fix(nuxt): follow Nuxt module conventions for server-side imports by wobsoriano · Pull Request #8439 · clerk/javascript

wobsoriano · 2026-05-01T15:57:43Z

Description

All h3 server runtime symbols (createError, eventHandler, setResponseHeader, etc.) are now imported from '#imports' instead of directly from 'h3'. This matches the convention used by the official Nuxt module builder. Nuxt server files are expected to consume auto-import symbols through '#imports', which Nuxt/Nitro resolves at app build time.

useRuntimeConfig was already imported this way. This change extends the same pattern to all remaining h3 value imports across clerkMiddleware.ts, utils.ts, routeMatcher.ts, and webhooks.ts.

Since h3 is no longer a direct runtime import, it has been moved from dependencies to devDependencies. Any Nuxt app already has h3 transitively via Nuxt itself, so this is non-breaking.

Type safety

To keep import { ... } from '#imports' fully typed during module development (without switching from tsup), a local declaration stub at src/runtime/types/nitro-server.d.ts re-exports the relevant h3 symbols and is mapped via paths["#imports"] in tsconfig.json.

Checklist

pnpm test runs as expected.
pnpm build runs as expected.
(If applicable) JSDoc comments have been added or updated for any package exports
(If applicable) Documentation has been updated

Type of change

vercel · 2026-05-01T15:57:48Z

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Skipped		May 1, 2026 4:32pm

changeset-bot · 2026-05-01T15:57:48Z

🦋 Changeset detected

Latest commit: 11757e1

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@clerk/nuxt	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

coderabbitai · 2026-05-01T15:59:17Z

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

@coderabbitai resume to resume automatic reviews.
@coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

▶️ Resume reviews
🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds a Nuxt #imports TypeScript path alias and a new packages/nuxt/src/runtime/types/nitro-server.d.ts that re-exports selected h3 APIs and declares useRuntimeConfig. Adjusts imports across the server runtime and tests to source h3 helpers and useRuntimeConfig via #imports (removing prior // @ts-expect-error`` workarounds) and updates a Vitest #imports mock to async-import and forward `h3` helpers. Changes middleware typing to use `EventHandler` explicitly. Updates `packages/nuxt/package.json` (downgrade to 2.2.10; moves `h3` to devDependencies), adds tsconfig paths, and creates a changeset. No runtime control flow or exported API behavior changed.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main objective: refactoring server imports to follow Nuxt module conventions by using '#imports' instead of direct 'h3' imports.
Linked Issues check	✅ Passed	The PR fully addresses issue `#8430` by changing all h3 server-runtime symbol imports from direct 'h3' imports to '#imports' pattern, moving h3 to devDependencies, and adding type safety through nitro-server.d.ts declaration stub.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to resolving `#8430`: import reorganization, package.json dependency classification, test mock updates, tsconfig path configuration, and a changeset entry. No unrelated modifications detected.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description check	✅ Passed	The pull request description clearly explains the changes: moving h3 imports to '#imports' convention, moving h3 to devDependencies, and adding a type declaration file for type safety.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

Generate code and open pull requests
Plan features and break down work
Investigate incidents and troubleshoot customer tickets together
Automate recurring tasks and respond to alerts with triggers
Summarize progress and report instantly

Built for teams:

Shared memory across your entire org—no repeating context
Per-thread sandboxes to safely plan and execute work
Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get your free trial and get 200 agent minutes per Slack user (a $50 value).

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

pkg-pr-new · 2026-05-01T16:11:08Z

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@8439

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@8439

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@8439

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@8439

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@8439

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@8439

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@8439

@clerk/express

npm i https://pkg.pr.new/@clerk/express@8439

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@8439

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@8439

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@8439

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@8439

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@8439

@clerk/react

npm i https://pkg.pr.new/@clerk/react@8439

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@8439

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@8439

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@8439

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@8439

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@8439

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@8439

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@8439

commit: 11757e1

Fixes #8430 Imports h3 server runtime symbols from '#imports' (the Nuxt virtual module) instead of directly from 'h3', matching the convention used by the official Nuxt module builder. This removes a conflict with Nitro's unimport auto-import injection, which generated a virtual auto-imports module referencing H3Error, H3Event, etc. without emitting their import statements when @clerk/nuxt server files were present in the bundle. A local type stub (src/runtime/types/nitro-server.d.ts) re-exports the h3 symbols from their real package and is wired up via a paths["#imports"] alias in tsconfig.json, preserving full type safety during module development without switching from tsup. The stub is not included in the published dist. Since no @clerk/nuxt server file has a direct runtime import from 'h3' anymore, h3 is moved from dependencies to devDependencies. Nuxt apps already have h3 as a transitive dependency, so this is non-breaking.

