refactor(nitro,nuxt,schema): use augments for nitro schema types

[danielroe]

🔗 Linked issue

#33005

📚 Description

this prepares for #33005 by moving nitro-specific types out of nuxt/schema and into nitro builder.

the aim is to enable people to continue to use nuxt/kit and nuxt/schema v4 without requiring a major bump of these dependencies for nuxt v5.

[bolt-new-by-stackblitz]

Run & review this pull request in StackBlitz Codeflow.

[pkg-pr-new]

Open in StackBlitz

@nuxt/kit

npm i https://pkg.pr.new/@nuxt/kit@34039

@nuxt/nitro-server

npm i https://pkg.pr.new/@nuxt/nitro-server@34039

nuxt

npm i https://pkg.pr.new/nuxt@34039

@nuxt/rspack-builder

npm i https://pkg.pr.new/@nuxt/rspack-builder@34039

@nuxt/schema

npm i https://pkg.pr.new/@nuxt/schema@34039

@nuxt/vite-builder

npm i https://pkg.pr.new/@nuxt/vite-builder@34039

@nuxt/webpack-builder

npm i https://pkg.pr.new/@nuxt/webpack-builder@34039

commit: 0182c10

[codspeed-hq]

Merging this PR will not alter performance

Summary

✅ 10 untouched benchmarks

---

_{Comparing refactor/schema-nitro (0182c10) with main (8f4fbec)¹}

Footnotes

1. No successful run was found on main (3e1a6d1) during the generation of this report, so 8f4fbec was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[coderabbitai]

Caution

Review failed

The pull request is closed.

Walkthrough

This pull request refactors the Nuxt and Nitro integration architecture by moving Nitro-specific type augmentations and configurations from the main schema into a dedicated module augmentation layer within packages/nitro-server. The changes reorganise the public API surface by removing Nitro properties from the main schema interfaces whilst adding experimental configuration flags for backwards compatibility. TypeScript hoisting dependencies related to Nitro are removed from the default list and conditionally managed within the Nitro server package. Documentation files receive error annotation comments for type checking examples.

Possibly related PRs

• refactor(nitro,nuxt): extract @nuxt/nitro-server package #33462: Directly extracts Nitro server into a separate package with corresponding build configuration, schema, and type/server.builder changes.
• refactor(nuxt): move references addition to nitro:prepare:types hook #33286: Modifies Nitro type reference wiring within the nitro:prepare:types hook and related template triple-slash references.
• fix(nuxt): exempt nitro from import protections #31246: Changes import exclusion patterns and handling for Nitro auto-imports configuration.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch refactor/schema-nitro

---

📜 Recent review details

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 8f4fbec and 0182c10.

⛔ Files ignored due to path filters (2)

• packages/schema/package.json is excluded by !**/package.json
• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml, !pnpm-lock.yaml

📒 Files selected for processing (16)

• docs/1.getting-started/15.prerendering.md
• docs/1.getting-started/16.deployment.md
• docs/2.directory-structure/3.tsconfig.md
• docs/3.guide/1.concepts/1.rendering.md
• packages/nitro-server/src/augments.ts
• packages/nitro-server/src/index.ts
• packages/nuxt/src/core/nuxt.ts
• packages/nuxt/src/core/templates.ts
• packages/schema/build.config.ts
• packages/schema/src/config/experimental.ts
• packages/schema/src/config/typescript.ts
• packages/schema/src/index.ts
• packages/schema/src/types/config.ts
• packages/schema/src/types/debug.ts
• packages/schema/src/types/hooks.ts
• packages/schema/src/types/schema.ts

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[s1gr1d]

Hi @danielroe, this change results in an error when trying to use nuxtOptions.options.nitro. I created a reproduction for that: https://github.com/s1gr1d/reprex.nuxt-nitro-option-type

Is it possible to still expose the nitro option in the type?

This is related to this PR: getsentry/sentry-javascript#19249

[danielroe]

sorry about that! yes, I'm aware, and this affects other modules like @nuxtjs/i18n. I think this is probably something to resolve in @nuxt/module-builder .

as a hotfix, you might also be able (I think) to install @nuxt/nitro-server as a dev dependency and, if necessary,
add it to your tsconfig types.