Skip to content

fix: support Nitro 2 and 3 server runtimes - #844

Merged
harlan-zw merged 6 commits into
nuxt:mainfrom
onmax:agent/support-nitro-2-and-3
Aug 4, 2026
Merged

fix: support Nitro 2 and 3 server runtimes#844
harlan-zw merged 6 commits into
nuxt:mainfrom
onmax:agent/support-nitro-2-and-3

Conversation

@onmax

@onmax onmax commented Jul 24, 2026

Copy link
Copy Markdown
Contributor

🔗 Linked issue

N/A

❓ Type of change

  • 📖 Documentation
  • 🐞 Bug fix
  • 👌 Enhancement
  • ✨ New feature
  • 🧹 Chore
  • ⚠️ Breaking change

📚 Description

Nuxt 5 uses Nitro 3, which splits APIs previously exported by nitropack/runtime across nitro/app, nitro/cache, and nitro/runtime-config. Bare Nitro imports fail under strict pnpm isolation because Nuxt Scripts cannot depend directly on Nitro.

This adds scoped #nuxt-scripts/nitro and #nuxt-scripts/h3 compatibility modules. Nitro 2 re-exports its existing runtime APIs. Nitro 3 entrypoints resolve through Nuxt's installed @nuxt/nitro-server package. Server runtime files now use explicit scoped imports instead of ambient globals.

Unit tests cover both compatibility paths. CI typechecks and runs the proxy fixture against Nuxt 5 and Nitro 3, while the existing suite covers Nuxt 4 and Nitro 2.

✅ Verification

  • pnpm lint
  • pnpm typecheck
  • pnpm build
  • Full suite: 963 passed, 6 skipped, 3 todo
  • Nuxt 4 and Nitro 2 proxy E2E: 4 passed
  • Strict isolated Nuxt 5 and Nitro 3 typecheck and proxy E2E: 4 passed

@vercel

vercel Bot commented Jul 24, 2026

Copy link
Copy Markdown
Contributor

@onmax is attempting to deploy a commit to the Nuxt Team on Vercel.

A member of the Team first needs to authorize it.

@pkg-pr-new

pkg-pr-new Bot commented Jul 24, 2026

Copy link
Copy Markdown

Open in StackBlitz

npm i https://pkg.pr.new/@nuxt/scripts@844

commit: 81cd5da

@onmax
onmax force-pushed the agent/support-nitro-2-and-3 branch 2 times, most recently from 2b82982 to 346d651 Compare July 24, 2026 09:06
@onmax
onmax force-pushed the agent/support-nitro-2-and-3 branch from 346d651 to 5886d49 Compare August 3, 2026 13:13
@onmax
onmax marked this pull request as ready for review August 3, 2026 13:22
@coderabbitai

coderabbitai Bot commented Aug 3, 2026

Copy link
Copy Markdown

Review Change Stack

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

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: c9fd9b16-79e4-4fc4-975b-e603b1cdac09

📥 Commits

Reviewing files that changed from the base of the PR and between 5d575c4 and 81cd5da.

📒 Files selected for processing (2)
  • packages/script/src/nitro-compatibility.ts
  • test/unit/nitro-compatibility.test.ts
🚧 Files skipped from review as they are similar to previous changes (1)
  • test/unit/nitro-compatibility.test.ts

📝 Walkthrough

Walkthrough

The module adds Nitro v2 and Nitro v3 runtime compatibility setup. Server files now use project-local H3 and Nitro aliases. Runtime configuration access no longer passes request events. Tests, proxy-alias fixtures, Vitest aliases, and a Nitro 3 CI job validate the integration.

Estimated code review effort: 3 (Moderate) | ~25 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly summarizes the main change: adding support for Nitro 2 and Nitro 3 server runtimes.
Description check ✅ Passed The description directly explains the Nitro compatibility changes, scoped modules, runtime updates, tests, and verification.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches 💡 1
🛠️ Fix failing CI checks 💡
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🧹 Nitpick comments (2)
packages/script/src/module.ts (1)

521-530: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick win

Fail fast when a Nitro runtime helper cannot be resolved.

At Line [524], resolveNuxtPath() can return a normalized input when resolution fails. pathToFileURL() can then create a file: URL for a nonexistent path. Validate each resolved file before registering the imports. The @nuxt/kit resolver documents this fallback behavior. (nuxt.com)

