@nuxt/docs-nightly 4.5.1-29752449.30d24817 → 4.5.2-2610052030-052d82e

package/2.directory-structure/1.app/1.utils.md

@@ -5,7 +5,7 @@ description: Use the utils/ directory to auto-import your utility functions thro
 navigation.icon: i-vscode-icons-folder-type-tools
 ---
 
-The main purpose of the [`app/utils/` directory](/docs/4.x/directory-structure/app/utils) is to allow a semantic distinction between your Vue composables and other auto-imported utility functions.
+The main purpose of the [`app/utils/` directory](/docs/directory-structure/app/utils) is to allow a semantic distinction between your Vue composables and other auto-imported utility functions.
 
 ## Usage
 
@@ -35,15 +35,19 @@ You can now use auto imported utility functions in `.js`, `.ts` and `.vue` files
 </template>
 ```
 
-:read-more{to="/docs/4.x/guide/concepts/auto-imports"}
+:read-more{to="/docs/guide/concepts/auto-imports"}
 
-:link-example{to="/docs/4.x/examples/features/auto-imports"}
+:link-example{to="/docs/examples/features/auto-imports"}
 
 ::tip
-The way `app/utils/` auto-imports work and are scanned is identical to the [`app/composables/`](/docs/4.x/directory-structure/app/composables) directory.
+The way `app/utils/` auto-imports work and are scanned is identical to the [`app/composables/`](/docs/directory-structure/app/composables) directory.
 ::
 
 ::important
 These utils are only available within the Vue part of your app. :br
-Only `server/utils` are auto-imported in the [`server/`](/docs/4.x/directory-structure/server#server-utilities) directory.
+Only `server/utils` are auto-imported in the [`server/`](/docs/directory-structure/server#server-utilities) directory.
+::
+
+::tip
+Types can be auto-imported the same way. Put app-only types in `app/types/`, server-only types in [`server/types/`](/docs/directory-structure/server#server-types), and types shared between both in [`shared/types/`](/docs/directory-structure/shared).
 ::

package/2.directory-structure/1.app/3.app-config.md

@@ -20,7 +20,7 @@ Do not put any secret values inside `app.config` file. It is exposed to the user
 ::
 
 ::note
-When configuring a custom [`srcDir`](/docs/4.x/api/nuxt-config#srcdir), make sure to place the `app.config` file at the root of the new `srcDir` path.
+When configuring a custom [`srcDir`](/docs/api/nuxt-config#srcdir), make sure to place the `app.config` file at the root of the new `srcDir` path.
 ::
 
 ## Usage
@@ -35,7 +35,7 @@ export default defineAppConfig({
 })
 ```
 
-We can now universally access `theme` both when server-rendering the page and in the browser using [`useAppConfig`](/docs/4.x/api/composables/use-app-config) composable.
+We can now universally access `theme` both when server-rendering the page and in the browser using [`useAppConfig`](/docs/api/composables/use-app-config) composable.
 
 ```vue [app/pages/index.vue]
 <script setup lang="ts">
@@ -45,7 +45,7 @@ console.log(appConfig.theme)
 </script>
 ```
 
-The [`updateAppConfig`](/docs/4.x/api/utils/update-app-config) utility can be used to update the `app.config` at runtime.
+The [`updateAppConfig`](/docs/api/utils/update-app-config) utility can be used to update the `app.config` at runtime.
 
 ```vue [app/pages/index.vue]
 <script setup>
@@ -59,7 +59,7 @@ console.log(appConfig) // { foo: 'baz' }
 </script>
 ```
 
-::read-more{to="/docs/4.x/api/utils/update-app-config"}
+::read-more{to="/docs/api/utils/update-app-config"}
 Read more about the `updateAppConfig` utility.
 ::
 
@@ -67,7 +67,7 @@ Read more about the `updateAppConfig` utility.
 
 Nuxt tries to automatically generate a TypeScript interface from provided app config so you won't have to type it yourself.
 
-The fully inferred type is only available in app code (components, composables, plugins and so on). In server routes, code in the `shared/` directory and `nuxt.config`, keys defined in `app.config` files are typed as `unknown` instead: typing them there would require typechecking your app code outside the app context, where app auto-imports are not available. Keys defined inline in the `appConfig` option of `nuxt.config` are typed everywhere. If you need other keys typed outside app code, you can extend the `AppConfig` interface as described below. The location of the augmentation file determines which contexts see it: a `.d.ts` file in the `shared/` directory covers app code, shared code and server routes.
+The fully inferred type is only available in app code (components, composables, plugins and so on). In server routes, code in the `shared/` directory and `nuxt.config`, keys defined in `app.config` files are typed as `unknown` instead: typing them there would require typechecking your app code outside the app context, where app auto-imports are not available. Keys defined inline in the `appConfig` option of `nuxt.config` are typed everywhere. If you need other keys typed outside app code, you can extend the `SharedAppConfig` interface as described below. The location of the augmentation file determines which contexts see it: a `.d.ts` file in the `shared/` directory covers app code, shared code and server routes.
 
 However, there are some cases where you might want to type it yourself. There are two possible things you might want to type.
 
