@nuxt/docs-nightly 5.0.0-29807919.2cbde35e → 5.0.0-29809859.f0ca99e9

package/1.getting-started/18.upgrade.md

@@ -386,8 +386,6 @@ The `nitropack` package has been renamed to `nitro`. All import paths have chang
 | `nitropack/runtime` | `nitro` |
 | `h3` (for server utilities) | `nitro/h3` |
 
-Auto-imports within server routes (`defineEventHandler`, `getQuery`, `readBody`, `useRuntimeConfig`, etc.) continue to work without changes.
-
 If you have explicit imports in server code, update them:
 
 ```diff
@@ -400,12 +398,53 @@ If you have explicit imports in server code, update them:
 ```diff
 - declare module 'nitropack/types' {
 + declare module 'nitro/types' {
-    interface NitroRouteRules {
+    interface NitroRuntimeConfig {
       myModule?: { /* ... */ }
     }
   }
 ```
 
+Route rules are augmented on a different module again. See [Route Rule Types Move to `h3/rules`](#route-rule-types-move-to-h3rules).
+
+#### Server Auto-Imports Are Now Opt-In
+
+Nitro v3 removed its auto-import support, so utilities such as `defineEventHandler`, `getQuery`, `readBody` and `useRuntimeConfig` are no longer global in server code. Nuxt still provides them, but in Nuxt 5 they are off by default.
+
+Add explicit imports to your server code:
+
+```diff [server/api/hello.ts]
++ import { defineEventHandler, getQuery } from 'nitro/h3'
++
+  export default defineEventHandler((event) => {
+    return getQuery(event)
+  })
+```
+
+Or keep the previous behaviour while you migrate:
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    nitroAutoImports: true,
+  },
+})
+```
+
+This applies only to the utilities Nitro and h3 provide. Your own exports from `server/utils/` and `shared/utils/` are still auto-imported.
+
+#### `#imports` Is Deprecated in Server Code, in Favour of `#imports/server`
+
+Server code should import from `#imports/server`:
+
+```diff [server/api/hello.ts]
+- import { defineEventHandler } from '#imports'
++ import { defineEventHandler } from '#imports/server'
+
+  export default defineEventHandler(() => ({ hello: true }))
+```
+
+`#imports` still resolves when your server code runs, so an unmigrated project keeps working, but it is no longer typed: TypeScript reports it as unresolved until you move to `#imports/server`.
+
 #### Error Handling: `status`/`statusText` replace `statusCode`/`statusMessage`
 
 h3 v2 renames the error properties to align with Web standards:
@@ -513,9 +552,70 @@ If you define redirect route rules, the property name has changed:
   })
 ```
 
+Nuxt applies `statusCode` as `status` for now and warns, so an unmigrated rule keeps its status rather than silently falling back to the default. The fallback will be removed.
+
+#### Cached Route Rules Ignore Query Parameters
+
+Cached routes (`cache`, `swr`, `isr`) now key on the path only, and the query string is dropped before the handler runs. Set `allowQuery` to keep it, either as `true` or as a list of parameter names:
+
+```ts
+export default defineNuxtConfig({
+  routeRules: {
+    '/products': { cache: { swr: true, maxAge: 60, allowQuery: ['page'] } },
+  },
+})
+```
+
+#### Route Rule Types Move to `h3/rules`
+
+Nitro v3 builds route rules on h3, so custom route rules are declared there rather than on `nitro/types`. `NitroRouteConfig` and `NitroRouteRules` are still exported as deprecated aliases, but they are now type aliases rather than interfaces, so augmenting them fails with `TS2300: Duplicate identifier`.
+
+There are two interfaces to declare, and they are separate on purpose. `RouteRuleConfig` is what a rule looks like in `nuxt.config`, and `RouteRules` is what a matched rule looks like at runtime:
+
+```diff
+- declare module 'nitropack/types' {
+-   interface NitroRouteConfig {
++ declare module 'h3/rules' {
++   interface RouteRuleConfig {
+      myModule?: { enabled: boolean }
+    }
+-   interface NitroRouteRules {
++   interface RouteRules {
+      myModule?: { enabled: boolean }
+    }
+  }
+```
+
+A rule that nothing declares now reads back as `unknown` rather than `any`, so it needs a cast at the point of use:
+
+```diff
+- const enabled = rules.myUndeclaredRule
++ const enabled = rules.myUndeclaredRule as boolean | undefined
+```
+
+#### The Server `tsconfig.json` Is Generated by Nuxt
+
+Nuxt now generates `.nuxt/tsconfig.server.json` itself, as one of the tsconfigs it writes per environment, rather than delegating it to the server builder. If you extended it through Nitro, use the Nuxt option instead:
+
+```diff
+  export default defineNuxtConfig({
+-   nitro: {
+-     typescript: {
+-       tsConfig: { compilerOptions: { /* ... */ } },
+-     },
+-   },
++   typescript: {
++     serverTsConfig: { compilerOptions: { /* ... */ } },
++   },
+  })
+```
+
+`typescript.serverTsConfig` already existed in Nuxt 4 and was kept in sync with `nitro.typescript.tsConfig`, so this is a no-op if you were already using it.
+
 #### For Module Authors: Additional Changes
 
-- **Nitro plugin imports**: Use `import { definePlugin } from 'nitro'` for explicit imports (auto-imports still work).
+- **Nitro plugin imports**: Use `import { definePlugin } from 'nitro'`, which is now required by default. See [Server Auto-Imports Are Now Opt-In](#server-auto-imports-are-now-opt-in).
+- **Route rule helpers**: `basicAuth` route rules are replaced by middleware, and a new `cors` rule replaces manual CORS wiring. See the [Nitro migration guide](https://nitro.build/docs/migration) for the runtime details.
 - **Runtime hooks**: `nitroApp.hooks.hook('beforeResponse', ...)` and `nitroApp.hooks.hook('afterResponse', ...)` have been replaced by `nitroApp.hooks.hook('response', ...)`.
 - **`getRouteRules()` from `nitro/app`**: On the server, the Nitro helper changed from `getRouteRules(event)` to `getRouteRules(method, pathname)`, which returns `{ routeRules }`.
 

package/3.guide/4.modules/5.recipes-advanced.md

@@ -144,9 +144,9 @@ export default defineNuxtModule({
         interface MyModuleNitroRules {
           myModule?: { foo: 'bar' }
         }
-        declare module 'nitro/types' {
-          interface NitroRouteRules extends MyModuleNitroRules {}
-          interface NitroRouteConfig extends MyModuleNitroRules {}
+        declare module 'h3/rules' {
+          interface RouteRules extends MyModuleNitroRules {}
+          interface RouteRuleConfig extends MyModuleNitroRules {}
         }
         export {}`,
     })

package/4.api/5.kit/7.pages.md

@@ -141,7 +141,7 @@ function extendRouteRules (route: string, rule: NitroRouteConfig, options?: Exte
 ### Parameters
 
 **route**: A route pattern to match against.\
-**rule**: A route rule configuration to apply to the matched route.
+**rule**: A route rule configuration to apply to the matched route. `NitroRouteConfig` is a union of `NitroRouteConfigV2` and `NitroRouteConfigV3`, so a rule has to be valid for one Nitro major as a whole. A few rules differ between them: Nitro v3 takes `redirect: { status }` where v2 takes `redirect: { statusCode }`, and v3 additionally accepts CORS options on `cors` and `false` on `redirect`/`proxy` to reset an inherited rule.
 
 ::tip
 About route rules configurations, you can get more detail in [Hybrid Rendering > Route Rules](/docs/4.x/guide/concepts/rendering#route-rules).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxt/docs-nightly",
-  "version": "5.0.0-29807919.2cbde35e",
+  "version": "5.0.0-29809859.f0ca99e9",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nuxt/nuxt.git",