@nuxt/docs 4.2.0 → 4.2.1

package/2.guide/1.directory-structure/1.app/1.middleware.md

@@ -48,13 +48,13 @@ Nuxt provides two globally available helpers that can be returned directly from
 1. [`navigateTo`](/docs/4.x/api/utils/navigate-to) - Redirects to the given route
 2. [`abortNavigation`](/docs/4.x/api/utils/abort-navigation) - Aborts the navigation, with an optional error message.
 
-Unlike [navigation guards](https://router.vuejs.org/guide/advanced/navigation-guards.html#global-before-guards) from `vue-router`, a third `next()` argument is not passed, and **redirect or route cancellation is handled by returning a value from the middleware**.
+Unlike [navigation guards](https://router.vuejs.org/guide/advanced/navigation-guards#Global-Before-Guards) from `vue-router`, a third `next()` argument is not passed, and **redirect or route cancellation is handled by returning a value from the middleware**.
 
 Possible return values are:
 
 * nothing (a simple `return` or no return at all) - does not block navigation and will move to the next middleware function, if any, or complete the route navigation
-* `return navigateTo('/')` - redirects to the given path and will set the redirect code to [`302` Found](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/302) if the redirect happens on the server side
-* `return navigateTo('/', { redirectCode: 301 })` - redirects to the given path and will set the redirect code to [`301` Moved Permanently](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/301) if the redirect happens on the server side
+* `return navigateTo('/')` - redirects to the given path and will set the redirect code to [`302` Found](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/302) if the redirect happens on the server side
+* `return navigateTo('/', { redirectCode: 301 })` - redirects to the given path and will set the redirect code to [`301` Moved Permanently](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/301) if the redirect happens on the server side
 * `return abortNavigation()` - stops the current navigation
 * `return abortNavigation(error)` - rejects the current navigation with an error
 
@@ -62,7 +62,7 @@ Possible return values are:
 :read-more{to="/docs/4.x/api/utils/abort-navigation"}
 
 ::important
-We recommend using the helper functions above for performing redirects or stopping navigation. Other possible return values described in [the vue-router docs](https://router.vuejs.org/guide/advanced/navigation-guards.html#global-before-guards) may work but there may be breaking changes in future.
+We recommend using the helper functions above for performing redirects or stopping navigation. Other possible return values described in [the vue-router docs](https://router.vuejs.org/guide/advanced/navigation-guards#Global-Before-Guards) may work but there may be breaking changes in future.
 ::
 
 ## Middleware Order

package/2.guide/1.directory-structure/1.app/1.pages.md

@@ -6,12 +6,12 @@ navigation.icon: i-vscode-icons-folder-type-view
 ---
 
 ::note
-To reduce your application's bundle size, this directory is **optional**, meaning that [`vue-router`](https://router.vuejs.org) won't be included if you only use [`app.vue`](/docs/4.x/guide/directory-structure/app). To force the pages system, set `pages: true` in `nuxt.config` or have a [`router.options.ts`](/docs/4.x/guide/recipes/custom-routing#using-routeroptions).
+To reduce your application's bundle size, this directory is **optional**, meaning that [`vue-router`](https://router.vuejs.org) won't be included if you only use [`app.vue`](/docs/4.x/guide/directory-structure/app/app). To force the pages system, set `pages: true` in `nuxt.config` or have a [`router.options.ts`](/docs/4.x/guide/recipes/custom-routing#using-routeroptions).
 ::
 
 ## Usage
 
-Pages are Vue components and can have any [valid extension](/docs/4.x/api/configuration/nuxt-config#extensions) that Nuxt supports (by default `.vue`, `.js`, `.jsx`, `.mjs`, `.ts` or `.tsx`).
+Pages are Vue components and can have any [valid extension](/docs/4.x/api/nuxt-config#extensions) that Nuxt supports (by default `.vue`, `.js`, `.jsx`, `.mjs`, `.ts` or `.tsx`).
 
 Nuxt will automatically create a route for every page in your `~/pages/` directory.
 
@@ -46,7 +46,7 @@ export default defineComponent({
 
 The `app/pages/index.vue` file will be mapped to the `/` route of your application.
 
-If you are using [`app.vue`](/docs/4.x/guide/directory-structure/app), make sure to use the [`<NuxtPage/>`](/docs/4.x/api/components/nuxt-page) component to display the current page:
+If you are using [`app.vue`](/docs/4.x/guide/directory-structure/app/app), make sure to use the [`<NuxtPage/>`](/docs/4.x/api/components/nuxt-page) component to display the current page:
 
 ```vue [app/app.vue]
 <template>
@@ -93,7 +93,7 @@ Here are some examples to illustrate what a page with a single root element look
 
 ## Dynamic Routes
 
-If you place anything within square brackets, it will be turned into a [dynamic route](https://router.vuejs.org/guide/essentials/dynamic-matching.html) parameter. You can mix and match multiple parameters and even non-dynamic text within a file name or directory.
+If you place anything within square brackets, it will be turned into a [dynamic route](https://router.vuejs.org/guide/essentials/dynamic-matching) parameter. You can mix and match multiple parameters and even non-dynamic text within a file name or directory.
 
 If you want a parameter to be _optional_, you must enclose it in double square brackets - for example, `~/pages/[[slug]]/index.vue` or `~/pages/[[slug]].vue` will match both `/` and `/test`.
 
@@ -154,7 +154,7 @@ Navigating to `/hello/world` would render:
 
 ## Nested Routes
 
-It is possible to display [nested routes](https://next.router.vuejs.org/guide/essentials/nested-routes.html) with `<NuxtPage>`.
+It is possible to display [nested routes](https://router.vuejs.org/guide/essentials/nested-routes) with `<NuxtPage>`.
 
 Example:
 
@@ -268,9 +268,9 @@ console.log(route.meta.title) // My home page
 </script>
 ```
 
-If you are using nested routes, the page metadata from all these routes will be merged into a single object. For more on route meta, see the [vue-router docs](https://router.vuejs.org/guide/advanced/meta.html#route-meta-fields).
+If you are using nested routes, the page metadata from all these routes will be merged into a single object. For more on route meta, see the [vue-router docs](https://router.vuejs.org/guide/advanced/meta).
 
-Much like `defineEmits` or `defineProps` (see [Vue docs](https://vuejs.org/api/sfc-script-setup.html#defineprops-defineemits)), `definePageMeta` is a **compiler macro**. It will be compiled away so you cannot reference it within your component. Instead, the metadata passed to it will be hoisted out of the component.
+Much like `defineEmits` or `defineProps` (see [Vue docs](https://vuejs.org/api/sfc-script-setup#defineprops-defineemits)), `definePageMeta` is a **compiler macro**. It will be compiled away so you cannot reference it within your component. Instead, the metadata passed to it will be hoisted out of the component.
 Therefore, the page meta object cannot reference the component. However, it can reference imported bindings, as well as locally defined **pure functions**.
 
 ::warning
@@ -301,13 +301,13 @@ Of course, you are welcome to define metadata for your own use throughout your a
 
 #### `alias`
 
-You can define page aliases. They allow you to access the same page from different paths. It can be either a string or an array of strings as defined [in the vue-router documentation](https://router.vuejs.org/guide/essentials/redirect-and-alias.html#Alias).
+You can define page aliases. They allow you to access the same page from different paths. It can be either a string or an array of strings as defined [in the vue-router documentation](https://router.vuejs.org/guide/essentials/redirect-and-alias#Alias).
 
 #### `keepalive`
 
-Nuxt will automatically wrap your page in [the Vue `<KeepAlive>` component](https://vuejs.org/guide/built-ins/keep-alive.html#keepalive) if you set `keepalive: true` in your `definePageMeta`. This might be useful to do, for example, in a parent route that has dynamic child routes, if you want to preserve page state across route changes.
+Nuxt will automatically wrap your page in [the Vue `<KeepAlive>` component](https://vuejs.org/guide/built-ins/keep-alive#keepalive) if you set `keepalive: true` in your `definePageMeta`. This might be useful to do, for example, in a parent route that has dynamic child routes, if you want to preserve page state across route changes.
 
-When your goal is to preserve state for parent routes use this syntax: `<NuxtPage keepalive />`. You can also set props to be passed to `<KeepAlive>` (see [a full list](https://vuejs.org/api/built-in-components.html#keepalive)).
+When your goal is to preserve state for parent routes use this syntax: `<NuxtPage keepalive />`. You can also set props to be passed to `<KeepAlive>` (see [a full list](https://vuejs.org/api/built-in-components#keepalive)).
 
 You can set a default value for this property [in your `nuxt.config`](/docs/4.x/api/nuxt-config#keepalive).
 
@@ -321,13 +321,13 @@ You can define the layout used to render the route. This can be either false (to
 
 #### `layoutTransition` and `pageTransition`
 
-You can define transition properties for the `<transition>` component that wraps your pages and layouts, or pass `false` to disable the `<transition>` wrapper for that route. You can see [a list of options that can be passed](https://vuejs.org/api/built-in-components.html#transition) or read [more about how transitions work](https://vuejs.org/guide/built-ins/transition.html#transition).
+You can define transition properties for the `<transition>` component that wraps your pages and layouts, or pass `false` to disable the `<transition>` wrapper for that route. You can see [a list of options that can be passed](https://vuejs.org/api/built-in-components#transition) or read [more about how transitions work](https://vuejs.org/guide/built-ins/transition#transition).
 
 You can set default values for these properties [in your `nuxt.config`](/docs/4.x/api/nuxt-config#layouttransition).
 
 #### `middleware`
 
-You can define middleware to apply before loading this page. It will be merged with all the other middleware used in any matching parent/child routes. It can be a string, a function (an anonymous/inlined middleware function following [the global before guard pattern](https://router.vuejs.org/guide/advanced/navigation-guards.html#global-before-guards)), or an array of strings/functions. [More about named middleware](/docs/4.x/guide/directory-structure/app/middleware).
+You can define middleware to apply before loading this page. It will be merged with all the other middleware used in any matching parent/child routes. It can be a string, a function (an anonymous/inlined middleware function following [the global before guard pattern](https://router.vuejs.org/guide/advanced/navigation-guards#Global-Before-Guards)), or an array of strings/functions. [More about named middleware](/docs/4.x/guide/directory-structure/app/middleware).
 
 #### `name`
 
@@ -335,7 +335,7 @@ You may define a name for this page's route.
 
 #### `path`
 
-You may define a path matcher, if you have a more complex pattern than can be expressed with the file name. See [the `vue-router` docs](https://router.vuejs.org/guide/essentials/route-matching-syntax.html#custom-regex-in-params) for more information.
+You may define a path matcher, if you have a more complex pattern than can be expressed with the file name. See [the `vue-router` docs](https://router.vuejs.org/guide/essentials/route-matching-syntax#Custom-regex-in-params) for more information.
 
 #### `props`
 

package/2.guide/1.directory-structure/1.app/1.plugins.md

@@ -205,7 +205,7 @@ Note that we highly recommend using [`composables`](/docs/4.x/guide/directory-st
 
 ::warning
 **If your plugin provides a `ref` or `computed`, it will not be unwrapped in a component `<template>`.** :br
-This is due to how Vue works with refs that aren't top-level to the template. You can read more about it [in the Vue documentation](https://vuejs.org/guide/essentials/reactivity-fundamentals.html#caveat-when-unwrapping-in-templates).
+This is due to how Vue works with refs that aren't top-level to the template. You can read more about it [in the Vue documentation](https://vuejs.org/guide/essentials/reactivity-fundamentals#caveat-when-unwrapping-in-templates).
 ::
 
 ## Typing Plugins
@@ -234,10 +234,6 @@ declare module 'vue' {
 export {}
 ```
 
-::note
-If you are using WebStorm, you may need to augment `@vue/runtime-core` until [this issue](https://youtrack.jetbrains.com/issue/WEB-59818/VUE-TypeScript-WS-PS-does-not-correctly-display-type-of-globally-injected-properties) is resolved.
-::
-
 ## Vue Plugins
 
 If you want to use Vue plugins, like [vue-gtag](https://github.com/MatteoGabriele/vue-gtag) to add Google Analytics tags, you can use a Nuxt plugin to do so.

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

@@ -5,7 +5,7 @@ head.title: "node_modules/"
 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.sh/package-manager)) creates this directory to store the dependencies of your project.
+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)) creates this directory to store the dependencies of your project.
 
 ::important
 This directory should be added to your [`.gitignore`](/docs/4.x/guide/directory-structure/gitignore) file to avoid pushing the dependencies to your repository.

package/2.guide/1.directory-structure/1.public.md

@@ -22,6 +22,6 @@ useSeoMeta({
 </script>
 ```
 
-::tip{to="https://v2.nuxt.com/docs/directory-structure/static" target="_blank"}
+::tip{to="https://v2.nuxt.com/docs/directory-structure/static/" target="_blank"}
 This is known as the [`static/`] directory in Nuxt 2.
 ::

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

@@ -132,9 +132,9 @@ export const defineWrappedResponseHandler = <T extends EventHandlerRequest, D> (
 
 ## Server Types
 
-::tip
-This feature is available from Nuxt >= 3.5
-::
+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/guide/directory-structure/tsconfig) which includes a project reference covering the `server/` folder which ensures accurate typings.
 
 ## Recipes
 
@@ -158,7 +158,7 @@ You can now universally call this API on `/api/hello/nuxt` and get `Hello, nuxt!
 
 ### Matching HTTP Method
 
-Handle file names can be suffixed with `.get`, `.post`, `.put`, `.delete`, ... to match request's [HTTP Method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods).
+Handle file names can be suffixed with `.get`, `.post`, `.put`, `.delete`, ... to match request's [HTTP Method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods).
 
 ```ts [server/api/test.get.ts]
 export default defineEventHandler(() => 'Test get handler')
@@ -226,7 +226,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"}
+::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.
 ::
 

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

@@ -75,5 +75,5 @@ Note that for a purely static site, it is not possible to set runtime configurat
 
 ::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/guide/directory-structure/app-config"}
+:read-more{to="/docs/4.x/guide/directory-structure/app/app-config"}
 ::

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

@@ -1,13 +1,13 @@
 ---
 title: "tsconfig.json"
-description: "Nuxt generates multiple TypeScript configuration files with sensible defaults and your aliases."
+description: "Learn how Nuxt manages TypeScript configuration across different parts of your project."
 head.title: "tsconfig.json"
 navigation.icon: i-vscode-icons-file-type-tsconfig
 ---
 
-Nuxt [automatically generates](/docs/4.x/guide/concepts/typescript) multiple TypeScript configuration files (`.nuxt/tsconfig.app.json`, `.nuxt/tsconfig.server.json`, `.nuxt/tsconfig.node.json` and `.nuxt/tsconfig.shared.json`) with the resolved aliases you are using in your Nuxt project, as well as with other sensible defaults.
+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.
 
-You can benefit from this by creating a `tsconfig.json` in the root of your project with the following content:
+Your Nuxt project should include the following `tsconfig.json` file at the root of the project:
 
 ```json [tsconfig.json]
 {
@@ -29,10 +29,41 @@ You can benefit from this by creating a `tsconfig.json` in the root of your proj
 }
 ```
 
-::note
-As you need to, you can customize the contents of this file. However, it is recommended that you don't overwrite `target`, `module` and `moduleResolution`.
+::warning
+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`.
 ::
 
-::note
-If you need to customize your `paths`, this will override the auto-generated path aliases. Instead, we recommend that you add any path aliases you need to the [`alias`](/docs/4.x/api/nuxt-config#alias) property within your `nuxt.config`, where they will get picked up and added to the auto-generated `tsconfig`.
+::read-more{to="/docs/4.x/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.
+<!-- @case-police-ignore tsConfig -->
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  typescript: {
+    // customize tsconfig.app.json
+    tsConfig: {
+      // ...
+    },
+    // customize tsconfig.shared.json
+    sharedTsConfig: {
+      // ...
+    },
+    // customize tsconfig.node.json
+    nodeTsConfig: {
+      // ...
+    },
+  },
+  nitro: {
+    typescript: {
+      // customize tsconfig.server.json
+      tsConfig: {
+        // ...
+      },
+    },
+  },
+})
+```

package/2.guide/2.concepts/1.auto-imports.md

@@ -3,7 +3,7 @@ title: Auto-imports
 description: "Nuxt auto-imports components, composables, helper functions and Vue APIs."
 ---
 
-Nuxt auto-imports components, composables and [Vue.js APIs](https://vuejs.org/api) to use across your application without explicitly importing them.
+Nuxt auto-imports components, composables and [Vue.js APIs](https://vuejs.org/api/) to use across your application without explicitly importing them.
 
 ```vue twoslash [app/app.vue]
 <script setup lang="ts">
@@ -109,7 +109,7 @@ Nuxt directly auto-imports files created in defined directories:
 
 ::warning
 **Auto-imported `ref` and `computed` won't be unwrapped in a component `<template>`.** :br
-This is due to how Vue works with refs that aren't top-level to the template. You can read more about it [in the Vue documentation](https://vuejs.org/guide/essentials/reactivity-fundamentals.html#caveat-when-unwrapping-in-templates).
+This is due to how Vue works with refs that aren't top-level to the template. You can read more about it [in the Vue documentation](https://vuejs.org/guide/essentials/reactivity-fundamentals#caveat-when-unwrapping-in-templates).
 ::
 
 ### Explicit Imports

package/2.guide/2.concepts/10.nuxt-lifecycle.md

@@ -40,13 +40,13 @@ The Vue and Nuxt instances are created first. Afterward, Nuxt executes its serve
 - Built-in plugins, such as Vue Router and `unhead`.
 - Custom plugins located in the `app/plugins/` directory, including those without a suffix (e.g., `myPlugin.ts`) and those with the `.server` suffix (e.g., `myServerPlugin.server.ts`).
 
-Plugins execute in a specific order and may have dependencies on one another. For more details, including execution order and parallelism, refer to the [Plugins documentation](/docs/4.x/guide/directory-structure/plugins).
+Plugins execute in a specific order and may have dependencies on one another. For more details, including execution order and parallelism, refer to the [Plugins documentation](/docs/4.x/guide/directory-structure/app/plugins).
 
 ::callout{icon="i-lucide-lightbulb"}
 After this step, Nuxt calls the [`app:created`](/docs/4.x/api/advanced/hooks#app-hooks-runtime) hook, which can be used to execute additional logic.
 ::
 
-:read-more{to="/docs/4.x/guide/directory-structure/plugins"}
+:read-more{to="/docs/4.x/guide/directory-structure/app/plugins"}
 
 ### Step 4: Route Validation
 
@@ -120,7 +120,7 @@ Custom plugins in the `app/plugins/` directory, such as those without a suffix (
 After this step, Nuxt calls the [`app:created`](/docs/4.x/api/advanced/hooks#app-hooks-runtime) hook, which can be used to execute additional logic.
 ::
 
-:read-more{to="/docs/4.x/guide/directory-structure/plugins"}
+:read-more{to="/docs/4.x/guide/directory-structure/app/plugins"}
 
 ### Step 2: Route Validation
 

package/2.guide/2.concepts/2.vuejs-development.md

@@ -21,7 +21,7 @@ We chose to build Nuxt on top of Vue for these reasons:
 
 ### Single File Components
 
-[Vue’s single-file components](https://vuejs.org/guide/scaling-up/sfc.html) (SFC or `*.vue` files) encapsulate the markup (`<template>`), logic (`<script>`) and styling (`<style>`) of a Vue component. Nuxt provides a zero-config experience for SFCs with [Hot Module Replacement](https://vite.dev/guide/features.html#hot-module-replacement) that offers a seamless developer experience.
+[Vue’s single-file components](https://vuejs.org/guide/scaling-up/sfc) (SFC or `*.vue` files) encapsulate the markup (`<template>`), logic (`<script>`) and styling (`<style>`) of a Vue component. Nuxt provides a zero-config experience for SFCs with [Hot Module Replacement](https://vite.dev/guide/features#hot-module-replacement) that offers a seamless developer experience.
 
 ### Auto-imports
 
@@ -78,7 +78,7 @@ export default {
 </script>
 ```
 
-The [Composition API](https://vuejs.org/guide/extras/composition-api-faq.html) introduced in Vue 3 is not a replacement of the Options API, but it enables better logic reuse throughout an application, and is a more natural way to group code by concern in complex components.
+The [Composition API](https://vuejs.org/guide/extras/composition-api-faq) introduced in Vue 3 is not a replacement of the Options API, but it enables better logic reuse throughout an application, and is a more natural way to group code by concern in complex components.
 
 Used with the `setup` keyword in the `<script>` definition, here is the above component rewritten with Composition API and Nuxt 3’s auto-imported Reactivity APIs:
 
@@ -91,7 +91,7 @@ const increment = () => count.value++
 
 The goal of Nuxt is to provide a great developer experience around the Composition API.
 
-- Use auto-imported [Reactivity functions](https://vuejs.org/api/reactivity-core.html) from Vue and Nuxt [built-in composables](/docs/4.x/api/composables/use-async-data).
+- Use auto-imported [Reactivity functions](https://vuejs.org/api/reactivity-core) from Vue and Nuxt [built-in composables](/docs/4.x/api/composables/use-async-data).
 - Write your own auto-imported reusable functions in the [`app/composables/` directory](/docs/4.x/guide/directory-structure/app/composables).
 
 ### TypeScript Support

package/2.guide/2.concepts/3.rendering.md

@@ -44,7 +44,7 @@ const handleClick = () => {
 
 On the initial request, the `counter` ref is initialized in the server since it is rendered inside the `<p>` tag. The contents of `handleClick` is never executed here. During hydration in the browser, the `counter` ref is re-initialized. The `handleClick` finally binds itself to the button; Therefore it is reasonable to deduce that the body of `handleClick` will always run in a browser environment.
 
-[Middlewares](/docs/4.x/guide/directory-structure/app/middleware) and [pages](/docs/4.x/guide/directory-structure/app/pages) run in the server and on the client during hydration. [Plugins](/docs/4.x/guide/directory-structure/plugins) can be rendered on the server or client or both. [Components](/docs/4.x/guide/directory-structure/app/components) can be forced to run on the client only as well. [Composables](/docs/4.x/guide/directory-structure/app/composables) and [utilities](/docs/4.x/guide/directory-structure/app/utils) are rendered based on the context of their usage.
+[Middlewares](/docs/4.x/guide/directory-structure/app/middleware) and [pages](/docs/4.x/guide/directory-structure/app/pages) run in the server and on the client during hydration. [Plugins](/docs/4.x/guide/directory-structure/app/plugins) can be rendered on the server or client or both. [Components](/docs/4.x/guide/directory-structure/app/components) can be forced to run on the client only as well. [Composables](/docs/4.x/guide/directory-structure/app/composables) and [utilities](/docs/4.x/guide/directory-structure/app/utils) are rendered based on the context of their usage.
 
 **Benefits of server-side rendering:**
 - **Performance**: Users can get immediate access to the page's content because browsers can display static content much faster than JavaScript-generated content. At the same time, Nuxt preserves the interactivity of a web application during the hydration process.
@@ -57,7 +57,7 @@ On the initial request, the `counter` ref is initialized in the server since it
 Universal rendering is very versatile and can fit almost any use case, and is especially appropriate for any content-oriented websites: **blogs, marketing websites, portfolios, e-commerce sites, and marketplaces.**
 
 ::tip
-For more examples about writing Vue code without hydration mismatch, see [the Vue docs](https://vuejs.org/guide/scaling-up/ssr.html#hydration-mismatch).
+For more examples about writing Vue code without hydration mismatch, see [the Vue docs](https://vuejs.org/guide/scaling-up/ssr#hydration-mismatch).
 ::
 
 ::important
@@ -225,8 +225,8 @@ Edge-side rendering is possible thanks to [Nitro](https://nitro.build/), the [se
 
 The current platforms where you can leverage ESR are:
 - [Cloudflare Pages](https://pages.cloudflare.com) with zero configuration using the git integration and the `nuxt build` command
-- [Vercel Edge Functions](https://vercel.com/features/edge-functions) using the `nuxt build` command and `NITRO_PRESET=vercel-edge` environment variable
-- [Netlify Edge Functions](https://www.netlify.com/products/#netlify-edge-functions) using the `nuxt build` command and `NITRO_PRESET=netlify-edge` environment variable
+- [Vercel Cloud](https://vercel.com/home) using the `nuxt build` command and `NITRO_PRESET=vercel-edge` environment variable
+- [Netlify Edge Functions](https://www.netlify.com/platform/#netlify-edge-functions) using the `nuxt build` command and `NITRO_PRESET=netlify-edge` environment variable
 
 Note that **Hybrid Rendering** can be used when using Edge-Side Rendering with route rules.
 

package/2.guide/2.concepts/7.esm.md

@@ -31,7 +31,7 @@ export { a }
 ```
 
 Before ECMAScript Modules (ESM) became a standard (it took more than 10 years!), tooling like
-[webpack](https://webpack.js.org/guides/ecma-script-modules) and even languages like TypeScript started supporting so-called **ESM syntax**.
+[webpack](https://webpack.js.org/guides/ecma-script-modules/) and even languages like TypeScript started supporting so-called **ESM syntax**.
 However, there are some key differences with actual spec; here's [a helpful explainer](https://hacks.mozilla.org/2018/03/es-modules-a-cartoon-deep-dive/).
 
 ### What is 'Native' ESM?
@@ -161,7 +161,7 @@ const pkg = require('cjs-pkg')
 console.log(pkg) // { test: 123 }
 ```
 
-[Node.js in native ESM mode](https://nodejs.org/api/esm.html#interoperability-with-commonjs), [typescript with `esModuleInterop` enabled](https://www.typescriptlang.org/tsconfig#esModuleInterop) and bundlers such as webpack, provide a compatibility mechanism so that we can default import such library.
+[Node.js in native ESM mode](https://nodejs.org/api/esm.html#interoperability-with-commonjs), [typescript with `esModuleInterop` enabled](https://www.typescriptlang.org/tsconfig/#esModuleInterop) and bundlers such as webpack, provide a compatibility mechanism so that we can default import such library.
 This mechanism is often referred to as "interop require default":
 
 ```js

package/2.guide/2.concepts/8.typescript.md

@@ -47,56 +47,37 @@ export default defineNuxtConfig({
 
 ## Auto-generated Types
 
-When you run `nuxt dev` or `nuxt build`, Nuxt generates the following files for IDE type support (and type checking):
+Nuxt projects rely on auto-generated types to work properly. These types are stored in the [`.nuxt`](/docs/4.x/guide/directory-structure/nuxt) directory and are generated when you run the dev server or build your application. You can also generate these files manually by running `nuxt prepare`.
 
-### `.nuxt/nuxt.d.ts`
+The generated `tsconfig.json` files inside the [`.nuxt`](/docs/4.x/guide/directory-structure/nuxt) directory 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 like `#imports`, `~/file`, or `#build/file`, and more.
 
-This file contains the types of any modules you are using, as well as the key types that Nuxt requires. Your IDE should recognize these types automatically.
-
-Some of the references in the file are to files that are only generated within your `buildDir` (`.nuxt`) and therefore for full typings, you will need to run `nuxt dev` or `nuxt build`.
-
-### `.nuxt/tsconfig.app.json`
-
-This file contains the recommended basic TypeScript configuration for your project, including resolved aliases injected by Nuxt or modules you are using, so you can get full type support and path auto-complete for aliases like `~/file` or `#build/file`.
-
-::note
-Consider using the `imports` section of [nuxt.config](/docs/4.x/api/nuxt-config#imports) to include directories beyond the default ones. This can be useful for auto-importing types which you're using across your app.
+::warning
+Nuxt relies on this configuration, and [Nuxt Modules](/docs/4.x/guide/going-further/modules) can extend it as well. For this reason, it is not recommended to modify your `tsconfig.json` file directly, as doing so could overwrite important settings. Instead, extend it via `nuxt.config.ts`. [Learn more about extending the configuration here](/docs/4.x/guide/directory-structure/tsconfig).
 ::
 
-[Read more about how to extend this configuration](/docs/4.x/guide/directory-structure/tsconfig).
-
 ::tip{icon="i-lucide-video" to="https://youtu.be/umLI7SlPygY" target="_blank"}
 Watch a video from Daniel Roe explaining built-in Nuxt aliases.
 ::
 
-::note
-Nitro also [auto-generates types](/docs/4.x/guide/concepts/server-engine#typed-api-routes) for API routes. Plus, Nuxt also generates types for globally available components and [auto-imports from your composables](/docs/4.x/guide/directory-structure/app/composables), plus other core functionality.
-::
-
-::note
-For backward compatibility, Nuxt still generates `./.nuxt/tsconfig.json`. However, we recommend using [TypeScript project references](/docs/4.x/guide/directory-structure/tsconfig) with the new configuration files (`.nuxt/tsconfig.app.json`, `.nuxt/tsconfig.server.json`, etc.) for better type safety and performance.
-
-If you do extend from `./.nuxt/tsconfig.json`, keep in mind that all options will be overwritten by those defined in your `tsconfig.json`. Overwriting options such as `"compilerOptions.paths"` with your own configuration will lead TypeScript to not factor in the module resolutions, which can cause module resolutions such as `#imports` to not be recognized.
-
-In case you need to extend options further, you can use the [`alias` property](/docs/4.x/api/nuxt-config#alias) within your `nuxt.config`. Nuxt will pick them up and extend the generated TypeScript configurations accordingly.
-::
-
 ## Project References
 
 Nuxt uses [TypeScript project references](https://www.typescriptlang.org/docs/handbook/project-references.html) to improve type-checking performance and provide better IDE support. This feature allows TypeScript to break up your codebase into smaller, more manageable pieces.
 
 ### How Nuxt Uses Project References
 
-When you run `nuxt dev` or `nuxt build`, Nuxt will generate multiple `tsconfig.json` files for different parts of your application.
+When you run `nuxt dev`, `nuxt build` or `nuxt prepare`, Nuxt will generate multiple `tsconfig.json` files for different parts of your application.
 
-- **`.nuxt/tsconfig.app.json`** - Configuration for your application code
-- **`.nuxt/tsconfig.node.json`** - Configuration for your `nuxt.config` and modules
+- **`.nuxt/tsconfig.app.json`** - Configuration for your application code within the `app/` directory
+- **`.nuxt/tsconfig.node.json`** - Configuration for your `nuxt.config.ts` and files outside the other contexts
 - **`.nuxt/tsconfig.server.json`** - Configuration for server-side code (when applicable)
 - **`.nuxt/tsconfig.shared.json`** - For code shared between app and server contexts (like types and non-environment specific utilities)
-- **`.nuxt/tsconfig.json`** - Legacy configuration for backward compatibility
 
 Each of these files is configured to reference the appropriate dependencies and provide optimal type-checking for their specific context.
 
+::note
+For backward compatibility, Nuxt still generates `.nuxt/tsconfig.json`. However, we recommend using [TypeScript project references](/docs/4.x/guide/directory-structure/tsconfig) with the new configuration files (`.nuxt/tsconfig.app.json`, `.nuxt/tsconfig.server.json`, etc.) for better type safety and performance. This legacy file will be removed in a future version of Nuxt.
+::
+
 ### Benefits of Project References
 
 - **Faster builds**: TypeScript can skip rebuilding unchanged projects
@@ -104,13 +85,9 @@ Each of these files is configured to reference the appropriate dependencies and
 - **Isolated compilation**: Errors in one part of your application don't prevent compilation of other parts
 - **Clearer dependency management**: Each project explicitly declares its dependencies
 
-::note
-The project reference setup is handled automatically by Nuxt. You typically don't need to modify these configurations manually, but understanding how they work can help you troubleshoot type-checking issues.
-::
-
 ### Augmenting Types with Project References
 
-Since the project is divided into **multiple type contexts**, it's important to **augment types within the correct context** to ensure they are properly recognized.
+Since the project is divided into **multiple type contexts**, it's important to **augment types within the correct context** to ensure they're properly recognized. TypeScript will not recognize augmentations placed outside these directories unless they are explicitly included in the appropriate context.
 
 For example, if you want to augment types for the `app` context, the augmentation file should be placed in the `app/` directory.
 
@@ -118,15 +95,15 @@ Similarly:
 - For the `server` context, place the augmentation file in the `server/` directory.
 - For types that are **shared between the app and server**, place the file in the `shared/` directory.
 
-::warning
-Augmenting types outside of these directories will not be recognized by TypeScript.
+::read-more{to="/docs/4.x/guide/going-further/modules#extending-tsconfigjson"}
+Read more about augmenting specific type contexts from **files outside those contexts** in the Module Author Guide.
 ::
 
 ## Strict Checks
 
 TypeScript comes with certain checks to give you more safety and analysis of your program.
 
-[Strict checks](https://www.typescriptlang.org/docs/handbook/migrating-from-javascript.html#getting-stricter-checks) are enabled by default in Nuxt to give you greater type safety.
+[Strict checks](https://www.typescriptlang.org/docs/handbook/migrating-from-javascript.html#getting-stricter-checks) are enabled by default in Nuxt when the [`typescript.typeCheck`](/docs/4.x/guide/concepts/typescript#type-checking) option is enabled to give you greater type safety.
 
 If you are currently converting your codebase to TypeScript, you may want to temporarily disable strict checks by setting `strict` to `false` in your `nuxt.config`:
 

package/2.guide/2.concepts/9.code-style.md

@@ -8,7 +8,7 @@ description: "Nuxt supports ESLint out of the box"
 The recommended approach for Nuxt is to enable ESLint support using the [`@nuxt/eslint`](https://eslint.nuxt.com/packages/module) module, that will setup project-aware ESLint configuration for you.
 
 :::callout{icon="i-lucide-lightbulb"}
-The module is designed for the [new ESLint flat config format](https://eslint.org/docs/latest/use/configure/configuration-files-new) with is the [default format since ESLint v9](https://eslint.org/blog/2024/04/eslint-v9.0.0-released/). If you are using the legacy `.eslintrc` config, you will need to [configure manually with `@nuxt/eslint-config`](https://eslint.nuxt.com/packages/config#legacy-config-format). We highly recommend you to migrate over the flat config to be future-proof.
+The module is designed for the [new ESLint flat config format](https://eslint.org/docs/latest/use/configure/configuration-files) which is the [default format since ESLint v9](https://eslint.org/blog/2024/04/eslint-v9.0.0-released/). If you are using the legacy `.eslintrc` config, you will need to [configure manually with `@nuxt/eslint-config`](https://eslint.nuxt.com/packages/config#customizing-the-config). We highly recommend you to migrate over the flat config to be future-proof.
 :::
 
 ## Quick Setup

package/2.guide/3.going-further/1.experimental-features.md

@@ -5,7 +5,7 @@ description: "Enable Nuxt experimental features to unlock new possibilities."
 
 Nuxt includes experimental features that you can enable in your configuration file.
 
-Internally, Nuxt uses `@nuxt/schema` to define these experimental features. You can refer to the [API documentation](/docs/4.x/api/configuration/nuxt-config#experimental) or the [source code](https://github.com/nuxt/nuxt/blob/main/packages/schema/src/config/experimental.ts) for more information.
+Internally, Nuxt uses `@nuxt/schema` to define these experimental features. You can refer to the [API documentation](/docs/4.x/guide/going-further/experimental-features) or the [source code](https://github.com/nuxt/nuxt/blob/main/packages/schema/src/config/experimental.ts) for more information.
 
 ::note
 Note that these features are experimental and could be removed or modified in the future.
@@ -290,7 +290,7 @@ export default defineNuxtConfig({
 
 :link-example{to="https://stackblitz.com/edit/nuxt-view-transitions?file=app.vue" target="_blank"}
 
-::read-more{icon="i-simple-icons-mdnwebdocs" to="https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API" target="_blank"}
+::read-more{icon="i-simple-icons-mdnwebdocs" to="https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API" target="_blank"}
 Read more about the **View Transition API**.
 ::
 
@@ -405,12 +405,12 @@ should do this automatically for you.)
 // This would be unsafe in a dynamic page (e.g. `[slug].vue`) because the route slug makes a difference
 // to the data fetched, but Nuxt can't know that because it's not reflected in the key.
 const route = useRoute()
-const { data } = await useAsyncData(async () => {
-  return await $fetch(`/api/my-page/${route.params.slug}`)
+const { data } = await useAsyncData(async (_nuxtApp, { signal }) => {
+  return await $fetch(`/api/my-page/${route.params.slug}`, { signal })
 })
 // Instead, you should use a key that uniquely identifies the data fetched.
-const { data } = await useAsyncData(route.params.slug, async () => {
-  return await $fetch(`/api/my-page/${route.params.slug}`)
+const { data } = await useAsyncData(route.params.slug, async (_nuxtApp, { signal }) => {
+  return await $fetch(`/api/my-page/${route.params.slug}`, { signal })
 })
 ```
 

package/2.guide/3.going-further/1.features.md

@@ -91,7 +91,7 @@ export default defineNuxtConfig({
 
 ### typescriptBundlerResolution
 
-This enables 'Bundler' module resolution mode for TypeScript, which is the recommended setting for frameworks like Nuxt and [Vite](https://vite.dev/guide/performance.html#reduce-resolve-operations).
+This enables 'Bundler' module resolution mode for TypeScript, which is the recommended setting for frameworks like Nuxt and [Vite](https://vite.dev/guide/performance#reduce-resolve-operations).
 
 It improves type support when using modern libraries with `exports`.
 

package/2.guide/3.going-further/1.internals.md

@@ -30,7 +30,7 @@ Global usage is possible for the browser but not on the server, to avoid sharing
 
 Since [`useNuxtApp`](/docs/4.x/api/composables/use-nuxt-app) throws an exception if context is currently unavailable, if your composable does not always require `nuxtApp`, you can use [`tryUseNuxtApp`](/docs/4.x/api/composables/use-nuxt-app#tryusenuxtapp) instead, which will return `null` instead of throwing an exception.
 
-To extend the `nuxtApp` interface and hook into different stages or access contexts, we can use [Nuxt Plugins](/docs/4.x/guide/directory-structure/plugins).
+To extend the `nuxtApp` interface and hook into different stages or access contexts, we can use [Nuxt Plugins](/docs/4.x/guide/directory-structure/app/plugins).
 
 Check [Nuxt App](/docs/4.x/api/composables/use-nuxt-app) for more information about this interface.
 
@@ -76,6 +76,6 @@ Nuxt builds and bundles project using Node.js but also has a runtime side.
 
 While both areas can be extended, that runtime context is isolated from build-time. Therefore, they are not supposed to share state, code, or context other than runtime configuration!
 
-`nuxt.config` and [Nuxt Modules](/docs/4.x/guide/going-further/modules) can be used to extend the build context, and [Nuxt Plugins](/docs/4.x/guide/directory-structure/plugins) can be used to extend runtime.
+`nuxt.config` and [Nuxt Modules](/docs/4.x/guide/going-further/modules) can be used to extend the build context, and [Nuxt Plugins](/docs/4.x/guide/directory-structure/app/plugins) can be used to extend runtime.
 
 When building an application for production, `nuxt build` will generate a standalone build in the `.output` directory, independent of `nuxt.config` and [Nuxt modules](/docs/4.x/guide/going-further/modules).

package/2.guide/3.going-further/2.hooks.md

@@ -39,7 +39,7 @@ Explore all available Nuxt hooks.
 
 ## App Hooks (Runtime)
 
-App hooks can be mainly used by [Nuxt Plugins](/docs/4.x/guide/directory-structure/plugins) to hook into rendering lifecycle but could also be used in Vue composables.
+App hooks can be mainly used by [Nuxt Plugins](/docs/4.x/guide/directory-structure/app/plugins) to hook into rendering lifecycle but could also be used in Vue composables.
 
 ```ts [app/plugins/test.ts]
 export default defineNuxtPlugin((nuxtApp) => {