wobsoriano · 2026-05-01T17:16:14Z

!snapshot

github-actions · 2026-05-01T17:19:58Z

Hey @wobsoriano - the snapshot version command generated the following package versions:

Package	Version
@clerk/astro	3.1.1-snapshot.v20260501171802
@clerk/backend	3.4.5-snapshot.v20260501171802
@clerk/chrome-extension	3.1.22-snapshot.v20260501171802
@clerk/clerk-js	6.8.1-snapshot.v20260501171802
@clerk/dev-cli	0.1.1-snapshot.v20260501171802
@clerk/expo	3.2.8-snapshot.v20260501171802
@clerk/expo-passkeys	1.0.21-snapshot.v20260501171802
@clerk/express	2.1.13-snapshot.v20260501171802
@clerk/fastify	3.1.23-snapshot.v20260501171802
@clerk/hono	0.1.23-snapshot.v20260501171802
@clerk/localizations	4.5.9-snapshot.v20260501171802
@clerk/msw	0.0.21-snapshot.v20260501171802
@clerk/nextjs	7.3.1-snapshot.v20260501171802
@clerk/nuxt	2.3.1-snapshot.v20260501171802
@clerk/react	6.5.1-snapshot.v20260501171802
@clerk/react-router	3.2.1-snapshot.v20260501171802
@clerk/shared	4.9.1-snapshot.v20260501171802
@clerk/tanstack-react-start	1.2.1-snapshot.v20260501171802
@clerk/testing	2.0.25-snapshot.v20260501171802
@clerk/ui	1.7.1-snapshot.v20260501171802
@clerk/upgrade	2.0.3-snapshot.v20260501171802
@clerk/vue	2.1.1-snapshot.v20260501171802

Tip: Use the snippet copy button below to quickly install the required packages.
@clerk/astro

npm i @clerk/astro@3.1.1-snapshot.v20260501171802 --save-exact

@clerk/backend

npm i @clerk/backend@3.4.5-snapshot.v20260501171802 --save-exact

@clerk/chrome-extension

npm i @clerk/chrome-extension@3.1.22-snapshot.v20260501171802 --save-exact

@clerk/clerk-js

npm i @clerk/clerk-js@6.8.1-snapshot.v20260501171802 --save-exact

@clerk/dev-cli

npm i @clerk/dev-cli@0.1.1-snapshot.v20260501171802 --save-exact

@clerk/expo

npm i @clerk/expo@3.2.8-snapshot.v20260501171802 --save-exact

@clerk/expo-passkeys

npm i @clerk/expo-passkeys@1.0.21-snapshot.v20260501171802 --save-exact

@clerk/express

npm i @clerk/express@2.1.13-snapshot.v20260501171802 --save-exact

@clerk/fastify

npm i @clerk/fastify@3.1.23-snapshot.v20260501171802 --save-exact

@clerk/hono

npm i @clerk/hono@0.1.23-snapshot.v20260501171802 --save-exact

@clerk/localizations

npm i @clerk/localizations@4.5.9-snapshot.v20260501171802 --save-exact

@clerk/msw

npm i @clerk/msw@0.0.21-snapshot.v20260501171802 --save-exact

@clerk/nextjs

npm i @clerk/nextjs@7.3.1-snapshot.v20260501171802 --save-exact

@clerk/nuxt

npm i @clerk/nuxt@2.3.1-snapshot.v20260501171802 --save-exact

@clerk/react

npm i @clerk/react@6.5.1-snapshot.v20260501171802 --save-exact

@clerk/react-router

npm i @clerk/react-router@3.2.1-snapshot.v20260501171802 --save-exact

@clerk/shared

npm i @clerk/shared@4.9.1-snapshot.v20260501171802 --save-exact

@clerk/tanstack-react-start

npm i @clerk/tanstack-react-start@1.2.1-snapshot.v20260501171802 --save-exact

@clerk/testing