@@ -92,7 +92,7 @@ export {}
 
 ### App Config Output
 
-If you want to type the result of calling [`useAppConfig()`](/docs/4.x/api/composables/use-app-config), then you will want to extend `AppConfig`.
+If you want to type the result of calling [`useAppConfig()`](/docs/api/composables/use-app-config) in app code, then you will want to extend `AppConfig`. Outside app code (server routes, the `shared/` directory and `nuxt.config`) `useAppConfig()` returns `SharedAppConfig`, so extend that interface instead.
 
 ::warning
 Be careful when typing `AppConfig` as you will overwrite the types Nuxt infers from your actually defined app config.
@@ -116,7 +116,7 @@ export {}
 
 ## Merging Strategy
 
-Nuxt uses a custom merging strategy for the `AppConfig` within [the layers](/docs/4.x/getting-started/layers) of your application.
+Nuxt uses a custom merging strategy for the `AppConfig` within [the layers](/docs/getting-started/layers) of your application.
 
 This strategy is implemented using a [Function Merger](https://github.com/unjs/defu#function-merger), which allows defining a custom merging strategy for every key in `app.config` that has an array as value.
 

package/2.directory-structure/1.app/3.app.md

@@ -13,7 +13,7 @@ If you have a `app/pages/` directory, the `app.vue` file is optional. Nuxt will
 
 ### Minimal Usage
 
-With Nuxt, the [`app/pages/`](/docs/4.x/directory-structure/app/pages) directory is optional. If it is not present, Nuxt will not include the [vue-router](https://router.vuejs.org) dependency. This is useful when building a landing page or an application that does not require routing.
+With Nuxt, the [`app/pages/`](/docs/directory-structure/app/pages) directory is optional. If it is not present, Nuxt will not include the [vue-router](https://router.vuejs.org) dependency. This is useful when building a landing page or an application that does not require routing.
 
 ```vue [app/app.vue]
 <template>
@@ -21,11 +21,11 @@ With Nuxt, the [`app/pages/`](/docs/4.x/directory-structure/app/pages) directory
 </template>
 ```
 
-:link-example{to="/docs/4.x/examples/hello-world"}
+:link-example{to="/docs/examples/hello-world"}
 
 ### Usage with Pages
 
-When you have a [`app/pages/`](/docs/4.x/directory-structure/app/pages) directory, you need to use the [`<NuxtPage>`](/docs/4.x/api/components/nuxt-page) component to display the current page:
+When you have a [`app/pages/`](/docs/directory-structure/app/pages) directory, you need to use the [`<NuxtPage>`](/docs/api/components/nuxt-page) component to display the current page:
 
 ```vue [app/app.vue]
 <template>
@@ -51,13 +51,13 @@ You can also define the common structure of your application directly in `app.vu
 Remember that `app.vue` acts as the main component of your Nuxt application. Anything you add to it (JS and CSS) will be global and included in every page.
 ::
 
-::read-more{to="/docs/4.x/directory-structure/app/pages"}
+::read-more{to="/docs/directory-structure/app/pages"}
 Learn more about how to structure your pages using the `app/pages/` directory.
 ::
 
 ### Usage with Layouts
 
-When your application requires different layouts for different pages, you can use the `app/layouts/` directory with the [`<NuxtLayout>`](/docs/4.x/api/components/nuxt-layout) component. This allows you to define multiple layouts and apply them per page.
+When your application requires different layouts for different pages, you can use the `app/layouts/` directory with the [`<NuxtLayout>`](/docs/api/components/nuxt-layout) component. This allows you to define multiple layouts and apply them per page.
 
 ```vue [app/app.vue]
 <template>
@@ -67,6 +67,6 @@ When your application requires different layouts for different pages, you can us
 </template>
 ```
 
-::read-more{to="/docs/4.x/directory-structure/app/layouts"}
+::read-more{to="/docs/directory-structure/app/layouts"}
 Learn more about how to structure your layouts using the `app/layouts/` directory.
 ::

package/2.directory-structure/1.app/3.error.md

@@ -23,7 +23,7 @@ const props = defineProps<{ error: NuxtError }>()
 ```
 
 ::note
-Although it is called an 'error page' it's not a route and shouldn't be placed in your `~/pages` directory. For the same reason, you shouldn't use `definePageMeta` within this page. That being said, you can still use layouts in the error file, by utilizing the [`NuxtLayout`](/docs/4.x/api/components/nuxt-layout) component and specifying the name of the layout.
+Although it is called an 'error page' it's not a route and shouldn't be placed in your `~/pages` directory. For the same reason, you shouldn't use `definePageMeta` within this page. That being said, you can still use layouts in the error file, by utilizing the [`NuxtLayout`](/docs/api/components/nuxt-layout) component and specifying the name of the layout.
 ::
 
 The error page has a single prop - `error` which contains an error for you to handle.

package/2.directory-structure/1.content.md

@@ -36,7 +36,7 @@ The module automatically loads and parses them.
 
 ## Render Content
 
-To render content pages, add a [catch-all route](/docs/4.x/directory-structure/app/pages/#catch-all-route) using the [`<ContentRenderer>`](https://content.nuxt.com/docs/components/content-renderer) component:
+To render content pages, add a [catch-all route](/docs/directory-structure/app/pages/#catch-all-route) using the [`<ContentRenderer>`](https://content.nuxt.com/docs/components/content-renderer) component:
 
 ```vue [app/pages/[...slug\\].vue]
 <script lang="ts" setup>

package/2.directory-structure/1.layers.md

@@ -64,17 +64,17 @@ Named layer aliases were introduced in Nuxt v3.16.0.
 
 Each layer can include:
 
-- [`nuxt.config.ts`](/docs/4.x/directory-structure/nuxt-config) - Layer-specific configuration that will be merged with the main config
-- [`app.config.ts`](/docs/4.x/directory-structure/app/app-config) - Reactive application configuration
-- [`app/components/`](/docs/4.x/directory-structure/app/components) - Vue components (auto-imported)
-- [`app/composables/`](/docs/4.x/directory-structure/app/composables) - Vue composables (auto-imported)
-- [`app/utils/`](/docs/4.x/directory-structure/app/utils) - Utility functions (auto-imported)
-- [`app/pages/`](/docs/4.x/directory-structure/app/pages) - Application pages
-- [`app/layouts/`](/docs/4.x/directory-structure/app/layouts) - Application layouts
-- [`app/middleware/`](/docs/4.x/directory-structure/app/middleware) - Route middleware
-- [`app/plugins/`](/docs/4.x/directory-structure/app/plugins) - Nuxt plugins
-- [`server/`](/docs/4.x/directory-structure/server) - Server routes, middleware, and utilities
-- [`shared/`](/docs/4.x/directory-structure/shared) - Shared code between app and server
+- [`nuxt.config.ts`](/docs/directory-structure/nuxt-config) - Layer-specific configuration that will be merged with the main config
+- [`app.config.ts`](/docs/directory-structure/app/app-config) - Reactive application configuration
+- [`app/components/`](/docs/directory-structure/app/components) - Vue components (auto-imported)
+- [`app/composables/`](/docs/directory-structure/app/composables) - Vue composables (auto-imported)
+- [`app/utils/`](/docs/directory-structure/app/utils) - Utility functions (auto-imported)
+- [`app/pages/`](/docs/directory-structure/app/pages) - Application pages
+- [`app/layouts/`](/docs/directory-structure/app/layouts) - Application layouts
+- [`app/middleware/`](/docs/directory-structure/app/middleware) - Route middleware
+- [`app/plugins/`](/docs/directory-structure/app/plugins) - Nuxt plugins
+- [`server/`](/docs/directory-structure/server) - Server routes, middleware, and utilities
+- [`shared/`](/docs/directory-structure/shared) - Shared code between app and server
 
 ## Priority Order
 
@@ -82,8 +82,8 @@ When multiple layers define the same resource (component, composable, page, etc.
 
 To control the order, prefix directories with numbers: `1.base/`, `2.features/`, `3.admin/`.
 
-Alternatively, reference the directories in [`extends`](/docs/4.x/api/nuxt-config#extends) (e.g. `extends: ['~~/layers/admin', '~~/layers/base']`) to order them from `nuxt.config` without renaming, with the first entry taking the highest priority.
+Alternatively, reference the directories in [`extends`](/docs/api/nuxt-config#extends) (e.g. `extends: ['~~/layers/admin', '~~/layers/base']`) to order them from `nuxt.config` without renaming, with the first entry taking the highest priority.
 
-:read-more{to="/docs/4.x/getting-started/layers#layer-priority"}
+:read-more{to="/docs/getting-started/layers#layer-priority"}
 
 :video-accordion{title="Watch a video from Learn Vue about Nuxt Layers" videoId="lnFCM7c9f7I"}

package/2.directory-structure/1.modules.md

@@ -11,7 +11,7 @@ The auto-registered files patterns are:
 - `modules/*/index.ts`
 - `modules/*.ts`
 
-You don't need to add those local modules to your [`nuxt.config.ts`](/docs/4.x/directory-structure/nuxt-config) separately.
+You don't need to add those local modules to your [`nuxt.config.ts`](/docs/directory-structure/nuxt-config) separately.
 
 ::code-group
 
@@ -57,7 +57,7 @@ Note that all components, pages, composables and other files that would be norma
 ::
 
 Modules are executed in the following sequence:
-- First, the modules defined in [`nuxt.config.ts`](/docs/4.x/api/nuxt-config#modules-1) are loaded.
+- First, the modules defined in [`nuxt.config.ts`](/docs/api/nuxt-config#modules-1) are loaded.
 - Then, modules found in the `modules/` directory are executed, and they load in alphabetical order.
 
 You can change the order of local module by adding a number to the front of each directory name:
@@ -69,7 +69,7 @@ modules/
   2.second-module.ts
 ```
 
-:read-more{to="/docs/4.x/guide/modules"}
+:read-more{to="/docs/guide/modules"}
 
 ::tip{icon="i-lucide-video" to="https://vueschool.io/lessons/creating-your-first-module-from-scratch?friend=nuxt" target="_blank"}
 Watch Vue School video about Nuxt private modules.

package/2.directory-structure/1.node_modules.md

@@ -8,5 +8,5 @@ navigation.icon: i-vscode-icons-folder-type-node
 The package manager ([`npm`](https://docs.npmjs.com/cli/commands/npm/) or [`yarn`](https://yarnpkg.com) or [`pnpm`](https://pnpm.io/cli/install) or [`bun`](https://bun.com/package-manager) or [`deno`](https://docs.deno.com/runtime/getting_started/installation/)) creates this directory to store the dependencies of your project.
 
 ::important
-This directory should be added to your [`.gitignore`](/docs/4.x/directory-structure/gitignore) file to avoid pushing the dependencies to your repository.
+This directory should be added to your [`.gitignore`](/docs/directory-structure/gitignore) file to avoid pushing the dependencies to your repository.
 ::

package/2.directory-structure/1.server.md

@@ -25,7 +25,7 @@ The handler can directly return JSON data, a `Promise`, or use `event.node.res.e
 Do not import Vue app code (components, composables, or other app-only utilities) in your server routes or utilities, and do not import server-only code in your app.
 ::
 
-:read-more{to="/docs/4.x/directory-structure/shared#why-you-cannot-mix-vue-and-nitro-code" title="Why You Cannot Mix Vue and Nitro Code"}
+:read-more{to="/docs/directory-structure/shared#why-you-cannot-mix-vue-and-nitro-code" title="Why You Cannot Mix Vue and Nitro Code"}
 
 ```ts twoslash [server/api/hello.ts]
 export default defineEventHandler((event) => {
@@ -64,7 +64,7 @@ export default defineEventHandler(() => 'Hello World!')
 Given the example above, the `/hello` route will be accessible at <http://localhost:3000/hello>.
 
 ::note
-Note that currently server routes do not support the full functionality of dynamic routes as [pages](/docs/4.x/directory-structure/app/pages#dynamic-routes) do.
+Note that currently server routes do not support the full functionality of dynamic routes as [pages](/docs/directory-structure/app/pages#dynamic-routes) do.
 ::
 
 ## Server Middleware
@@ -160,7 +160,25 @@ The `#server` alias can only be used within the `server/` directory. Importing f
 
 Auto-imports and other types are different for the `server/` directory, as it is running in a different context from the `app/` directory.
 
-By default, Nuxt 4 generates a [`tsconfig.json`](/docs/4.x/directory-structure/tsconfig) which includes a project reference covering the `server/` folder which ensures accurate typings.
+By default, Nuxt 4 generates a [`tsconfig.json`](/docs/directory-structure/tsconfig) which includes a project reference covering the `server/` folder which ensures accurate typings.
+
+Types placed in `~~/server/types/` are auto-imported in the server context only, so you can reference them in server routes, middleware, plugins, and utilities without importing them. Types that are also needed in the Vue app belong in [`shared/types/`](/docs/directory-structure/shared) instead.
+
+```ts twoslash [server/types/todo.ts]
+export interface Todo {
+  id: string
+  title: string
+  completed: boolean
+}
+```
+
+```ts [server/api/todos.get.ts]
+export default defineEventHandler((): Todo[] => {
+  return []
+})
+```
+
+Only files directly in `server/types/` are scanned; files in nested subdirectories are not auto-imported, matching how [`shared/types/`](/docs/directory-structure/shared#how-files-are-scanned) works.
 
 ## Recipes
 
@@ -177,7 +195,7 @@ export default defineEventHandler((event) => {
 ```
 
 ::tip{to="https://h3.dev/examples/validate-data#validate-params"}
-Alternatively, use `getValidatedRouterParams` with a schema validator such as Zod for runtime and type safety.
+Alternatively, use `getValidatedRouterParams` with a schema validator such as Zod or Valibot for runtime and type safety.
 ::
 
 You can now universally call this API on `/api/hello/nuxt` and get `Hello, nuxt!`.
@@ -253,7 +271,7 @@ export default defineEventHandler(async (event) => {
 ```
 
 ::tip{to="https://unjs.io/blog/2023-08-15-h3-towards-the-edge-of-the-web/#runtime-type-safe-request-utils"}
-Alternatively, use `readValidatedBody` with a schema validator such as Zod for runtime and type safety.
+Alternatively, use `readValidatedBody` with a schema validator such as Zod or Valibot for runtime and type safety.
 ::
 
 You can now universally call this API using:
@@ -286,7 +304,7 @@ export default defineEventHandler((event) => {
 ```
 
 ::tip{to="https://unjs.io/blog/2023-08-15-h3-towards-the-edge-of-the-web#runtime-type-safe-request-utils"}
-Alternatively, use `getValidatedQuery` with a schema validator such as Zod for runtime and type safety.
+Alternatively, use `getValidatedQuery` with a schema validator such as Zod or Valibot for runtime and type safety.
 ::
 
 ### Error Handling
@@ -295,7 +313,7 @@ If no errors are thrown, a status code of `200 OK` will be returned.
 
 Any uncaught errors will return a `500 Internal Server Error` HTTP Error.
 
-To return other error codes, throw an exception with [`createError`](/docs/4.x/api/utils/create-error):
+To return other error codes, throw an exception with [`createError`](/docs/api/utils/create-error):
 
 ```ts [server/api/validation/[id\\].ts]
 export default defineEventHandler((event) => {
@@ -313,7 +331,7 @@ export default defineEventHandler((event) => {
 
 ### Status Codes
 
-To return other status codes, use the [`setResponseStatus`](/docs/4.x/api/utils/set-response-status) utility.
+To return other status codes, use the [`setResponseStatus`](/docs/api/utils/set-response-status) utility.
 
 For example, to return `202 Accepted`
 
@@ -352,7 +370,7 @@ NUXT_GITHUB_TOKEN='<my-super-token>'
 ::
 
 ::note
-Giving the `event` as argument to `useRuntimeConfig` is optional, but it is recommended to pass it to get the runtime config overwritten by [environment variables](/docs/4.x/guide/going-further/runtime-config#environment-variables) at runtime for server routes.
+Giving the `event` as argument to `useRuntimeConfig` is optional, but it is recommended to pass it to get the runtime config overwritten by [environment variables](/docs/guide/going-further/runtime-config#environment-variables) at runtime for server routes.
 ::
 
 ### Request Cookies
@@ -418,7 +436,7 @@ export default defineNuxtConfig({
 })
 ```
 
-:read-more{to="/docs/4.x/guide/concepts/server-engine"}
+:read-more{to="/docs/guide/concepts/server-engine"}
 
 ### Nested Router
 
@@ -438,12 +456,13 @@ export default useBase('/api/hello', router.handler)
 This is an experimental feature and is available in all environments.
 ::
 
+You can return streams directly from the event handler.
+
 ```ts [server/api/foo.get.ts]
 import fs from 'node:fs'
-import { sendStream } from 'h3'
 
-export default defineEventHandler((event) => {
-  return sendStream(event, fs.createReadStream('/path/to/file'))
+export default defineEventHandler(() => {
+  return fs.createReadStream('/path/to/file')
 })
 ```
 
@@ -480,7 +499,7 @@ Never combine `next()` callback with a legacy middleware that is `async` or retu
 
 ### Server Storage
 
-Nitro provides a cross-platform [storage layer](https://nitro.build/guide/storage). In order to configure additional storage mount points, you can use `nitro.storage`, or [server plugins](/docs/4.x/directory-structure/server#server-plugins).
+Nitro provides a cross-platform [storage layer](https://nitro.build/guide/storage). In order to configure additional storage mount points, you can use `nitro.storage`, or [server plugins](/docs/directory-structure/server#server-plugins).
 
 **Example of adding a Redis storage:**
 

package/2.directory-structure/1.shared.md

@@ -29,7 +29,9 @@ Server-only code (such as Node APIs, Nitro utilities, or server route handlers)
 
 ### Type-Only Imports
 
-`import type` is erased at compile time and does not pull runtime code into the other bundle, so importing only types across the boundary may appear to work. Even so, keep shared types (such as API response types) in `shared/types/`, where they are auto-imported in both contexts. This keeps the boundary clear, avoids accidentally turning a type import into a value import later, and matches Nuxt's separate [type contexts](/docs/4.x/guide/concepts/typescript#project-references) for app, server, and shared code.
+`import type` is erased at compile time and does not pull runtime code into the other bundle, so importing only types across the boundary may appear to work. Even so, keep shared types (such as API response types) in `shared/types/`, where they are auto-imported in both contexts. This keeps the boundary clear, avoids accidentally turning a type import into a value import later, and matches Nuxt's separate [type contexts](/docs/guide/concepts/typescript#project-references) for app, server, and shared code.
+
+Types that are only used in one context can live next to that context instead: `app/types/` is auto-imported in the Vue app only, and [`server/types/`](/docs/directory-structure/server#server-types) is auto-imported in the Nitro server only. Use `shared/types/` when a type is needed in both.
 
 :video-accordion{title="Watch a video from Vue School on sharing utils and types between app and server" videoId="nnAR-MO3q5M"}
 
@@ -51,7 +53,7 @@ export default function (input: string) {
 }
 ```
 
-You can now use [auto-imported](/docs/4.x/directory-structure/shared) utilities in your Nuxt app and `server/` directory.
+You can now use [auto-imported](/docs/directory-structure/shared) utilities in your Nuxt app and `server/` directory.
 
 ```vue [app/app.vue]
 <script setup lang="ts">
@@ -78,10 +80,10 @@ export default defineEventHandler((event) => {
 Only files in the `shared/utils/` and `shared/types/` directories will be auto-imported. Files nested within subdirectories of these directories will not be auto-imported unless you add these directories to `imports.dirs` and `nitro.imports.dirs`.
 
 ::tip
-The way `shared/utils` and `shared/types` auto-imports work and are scanned is identical to the [`app/composables/`](/docs/4.x/directory-structure/app/composables) and [`app/utils/`](/docs/4.x/directory-structure/app/utils) directories.
+The way `shared/utils` and `shared/types` auto-imports work and are scanned is identical to the [`app/composables/`](/docs/directory-structure/app/composables) and [`app/utils/`](/docs/directory-structure/app/utils) directories.
 ::
 
-:read-more{to="/docs/4.x/directory-structure/app/composables#how-files-are-scanned"}
+:read-more{to="/docs/directory-structure/app/composables#how-files-are-scanned"}
 
 ```bash [Directory Structure]
 -| shared/
@@ -111,4 +113,4 @@ import upper from '#shared/utils/formatters/upper'
 
 This alias ensures consistent imports across your application, regardless of the importing file's location.
 
-:read-more{to="/docs/4.x/guide/concepts/auto-imports"}
+:read-more{to="/docs/guide/concepts/auto-imports"}

package/2.directory-structure/1.test.md

@@ -0,0 +1,25 @@
+---
+title: 'test'
+head.title: 'test/'
+description: 'Use the test/ directory to organize unit, Nuxt, and end-to-end tests for your application.'
+navigation.icon: i-vscode-icons-folder-type-test
+---
+
+The `test/` directory is the recommended place for your application tests. Nuxt does not scan it the way it does `app/` or `server/`; you choose the runner and layout yourself (typically with [`@nuxt/test-utils`](/docs/getting-started/testing)).
+
+A common layout separates environments:
+
+```bash [Directory structure]
+-| test/
+---| e2e/
+---| nuxt/
+---| unit/
+```
+
+- `test/unit/` — fast Node tests without the Nuxt runtime
+- `test/nuxt/` — tests that need the Nuxt runtime environment
+- `test/e2e/` — end-to-end tests against a running app
+
+::read-more{to="/docs/getting-started/testing#organizing-your-tests"}
+See **Organizing Your Tests** for setup, Vitest projects, and TypeScript context.
+::

package/2.directory-structure/2.env.md

@@ -6,12 +6,12 @@ navigation.icon: i-vscode-icons-file-type-dotenv
 ---
 
 ::important
-This file should be added to your [`.gitignore`](/docs/4.x/directory-structure/gitignore) file to avoid pushing secrets to your repository.
+This file should be added to your [`.gitignore`](/docs/directory-structure/gitignore) file to avoid pushing secrets to your repository.
 ::
 
 ## Dev, Build and Generate Time
 
-Nuxt CLI has built-in [dotenv](https://github.com/motdotla/dotenv) support in development mode and when running [`nuxt build`](/docs/4.x/api/commands/build) and [`nuxt generate`](/docs/4.x/api/commands/generate).
+Nuxt CLI has built-in `.env` support via [c12](https://github.com/unjs/c12) in development mode and when running [`nuxt build`](/docs/api/commands/build) and [`nuxt generate`](/docs/api/commands/generate).
 
 In addition to any process environment variables, if you have a `.env` file in your project root directory, it will be automatically loaded **at dev, build and generate time**. Any environment variables set there will be accessible within your `nuxt.config` file and modules.
 
@@ -34,7 +34,7 @@ npx nuxt dev --dotenv .env.local
 When updating `.env` in development mode, the Nuxt instance is automatically restarted to apply new values to the `process.env`.
 
 ::important
-In your application code, you should use [Runtime Config](/docs/4.x/guide/going-further/runtime-config) instead of plain env variables.
+In your application code, you should use [Runtime Config](/docs/guide/going-further/runtime-config) instead of plain env variables.
 ::
 
 ## Production
@@ -56,12 +56,12 @@ Since `.env` files are not used in production, you must explicitly set environme
 * Many cloud service providers, such as Vercel, Netlify, and AWS, provide interfaces for setting environment variables via their dashboards, CLI tools or configuration files.
 
 ::important
-`runtimeConfig` [won't pick up environment variables that don't start with `NUXT_` in production] (https://nuxt.com/docs/4.x/guide/going-further/runtime-config#environment-variables).
+`runtimeConfig` [won't pick up environment variables that don't start with `NUXT_` in production] (/docs/guide/going-further/runtime-config#environment-variables).
 ::
 
 ## Production Preview
 
-For local production preview purpose, we recommend using [`nuxt preview`](/docs/4.x/api/commands/preview) since using this command, the `.env` file will be loaded into `process.env` for convenience. Note that this command requires dependencies to be installed in the package directory.
+For local production preview purpose, we recommend using [`nuxt preview`](/docs/api/commands/preview) since using this command, the `.env` file will be loaded into `process.env` for convenience. Note that this command requires dependencies to be installed in the package directory.
 
 Or you could pass the environment variables as arguments using the terminal. For example, on Linux or macOS:
 
@@ -71,9 +71,9 @@ NODE_ENV=production DATABASE_HOST=mydatabaseconnectionstring node .output/server
 
 Note that for a purely static site, it is not possible to set runtime configuration config after your project is prerendered.
 
-:read-more{to="/docs/4.x/guide/going-further/runtime-config"}
+:read-more{to="/docs/guide/going-further/runtime-config"}
 
 ::note
 If you want to use environment variables set at build time but do not care about updating these down the line (or only need to update them reactively _within_ your app) then `appConfig` may be a better choice. You can define `appConfig` both within your `nuxt.config` (using environment variables) and also within an `~/app.config.ts` file in your project.
-:read-more{to="/docs/4.x/directory-structure/app/app-config"}
+:read-more{to="/docs/directory-structure/app/app-config"}
 ::

package/2.directory-structure/2.nuxtignore.md

@@ -6,12 +6,12 @@ navigation.icon: i-vscode-icons-file-type-nuxt
 
 ---
 
-The `.nuxtignore` file tells Nuxt to ignore files in your project’s root directory ([`rootDir`](/docs/4.x/api/nuxt-config#rootdir)) during the build phase.
+The `.nuxtignore` file tells Nuxt to ignore files in your project’s root directory ([`rootDir`](/docs/api/nuxt-config#rootdir)) during the build phase.
 
-It is subject to the same specification as [`.gitignore`](/docs/4.x/directory-structure/gitignore) and `.eslintignore` files, in which each line is a glob pattern indicating which files should be ignored.
+It is subject to the same specification as [`.gitignore`](/docs/directory-structure/gitignore) and `.eslintignore` files, in which each line is a glob pattern indicating which files should be ignored.
 
 ::tip
-You can also configure [`ignoreOptions`](/docs/4.x/api/nuxt-config#ignoreoptions), [`ignorePrefix`](/docs/4.x/api/nuxt-config#ignoreprefix) and [`ignore`](/docs/4.x/api/nuxt-config#ignore) in your `nuxt.config` file.
+You can also configure [`ignoreOptions`](/docs/api/nuxt-config#ignoreoptions), [`ignorePrefix`](/docs/api/nuxt-config#ignoreprefix) and [`ignore`](/docs/api/nuxt-config#ignore) in your `nuxt.config` file.
 ::
 
 ## Usage

package/2.directory-structure/2.nuxtrc.md

@@ -8,7 +8,7 @@ navigation.icon: i-vscode-icons-file-type-nuxt
 The `.nuxtrc` file can be used to configure Nuxt with a flat syntax. It is based on [`unjs/rc9`](https://github.com/unjs/rc9).
 
 ::tip
-For more advanced configurations, use [`nuxt.config`](/docs/4.x/directory-structure/nuxt-config).
+For more advanced configurations, use [`nuxt.config`](/docs/directory-structure/nuxt-config).
 ::
 
 ## Usage
@@ -31,10 +31,10 @@ setups.@nuxt/test-utils="3.23.0"
 If present, the properties in the `nuxt.config` file will overwrite the properties in `.nuxtrc` file.
 
 ::note
-Nuxt automatically adds a `setups` section to track module installation and upgrade state. This is used internally for [module lifecycle hooks](/docs/4.x/api/kit/modules#using-lifecycle-hooks-for-module-installation-and-upgrade) and should not be modified manually.
+Nuxt automatically adds a `setups` section to track module installation and upgrade state. This is used internally for [module lifecycle hooks](/docs/api/kit/modules#using-lifecycle-hooks-for-module-installation-and-upgrade) and should not be modified manually.
 ::
 
-::read-more{to="/docs/4.x/api/configuration/nuxt-config"}
+::read-more{to="/docs/api/configuration/nuxt-config"}
 Discover all the available options in the **Nuxt configuration** documentation.
 ::
 

package/2.directory-structure/3.nuxt-config.md

@@ -27,8 +27,8 @@ export default defineNuxtConfig({
 })
 ```
 
-::read-more{to="/docs/4.x/api/configuration/nuxt-config"}
+::read-more{to="/docs/api/configuration/nuxt-config"}
 Discover all the available options in the **Nuxt configuration** documentation.
 ::
 
-To ensure your configuration is up to date, Nuxt will make a full restart when detecting changes in the main configuration file, the [`.env`](/docs/4.x/directory-structure/env), [`.nuxtignore`](/docs/4.x/directory-structure/nuxtignore) and [`.nuxtrc`](/docs/4.x/directory-structure/nuxtrc) dotfiles.
+To ensure your configuration is up to date, Nuxt will make a full restart when detecting changes in the main configuration file, the [`.env`](/docs/directory-structure/env), [`.nuxtignore`](/docs/directory-structure/nuxtignore) and [`.nuxtrc`](/docs/directory-structure/nuxtrc) dotfiles.

package/2.directory-structure/3.tsconfig.md

@@ -5,7 +5,7 @@ head.title: "tsconfig.json"
 navigation.icon: i-vscode-icons-file-type-tsconfig
 ---
 
-Nuxt [automatically generates](/docs/4.x/guide/concepts/typescript#auto-generated-types) multiple TypeScript configuration files (`.nuxt/tsconfig.app.json`, `.nuxt/tsconfig.server.json`, `.nuxt/tsconfig.node.json` and `.nuxt/tsconfig.shared.json`) that include recommended basic TypeScript configuration for your project, references to [auto-imports](/docs/4.x/guide/concepts/auto-imports), [API route types](/docs/4.x/guide/concepts/server-engine#typed-api-routes), path aliases, and more.
+Nuxt [automatically generates](/docs/guide/concepts/typescript#auto-generated-types) multiple TypeScript configuration files (`.nuxt/tsconfig.app.json`, `.nuxt/tsconfig.server.json`, `.nuxt/tsconfig.node.json` and `.nuxt/tsconfig.shared.json`) that include recommended basic TypeScript configuration for your project, references to [auto-imports](/docs/guide/concepts/auto-imports), [API route types](/docs/guide/concepts/server-engine#typed-api-routes), path aliases, and more.
 
 Your Nuxt project should include the following `tsconfig.json` file at the root of the project:
 
@@ -33,20 +33,26 @@ Your Nuxt project should include the following `tsconfig.json` file at the root
 We do not recommend modifying the contents of this file directly, as doing so could overwrite important settings that Nuxt or other modules rely on. Instead, extend it via `nuxt.config.ts`.
 ::
 
-::read-more{to="/docs/4.x/guide/concepts/typescript#project-references"}
+::read-more{to="/docs/guide/concepts/typescript#project-references"}
 Read more about the different type contexts of a Nuxt project here.
 ::
 
 ## Extending TypeScript Configuration
 
-You can customize the TypeScript configuration of your Nuxt project for each context (`app`, `shared`, `node`, and `server`) in the `nuxt.config.ts` file.
+You can customize the TypeScript configuration of your Nuxt project in the `nuxt.config.ts` file: set shared `compilerOptions` for every context at once with `typescript.tsConfig`, and override them for each context (`app`, `shared`, `node`, and `server`) individually.
 <!-- @case-police-ignore tsConfig -->
 ```ts twoslash [nuxt.config.ts]
 // @errors: 2353
 export default defineNuxtConfig({
   typescript: {
-    // customize tsconfig.app.json
+    // shared compiler options for every generated tsconfig
     tsConfig: {
+      compilerOptions: {
+        // ...
+      },
+    },
+    // customize tsconfig.app.json
+    appTsConfig: {
       // ...
     },
     // customize tsconfig.shared.json
@@ -57,14 +63,18 @@ export default defineNuxtConfig({
     nodeTsConfig: {
       // ...
     },
-  },
-  nitro: {
-    typescript: {
-      // customize tsconfig.server.json
-      tsConfig: {
-        // ...
-      },
+    // customize tsconfig.server.json
+    serverTsConfig: {
+      // ...
     },
   },
 })
 ```
+
+::note
+Most `compilerOptions` set in `typescript.tsConfig` are shared with every context, but a few are not. DOM- and Vue-specific options (such as `lib`, `jsx` and `jsxImportSource`) only make sense for your application code, so they are applied to `tsconfig.app.json` alone. Nuxt also manages `types`, `paths` and `noEmit` per context (the `node`, `shared` and `server` configs deliberately emit nothing and scan no ambient types), so setting these in `typescript.tsConfig` will not change them. Use the matching per-context option (`appTsConfig`, `nodeTsConfig`, `sharedTsConfig` or `serverTsConfig`) when you need to override them.
+::
+
+::note
+`typescript.serverTsConfig` extends `tsconfig.server.json`. `nitro.typescript.tsConfig` is kept in sync with it but is deprecated, so set `typescript.serverTsConfig` instead.
+::