@nuxt/docs 4.1.3 → 4.2.1

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

@@ -34,6 +34,146 @@ bun x nuxt upgrade
 
 To use the latest Nuxt build and test features before their release, read about the [nightly release channel](/docs/4.x/guide/going-further/nightly-release-channel) guide.
 
+## Testing Nuxt 5
+
+Nuxt 5 is **currently in development**. Until the release, it is possible to test many of Nuxt 5's breaking changes from Nuxt version 4.2+.
+
+### Opting in to Nuxt 5
+
+First, upgrade Nuxt to the [latest release](https://github.com/nuxt/nuxt/releases).
+
+Then you can set your `future.compatibilityVersion` to match Nuxt 5 behavior:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  future: {
+    compatibilityVersion: 5,
+  },
+})
+```
+
+When you set your `future.compatibilityVersion` to `5`, defaults throughout your Nuxt configuration will change to opt in to Nuxt v5 behavior, including:
+
+- **Vite Environment API**: Automatically enables the new [Vite Environment API](/docs/4.x/getting-started/upgrade#migration-to-vite-environment-api) for improved build configuration
+- Other Nuxt 5 improvements and changes as they become available
+
+::note
+This section is subject to change until the final release, so please check back here regularly if you are testing Nuxt 5 using `future.compatibilityVersion: 5`.
+::
+
+Breaking or significant changes will be noted below along with migration steps for backward/forward compatibility.
+
+### Migration to Vite Environment API
+
+🚦 **Impact Level**: Medium
+
+#### What Changed
+
+Nuxt 5 migrates to Vite 6's new [Environment API](https://vite.dev/guide/api-environment), which formalizes the concept of environments and provides better control over configuration per environment.
+
+Previously, Nuxt used separate client and server Vite configurations. Now, Nuxt uses a shared Vite configuration with environment-specific plugins that use the `applyToEnvironment()` method to target specific environments.
+
+::tip
+You can test this feature early by setting `future.compatibilityVersion: 5` (see [Testing Nuxt 5](/docs/4.x/getting-started/upgrade#testing-nuxt-5)) or by enabling it explicitly with `experimental.viteEnvironmentApi: true`.
+::
+
+**Key changes:**
+
+1. **Deprecated environment-specific `extendViteConfig()`**: The `server` and `client` options in `extendViteConfig()` are deprecated and will show warnings when used.
+
+2. **Changed plugin registration**: Vite plugins registered with `addVitePlugin()` and only targeting one environment (by passing `server: false` or `client: false`) will not have their `config` or `configResolved` hooks called.
+
+3. **Shared configuration**: The `vite:extendConfig` and `vite:configResolved` hooks now work with a shared configuration rather than separate client/server configs.
+
+#### Reasons for Change
+
+The Vite Environment API provides:
+- Better consistency between development and production builds
+- More granular control over environment-specific configuration
+- Improved performance and plugin architecture
+- Support for custom environments beyond just client and server
+
+#### Migration Steps
+
+##### 1. Migrate to use Vite plugins
+
+We would recommend you use a Vite plugin instead of `extendViteConfig`, `vite:configResolved` and `vite:extendConfig`.
+
+```ts
+// Before
+extendViteConfig((config) => {
+  config.optimizeDeps.include.push('my-package')
+}, { server: false })
+
+nuxt.hook('vite:extendConfig' /* or vite:configResolved */, (config, { isClient }) => {
+  if (isClient) {
+    config.optimizeDeps.include.push('my-package')
+  }
+})
+
+// After
+addVitePlugin(() => ({
+  name: 'my-plugin',
+  config (config) {
+    // you can set global vite configuration here
+  },
+  configResolved (config) {
+    // you can access the fully resolved vite configuration here
+  },
+  configEnvironment (name, config) {
+    // you can set environment-specific vite configuration here
+    if (name === 'client') {
+      config.optimizeDeps ||= {}
+      config.optimizeDeps.include ||= []
+      config.optimizeDeps.include.push('my-package')
+    }
+  },
+  applyToEnvironment (environment) {
+    return environment.name === 'client'
+  },
+}))
+```
+
+##### 2. Migrate Vite plugins to use environments
+
+Instead of using `addVitePlugin` with `server: false` or `client: false`, you can instead use the new `applyToEnvironment` hook within your plugin.
+
+```ts
+// Before
+addVitePlugin(() => ({
+  name: 'my-plugin',
+  config (config) {
+    config.optimizeDeps.include.push('my-package')
+  },
+}), { client: false })
+
+// After
+addVitePlugin(() => ({
+  name: 'my-plugin',
+  config (config) {
+    // you can set global vite configuration here
+  },
+  configResolved (config) {
+    // you can access the fully resolved vite configuration here
+  },
+  configEnvironment (name, config) {
+    // you can set environment-specific vite configuration here
+    if (name === 'client') {
+      config.optimizeDeps ||= {}
+      config.optimizeDeps.include ||= []
+      config.optimizeDeps.include.push('my-package')
+    }
+  },
+  applyToEnvironment (environment) {
+    return environment.name === 'client'
+  },
+}))
+```
+
+::read-more{to="https://vite.dev/guide/api-environment" target="_blank"}
+Learn more about Vite's Environment API
+::
+
 ## Migrating to Nuxt 4
 
 Nuxt 4 includes significant improvements and changes. This guide will help you migrate your existing Nuxt 3 application to Nuxt 4.
@@ -74,26 +214,30 @@ To facilitate the upgrade process, we have collaborated with the [Codemod](https
 If you encounter any issues, please report them to the Codemod team with `npx codemod feedback` 🙏
 ::
 
-For a complete list of Nuxt 4 codemods, detailed information on each, their source, and various ways to run them, visit the [Codemod Registry](https://go.codemod.com/codemod-registry).
+For a complete list of Nuxt 4 codemods, detailed information on each, their source, and various ways to run them, visit the [Codemod Registry](https://app.codemod.com/registry).
 
 You can run all the codemods mentioned in this guide using the following `codemod` recipe:
 
 ::code-group
 
 ```bash [npm]
-npx codemod@latest nuxt/4/migration-recipe
+# Using pinned version due to https://github.com/codemod-com/codemod/issues/1710
+npx codemod@0.18.7 nuxt/4/migration-recipe
 ```
 
 ```bash [yarn]
-yarn dlx codemod@latest nuxt/4/migration-recipe
+# Using pinned version due to https://github.com/codemod-com/codemod/issues/1710
+yarn dlx codemod@0.18.7 nuxt/4/migration-recipe
 ```
 
 ```bash [pnpm]
-pnpm dlx codemod@latest nuxt/4/migration-recipe
+# Using pinned version due to https://github.com/codemod-com/codemod/issues/1710
+pnpm dlx codemod@0.18.7 nuxt/4/migration-recipe
 ```
 
 ```bash [bun]
-bun x codemod@latest nuxt/4/migration-recipe
+# Using pinned version due to https://github.com/codemod-com/codemod/issues/1710
+bun x codemod@0.18.7 nuxt/4/migration-recipe
 ```
 
 ::
@@ -110,11 +254,11 @@ Nuxt now defaults to a new directory structure, with backwards compatibility (so
 
 #### What Changed
 
-* the new Nuxt default `srcDir` is `app/` by default, and most things are resolved from there.
-* `serverDir` now defaults to `<rootDir>/server` rather than `<srcDir>/server`
-* `layers/`, `modules/` and `public/` are resolved relative to `<rootDir>` by default
-* if using [Nuxt Content v2.13+](https://github.com/nuxt/content/pull/2649), `content/` is resolved relative to `<rootDir>`
-* a new `dir.app` is added, which is the directory we look for `router.options.ts` and `spa-loading-template.html` - this defaults to `<srcDir>/`
+- the new Nuxt default `srcDir` is `app/` by default, and most things are resolved from there.
+- `serverDir` now defaults to `<rootDir>/server` rather than `<srcDir>/server`
+- `layers/`, `modules/` and `public/` are resolved relative to `<rootDir>` by default
+- if using [Nuxt Content v2.13+](https://github.com/nuxt/content/pull/2649), `content/` is resolved relative to `<rootDir>`
+- a new `dir.app` is added, which is the directory we look for `router.options.ts` and `spa-loading-template.html` - this defaults to `<srcDir>/`
 
 <details>
 
@@ -279,15 +423,15 @@ Now modules are loaded in the correct order:
 2. **Project modules last** (highest priority)
 
 This affects both:
-* Modules defined in the `modules` array in `nuxt.config.ts`
-* Auto-discovered modules from the `modules/` directory
+- Modules defined in the `modules` array in `nuxt.config.ts`
+- Auto-discovered modules from the `modules/` directory
 
 #### Reasons for Change
 
 This change ensures that:
-* Extended layers have lower priority than the consuming project
-* Module execution order matches the intuitive layer inheritance pattern
-* Module configuration and hooks work as expected in multi-layer setups
+- Extended layers have lower priority than the consuming project
+- Module execution order matches the intuitive layer inheritance pattern
+- Module configuration and hooks work as expected in multi-layer setups
 
 #### Migration Steps
 
@@ -394,9 +538,9 @@ export default defineNuxtConfig({
 [Unhead](https://unhead.unjs.io/), used to generate `<head>` tags, has been updated to version 2. While mostly compatible it includes several breaking changes
 for lower-level APIs.
 
-* Removed props: `vmid`, `hid`, `children`, `body`.
-* Promise input no longer supported.
-* Tags are now sorted using Capo.js by default.
+- Removed props: `vmid`, `hid`, `children`, `body`.
+- Promise input no longer supported.
+- Tags are now sorted using Capo.js by default.
 
 #### Migration Steps
 
@@ -404,7 +548,7 @@ The above changes should have minimal impact on your app.
 
 If you have issues you should verify:
 
-* You're not using any of the removed props.
+- You're not using any of the removed props.
 
 ```diff
 useHead({
@@ -417,7 +561,7 @@ useHead({
 })
 ```
 
-* If you're using [Template Params](https://unhead.unjs.io/docs/head/guides/plugins/template-params) or [Alias Tag Sorting](https://unhead.unjs.io/docs/head/guides/plugins/alias-sorting), you will need to explicitly opt in to these features now.
+- If you're using [Template Params](https://unhead.unjs.io/docs/head/guides/plugins/template-params) or [Alias Tag Sorting](https://unhead.unjs.io/docs/head/guides/plugins/alias-sorting), you will need to explicitly opt in to these features now.
 
 ```ts
 import { AliasSortingPlugin, TemplateParamsPlugin } from '@unhead/vue/plugins'
@@ -915,9 +1059,9 @@ Finally, providing code serialization functions directly within Nuxt is not idea
 
 We have raised PRs to update modules using EJS syntax, but if you need to do this yourself, you have three backwards/forwards-compatible alternatives:
 
-* Moving your string interpolation logic directly into `getContents()`.
-* Using a custom function to handle the replacement, such as in https://github.com/nuxt-modules/color-mode/pull/240.
-* Use `es-toolkit/compat` (a drop-in replacement for lodash template), as a dependency of _your_ project rather than Nuxt:
+- Moving your string interpolation logic directly into `getContents()`.
+- Using a custom function to handle the replacement, such as in https://github.com/nuxt-modules/color-mode/pull/240.
+- Use `es-toolkit/compat` (a drop-in replacement for lodash template), as a dependency of _your_ project rather than Nuxt:
 
 ```diff
 + import { readFileSync } from 'node:fs'
@@ -1000,11 +1144,11 @@ There are two approaches:
 Nuxt now generates separate TypeScript configurations for different contexts to provide better type-checking experiences:
 
 1. **New TypeScript configuration files**: Nuxt now generates additional TypeScript configurations:
-   * `.nuxt/tsconfig.app.json` - For your app code (Vue components, composables, etc.)
-   * `.nuxt/tsconfig.server.json` - For your server-side code (Nitro/server directory)  
-   * `.nuxt/tsconfig.node.json` - For your build-time code (modules, `nuxt.config.ts`, etc.)
-   * `.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
+   - `.nuxt/tsconfig.app.json` - For your app code (Vue components, composables, etc.)
+   - `.nuxt/tsconfig.server.json` - For your server-side code (Nitro/server directory)  
+   - `.nuxt/tsconfig.node.json` - For your build-time code (modules, `nuxt.config.ts`, etc.)
+   - `.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
 
 2. **Backward compatibility**: Existing projects that extend `.nuxt/tsconfig.json` will continue to work as before.
 
@@ -1033,8 +1177,13 @@ However, to take advantage of improved type checking, you can opt in to the new
 
 1. **Update your root `tsconfig.json`** to use project references:
 
+   ::note
+   If your `tsconfig.json` currently has an `"extends": "./.nuxt/tsconfig.json"` line, **remove it** before adding the references. Project references and extends are mutually exclusive.
+   ::
+
    ```json
    {
+     // Remove "extends": "./.nuxt/tsconfig.json" if present
      "files": [],
      "references": [
        { "path": "./.nuxt/tsconfig.app.json" },
@@ -1055,30 +1204,38 @@ However, to take advantage of improved type checking, you can opt in to the new
    ```
 
 4. **Move all type augmentations into their appropriate context**:
-   * If you are augmenting types for the app context, move the files to the `app/` directory.
-   * If you are augmenting types for the server context, move the files to the `server/` directory.
-   * If you are augmenting types that are **shared between the app and server**, move the files to the `shared/` directory.
+   - If you are augmenting types for the app context, move the files to the `app/` directory.
+   - If you are augmenting types for the server context, move the files to the `server/` directory.
+   - If you are augmenting types that are **shared between the app and server**, move the files to the `shared/` directory.
 
     ::warning
     Augmenting types from outside the `app/`, `server/`, or `shared/` directories will not work with the new project references setup.
     ::
 
-5. **Configure Node.js TypeScript options** if needed:
+5. **Configure TypeScript options** if needed:
    <!-- @case-police-ignore tsConfig -->
 
    ```ts
    export default defineNuxtConfig({
      typescript: {
-       // Customize app/server TypeScript config
+       // customize tsconfig.app.json
        tsConfig: {
-         compilerOptions: {
-           strict: true,
-         },
+         // ...
        },
-       // Customize build-time TypeScript config
+       // customize tsconfig.shared.json
+       sharedTsConfig: {
+         // ...
+       },
+       // customize tsconfig.node.json
        nodeTsConfig: {
-         compilerOptions: {
-           strict: true,
+         // ...
+       },
+     },
+     nitro: {
+       typescript: {
+         // customize tsconfig.server.json
+         tsConfig: {
+           // ...
          },
        },
      },
@@ -1097,11 +1254,11 @@ The new configuration provides better type safety and IntelliSense for projects
 
 Four experimental features are no longer configurable in Nuxt 4:
 
-* `experimental.treeshakeClientOnly` will be `true` (default since v3.0)
-* `experimental.configSchema` will be `true` (default since v3.3)
-* `experimental.polyfillVueUseHead` will be `false` (default since v3.4)
-* `experimental.respectNoSSRHeader` will be `false` (default since v3.4)
-* `vite.devBundler` is no longer configurable - it will use `vite-node` by default
+- `experimental.treeshakeClientOnly` will be `true` (default since v3.0)
+- `experimental.configSchema` will be `true` (default since v3.3)
+- `experimental.polyfillVueUseHead` will be `false` (default since v3.4)
+- `experimental.respectNoSSRHeader` will be `false` (default since v3.4)
+- `vite.devBundler` is no longer configurable - it will use `vite-node` by default
 
 #### Reasons for Change
 
@@ -1109,9 +1266,9 @@ These options have been set to their current values for some time and we do not
 
 #### Migration Steps
 
-* `polyfillVueUseHead` is implementable in user-land with [this plugin](https://github.com/nuxt/nuxt/blob/f209158352b09d1986aa320e29ff36353b91c358/packages/nuxt/src/head/runtime/plugins/vueuse-head-polyfill.ts#L10-L11)
+- `polyfillVueUseHead` is implementable in user-land with [this plugin](https://github.com/nuxt/nuxt/blob/f209158352b09d1986aa320e29ff36353b91c358/packages/nuxt/src/head/runtime/plugins/vueuse-head-polyfill.ts#L10-L11)
 
-* `respectNoSSRHeader`is implementable in user-land with [server middleware](https://github.com/nuxt/nuxt/blob/c660b39447f0d5b8790c0826092638d321cd6821/packages/nuxt/src/core/runtime/nitro/no-ssr.ts#L8-L9)
+- `respectNoSSRHeader`is implementable in user-land with [server middleware](https://github.com/nuxt/nuxt/blob/c660b39447f0d5b8790c0826092638d321cd6821/packages/nuxt/src/core/runtime/nitro/no-ssr.ts#L8-L9)
 
 ### Removal of Top-Level `generate` Configuration
 
@@ -1121,8 +1278,8 @@ These options have been set to their current values for some time and we do not
 
 The top-level `generate` configuration option is no longer available in Nuxt 4. This includes all of its properties:
 
-* `generate.exclude` - for excluding routes from prerendering
-* `generate.routes` - for specifying routes to prerender
+- `generate.exclude` - for excluding routes from prerendering
+- `generate.routes` - for specifying routes to prerender
 
 #### Reasons for Change
 

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

@@ -163,7 +163,7 @@ Read more about the options for `hydrate-on-visible`.
 ::
 
 ::note
-Under the hood, this uses Vue's built-in [`hydrateOnVisible` strategy](https://vuejs.org/guide/components/async.html#hydrate-on-visible).
+Under the hood, this uses Vue's built-in [`hydrateOnVisible` strategy](https://vuejs.org/guide/components/async#hydrate-on-visible).
 ::
 
 #### `hydrate-on-idle`
@@ -181,7 +181,7 @@ You can also pass a number which serves as a max timeout.
 ```
 
 ::note
-Under the hood, this uses Vue's built-in [`hydrateOnIdle` strategy](https://vuejs.org/guide/components/async.html#hydrate-on-idle).
+Under the hood, this uses Vue's built-in [`hydrateOnIdle` strategy](https://vuejs.org/guide/components/async#hydrate-on-idle).
 ::
 
 #### `hydrate-on-interaction`
@@ -199,7 +199,7 @@ Hydrates the component after a specified interaction (e.g., click, mouseover).
 If you do not pass an event or list of events, it defaults to hydrating on `pointerenter`, `click` and `focus`.
 
 ::note
-Under the hood, this uses Vue's built-in [`hydrateOnInteraction` strategy](https://vuejs.org/guide/components/async.html#hydrate-on-interaction).
+Under the hood, this uses Vue's built-in [`hydrateOnInteraction` strategy](https://vuejs.org/guide/components/async#hydrate-on-interaction).
 ::
 
 #### `hydrate-on-media-query`
@@ -215,7 +215,7 @@ Hydrates the component when the window matches a media query.
 ```
 
 ::note
-Under the hood, this uses Vue's built-in [`hydrateOnMediaQuery` strategy](https://vuejs.org/guide/components/async.html#hydrate-on-media-query).
+Under the hood, this uses Vue's built-in [`hydrateOnMediaQuery` strategy](https://vuejs.org/guide/components/async#hydrate-on-media-query).
 ::
 
 #### `hydrate-after`

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

@@ -71,7 +71,7 @@ export const useFoo = () => {
 
 ### Access plugin injections
 
-You can access [plugin injections](/docs/4.x/guide/directory-structure/plugins#providing-helpers) from composables:
+You can access [plugin injections](/docs/4.x/guide/directory-structure/app/plugins#providing-helpers) from composables:
 
 ```ts [app/composables/test.ts]
 export const useHello = () => {

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

@@ -11,7 +11,7 @@ For best performance, components placed in this directory will be automatically
 
 ## Enable Layouts
 
-Layouts are enabled by adding [`<NuxtLayout>`](/docs/4.x/api/components/nuxt-layout) to your [`app.vue`](/docs/4.x/guide/directory-structure/app):
+Layouts are enabled by adding [`<NuxtLayout>`](/docs/4.x/api/components/nuxt-layout) to your [`app.vue`](/docs/4.x/guide/directory-structure/app/app):
 
 ```vue [app/app.vue]
 <template>
@@ -34,7 +34,7 @@ If no layout is specified, `app/layouts/default.vue` will be used.
 ::
 
 ::important
-If you only have a single layout in your application, we recommend using [`app.vue`](/docs/4.x/guide/directory-structure/app) instead.
+If you only have a single layout in your application, we recommend using [`app.vue`](/docs/4.x/guide/directory-structure/app/app) instead.
 ::
 
 ::important

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.
 ::