npm i @clerk/testing@2.0.25-snapshot.v20260501171802 --save-exact

@clerk/ui

npm i @clerk/ui@1.7.1-snapshot.v20260501171802 --save-exact

@clerk/upgrade

npm i @clerk/upgrade@2.0.3-snapshot.v20260501171802 --save-exact

@clerk/vue

npm i @clerk/vue@2.1.1-snapshot.v20260501171802 --save-exact

jacekradko · 2026-05-02T16:26:20Z

+    "@nuxt/schema": "^4.1.3"
  },
  "devDependencies": {
+    "h3": "^1.15.4",


Codex flagged h3 type imports that still need to come from direct dependencies. Might want to double check this

This package still exposes public declarations that import H3Event/EventHandler from h3 through @clerk/nuxt/server, @clerk/nuxt/webhooks, and helpers like createRouteMatcher. Moving h3 to devDependencies means strict package-manager installs can leave consumers unable to resolve those published declarations from @clerk/nuxt, even if Nuxt has h3 somewhere transitively. The runtime imports can come from #imports, but the package still needs to declare h3 as a dependency or peer dependency for its public type surface.

github-actions Bot added integration nuxt labels May 1, 2026

wobsoriano force-pushed the rob/fix-8430 branch from c3ce71a to b863462 Compare May 1, 2026 15:58

vercel Bot temporarily deployed to Preview May 1, 2026 15:58 Inactive

vercel Bot deployed to Preview May 1, 2026 15:59 View deployment

vercel Bot deployed to Preview May 1, 2026 16:01 View deployment

vercel Bot deployed to Preview May 1, 2026 16:03 View deployment

vercel Bot temporarily deployed to Preview May 1, 2026 16:04 Inactive

vercel Bot deployed to Preview May 1, 2026 16:08 View deployment

vercel Bot temporarily deployed to Preview May 1, 2026 16:25 Inactive

wobsoriano added 8 commits May 1, 2026 09:29

docs: add accounts portal OAuth consent refactor spec

387361b

chore: fix machine auth helper import sorting

1cc2447

chore: remove docs

6e9b916

chore: bump kit and schema deps to 4.4.1

3c6f4f2

chore: revert nuxt versions

0267bb3

chore: add changeset

31a985d

chore: revert nuxt versions

30da0af

wobsoriano force-pushed the rob/fix-8430 branch from e4e04c5 to 30da0af Compare May 1, 2026 16:29

vercel Bot deployed to Preview May 1, 2026 16:30 View deployment

chore: revert pkg version

11757e1

vercel Bot temporarily deployed to Preview May 1, 2026 16:32 Inactive

wobsoriano mentioned this pull request May 1, 2026

[clerk-nuxt] Auto-registered Nitro server middleware breaks h3 auto-imports — ReferenceError: H3Error is not defined #8430

Closed

4 tasks

jacekradko reviewed May 2, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix(nuxt): follow Nuxt module conventions for server-side imports#8439

fix(nuxt): follow Nuxt module conventions for server-side imports#8439
wobsoriano wants to merge 9 commits intomainfrom
rob/fix-8430

wobsoriano commented May 1, 2026 •

edited

Loading

Uh oh!

vercel Bot commented May 1, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented May 1, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented May 1, 2026 •

edited

Loading

Reviews paused

Walkthrough

Estimated code review effort

Uh oh!

pkg-pr-new Bot commented May 1, 2026 •

edited

Loading

Uh oh!

wobsoriano commented May 1, 2026

Uh oh!

github-actions Bot commented May 1, 2026

Uh oh!

jacekradko May 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

wobsoriano commented May 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Type safety

Checklist

Type of change

Uh oh!

vercel Bot commented May 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot Bot commented May 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

coderabbitai Bot commented May 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reviews paused

Walkthrough

Estimated code review effort

Uh oh!

pkg-pr-new Bot commented May 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

wobsoriano commented May 1, 2026

Uh oh!

github-actions Bot commented May 1, 2026

Uh oh!

jacekradko May 2, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

wobsoriano commented May 1, 2026 •

edited

Loading

vercel Bot commented May 1, 2026 •

edited

Loading

changeset-bot Bot commented May 1, 2026 •

edited

Loading

coderabbitai Bot commented May 1, 2026 •

edited

Loading

pkg-pr-new Bot commented May 1, 2026 •

edited

Loading