Proposed validation
-      const resolveNitroImport = async (id: string) => pathToFileURL(await resolveNuxtPath(id, { cwd: nitroDir })).href
+      const resolveNitroImport = async (id: string) => {
+        const resolved = await resolveNuxtPath(id, { cwd: nitroDir })
+        if (!existsSync(resolved))
+          throw new Error(`[nuxt-scripts] Could not resolve Nitro runtime helper "${id}" from "${nitroDir}".`)
+        return pathToFileURL(resolved).href
+      }
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/script/src/module.ts` around lines 521 - 530, Update the Nitro
import setup in the Nuxt version branch, especially resolveNitroImport, to
verify each resolved helper file exists before converting it with pathToFileURL
or registering it through addServerImports. Fail immediately when resolution
returns a nonexistent fallback path, and preserve registration only for valid
Nitro runtime helpers.
.github/workflows/ci.yml (1)

173-174: 🔒 Security & Privacy | 🔵 Trivial | ⚡ Quick win

Run the unknown-alias security test in the Nitro 3 job.

Line [174] skips the rejects an unknown alias segment test in test/e2e/proxy-alias.test.ts at Lines [24] through [27]. An allowlist regression can therefore pass the Nitro 3 job. Add rejects to the filter or run the complete proxy-alias test file.

Proposed CI change
-        run: pnpm vitest run --project e2e test/e2e/proxy-alias.test.ts -t 'auto-injects|resolves'
+        run: pnpm vitest run --project e2e test/e2e/proxy-alias.test.ts -t 'auto-injects|rejects|resolves'
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/ci.yml around lines 173 - 174, Update the “Run Nitro 3
compatibility tests” step to include the `rejects` test pattern in its Vitest
filter, or run the complete test/e2e/proxy-alias.test.ts file, so the
unknown-alias rejection coverage executes alongside the existing auto-injects
and resolves tests.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@test/e2e/proxy-alias.test.ts`:
- Line 41: Remove the status assertion from the live-upstream test so a valid
alias is not rejected when Plausible returns an uncontrolled HTTP 500; cover
local Nitro runtime failures separately with a controlled upstream fixture or
unit test.

---

Nitpick comments:
In @.github/workflows/ci.yml:
- Around line 173-174: Update the “Run Nitro 3 compatibility tests” step to
include the `rejects` test pattern in its Vitest filter, or run the complete
test/e2e/proxy-alias.test.ts file, so the unknown-alias rejection coverage
executes alongside the existing auto-injects and resolves tests.

In `@packages/script/src/module.ts`:
- Around line 521-530: Update the Nitro import setup in the Nuxt version branch,
especially resolveNitroImport, to verify each resolved helper file exists before
converting it with pathToFileURL or registering it through addServerImports.
Fail immediately when resolution returns a nonexistent fallback path, and
preserve registration only for valid Nitro runtime helpers.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 9a1faeb1-1bf7-410a-9d33-fda6a68e809d

📥 Commits

Reviewing files that changed from the base of the PR and between 1af4423 and 5886d49.

📒 Files selected for processing (19)
  • .github/workflows/ci.yml
  • packages/script/src/module.ts
  • packages/script/src/runtime/server/bluesky-embed.ts
  • packages/script/src/runtime/server/google-maps-geocode-proxy.ts
  • packages/script/src/runtime/server/google-static-maps-proxy.ts
  • packages/script/src/runtime/server/gravatar-proxy.ts
  • packages/script/src/runtime/server/instagram-embed.ts
  • packages/script/src/runtime/server/proxy-handler.ts
  • packages/script/src/runtime/server/utils/cached-upstream.ts
  • packages/script/src/runtime/server/utils/withSigning.ts
  • packages/script/src/runtime/server/x-embed.ts
  • test/e2e/proxy-alias.test.ts
  • test/fixtures/proxy-alias/nuxt.config.ts
  • test/unit/__mocks__/stub-nitro-runtime.ts
  • test/unit/cached-upstream.test.ts
  • test/unit/proxy-handler-alias.test.ts
  • test/unit/proxy-handler-body.test.ts
  • test/unit/proxy-handler-hop-by-hop.test.ts
  • test/unit/with-signing.test.ts
💤 Files with no reviewable changes (5)
  • packages/script/src/runtime/server/gravatar-proxy.ts
  • packages/script/src/runtime/server/proxy-handler.ts
  • packages/script/src/runtime/server/google-static-maps-proxy.ts
  • packages/script/src/runtime/server/utils/cached-upstream.ts
  • packages/script/src/runtime/server/google-maps-geocode-proxy.ts

Comment thread test/e2e/proxy-alias.test.ts Outdated
@harlan-zw
harlan-zw merged commit aa88c3c into nuxt:main Aug 4, 2026
14 of 16 checks passed
harlan-zw added a commit that referenced this pull request Aug 13, 2026
Co-authored-by: Harlan Wilton <harlan@harlanzw.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants