npm - @nuxt/docs-nightly - Versions diffs - 4.1.3-29314777.50febbbb → 4.1.3-29316225.304409da - Mend

@nuxt/docs-nightly 4.1.3-29314777.50febbbb → 4.1.3-29316225.304409da

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (139) hide show

package/1.getting-started/03.configuration.md +19 -19
package/1.getting-started/04.views.md +1 -1
package/1.getting-started/05.assets.md +8 -2
package/1.getting-started/06.styling.md +50 -40
package/1.getting-started/07.routing.md +4 -4
package/1.getting-started/08.seo-meta.md +46 -33
package/1.getting-started/09.transitions.md +38 -33
package/1.getting-started/10.data-fetching.md +47 -39
package/1.getting-started/11.state-management.md +15 -8
package/1.getting-started/12.error-handling.md +6 -4
package/1.getting-started/13.server.md +3 -3
package/1.getting-started/14.layers.md +18 -12
package/1.getting-started/15.prerendering.md +24 -24
package/1.getting-started/16.deployment.md +7 -7
package/1.getting-started/17.testing.md +41 -41
package/1.getting-started/18.upgrade.md +48 -66
package/2.guide/1.directory-structure/1.app/1.components.md +36 -19
package/2.guide/1.directory-structure/1.app/1.composables.md +7 -7
package/2.guide/1.directory-structure/1.app/1.layouts.md +9 -5
package/2.guide/1.directory-structure/1.app/1.middleware.md +20 -14
package/2.guide/1.directory-structure/1.app/1.pages.md +19 -17
package/2.guide/1.directory-structure/1.app/1.plugins.md +17 -17
package/2.guide/1.directory-structure/1.app/1.utils.md +1 -1
package/2.guide/1.directory-structure/1.app/3.app-config.md +6 -6
package/2.guide/1.directory-structure/1.app/3.error.md +4 -4
package/2.guide/1.directory-structure/1.content.md +4 -1
package/2.guide/1.directory-structure/1.modules.md +4 -4
package/2.guide/1.directory-structure/1.public.md +1 -1
package/2.guide/1.directory-structure/1.server.md +28 -28
package/2.guide/1.directory-structure/1.shared.md +1 -1
package/2.guide/2.concepts/1.auto-imports.md +11 -11
package/2.guide/2.concepts/2.vuejs-development.md +5 -5
package/2.guide/2.concepts/3.rendering.md +14 -12
package/2.guide/2.concepts/5.modules.md +2 -2
package/2.guide/2.concepts/7.esm.md +14 -12
package/2.guide/2.concepts/8.typescript.md +4 -4
package/2.guide/3.going-further/1.events.md +2 -2
package/2.guide/3.going-further/1.experimental-features.md +234 -73
package/2.guide/3.going-further/1.features.md +44 -9
package/2.guide/3.going-further/1.internals.md +15 -15
package/2.guide/3.going-further/10.runtime-config.md +7 -7
package/2.guide/3.going-further/2.hooks.md +8 -8
package/2.guide/3.going-further/3.modules.md +76 -74
package/2.guide/3.going-further/4.kit.md +3 -3
package/2.guide/3.going-further/6.nuxt-app.md +1 -1
package/2.guide/3.going-further/7.layers.md +50 -41
package/2.guide/3.going-further/9.debugging.md +2 -2
package/2.guide/4.recipes/1.custom-routing.md +19 -19
package/2.guide/4.recipes/2.vite-plugin.md +3 -3
package/2.guide/4.recipes/3.custom-usefetch.md +9 -9
package/2.guide/4.recipes/4.sessions-and-authentication.md +33 -19
package/2.guide/5.best-practices/performance.md +8 -8
package/3.api/1.components/1.client-only.md +6 -3
package/3.api/1.components/1.nuxt-client-fallback.md +9 -6
package/3.api/1.components/11.teleports.md +4 -1
package/3.api/1.components/12.nuxt-route-announcer.md +7 -7
package/3.api/1.components/13.nuxt-time.md +44 -17
package/3.api/1.components/2.nuxt-page.md +2 -2
package/3.api/1.components/3.nuxt-layout.md +9 -4
package/3.api/1.components/4.nuxt-link.md +38 -18
package/3.api/1.components/6.nuxt-error-boundary.md +11 -9
package/3.api/2.composables/on-prehydrate.md +2 -2
package/3.api/2.composables/use-async-data.md +11 -11
package/3.api/2.composables/use-cookie.md +26 -18
package/3.api/2.composables/use-error.md +1 -1
package/3.api/2.composables/use-fetch.md +13 -13
package/3.api/2.composables/use-head-safe.md +5 -5
package/3.api/2.composables/use-head.md +2 -2
package/3.api/2.composables/use-hydration.md +5 -5
package/3.api/2.composables/use-loading-indicator.md +10 -10
package/3.api/2.composables/use-nuxt-app.md +9 -9
package/3.api/2.composables/use-nuxt-data.md +7 -7
package/3.api/2.composables/use-preview-mode.md +12 -15
package/3.api/2.composables/use-request-fetch.md +1 -1
package/3.api/2.composables/use-request-headers.md +3 -3
package/3.api/2.composables/use-response-header.md +7 -8
package/3.api/2.composables/use-route-announcer.md +3 -3
package/3.api/2.composables/use-router.md +5 -3
package/3.api/2.composables/use-runtime-config.md +6 -6
package/3.api/2.composables/use-runtime-hook.md +1 -1
package/3.api/2.composables/use-seo-meta.md +1 -1
package/3.api/2.composables/use-server-seo-meta.md +1 -1
package/3.api/2.composables/use-state.md +3 -3
package/3.api/3.utils/$fetch.md +5 -3
package/3.api/3.utils/abort-navigation.md +2 -2
package/3.api/3.utils/add-route-middleware.md +3 -3
package/3.api/3.utils/call-once.md +3 -3
package/3.api/3.utils/clear-error.md +1 -1
package/3.api/3.utils/clear-nuxt-data.md +2 -2
package/3.api/3.utils/clear-nuxt-state.md +2 -2
package/3.api/3.utils/create-error.md +1 -1
package/3.api/3.utils/define-lazy-hydration-component.md +13 -13
package/3.api/3.utils/define-nuxt-component.md +5 -5
package/3.api/3.utils/define-nuxt-plugin.md +11 -11
package/3.api/3.utils/define-nuxt-route-middleware.md +2 -2
package/3.api/3.utils/define-page-meta.md +14 -14
package/3.api/3.utils/define-route-rules.md +3 -3
package/3.api/3.utils/navigate-to.md +9 -9
package/3.api/3.utils/preload-components.md +1 -1
package/3.api/3.utils/prerender-routes.md +2 -2
package/3.api/3.utils/refresh-cookie.md +3 -3
package/3.api/3.utils/refresh-nuxt-data.md +9 -4
package/3.api/3.utils/reload-nuxt-app.md +2 -2
package/3.api/3.utils/set-response-status.md +1 -1
package/3.api/3.utils/show-error.md +2 -2
package/3.api/3.utils/update-app-config.md +2 -1
package/3.api/4.commands/prepare.md +4 -0
package/3.api/5.kit/1.modules.md +36 -36
package/3.api/5.kit/10.templates.md +8 -6
package/3.api/5.kit/11.nitro.md +62 -62
package/3.api/5.kit/12.resolving.md +2 -2
package/3.api/5.kit/14.builder.md +1 -0
package/3.api/5.kit/15.examples.md +2 -2
package/3.api/5.kit/16.layers.md +26 -26
package/3.api/5.kit/3.compatibility.md +12 -12
package/3.api/5.kit/4.autoimports.md +12 -12
package/3.api/5.kit/5.components.md +5 -5
package/3.api/5.kit/6.context.md +3 -3
package/3.api/5.kit/7.pages.md +4 -4
package/3.api/5.kit/8.layout.md +1 -1
package/3.api/5.kit/9.plugins.md +5 -4
package/3.api/6.advanced/2.import-meta.md +3 -3
package/3.api/6.nuxt-config.md +293 -858
package/6.bridge/1.overview.md +1 -1
package/6.bridge/10.configuration.md +2 -1
package/6.bridge/2.typescript.md +2 -2
package/6.bridge/3.bridge-composition-api.md +2 -2
package/6.bridge/4.plugins-and-middleware.md +5 -5
package/6.bridge/5.nuxt3-compatible-api.md +11 -8
package/6.bridge/6.meta.md +15 -14
package/6.bridge/8.nitro.md +2 -2
package/6.bridge/9.vite.md +3 -3
package/7.migration/2.configuration.md +17 -15
package/7.migration/4.meta.md +17 -14
package/7.migration/5.plugins-and-middleware.md +5 -5
package/7.migration/6.pages-and-layouts.md +15 -11
package/7.migration/7.component-options.md +3 -3
package/7.migration/8.runtime-config.md +3 -3
package/package.json +1 -1

package/3.api/6.nuxt-config.md CHANGED Viewed

@@ -36,15 +36,15 @@ your alias by prefixing it with `~`.
 ::
 **Example**:
-```js
-import { fileURLToPath } from "node:url";
+```ts
+import { fileURLToPath } from 'node:url'
 export default defineNuxtConfig({
   alias: {
     'images': fileURLToPath(new URL('./assets/images', import.meta.url)),
     'style': fileURLToPath(new URL('./assets/style', import.meta.url)),
-    'data': fileURLToPath(new URL('./assets/other/data', import.meta.url))
-  }
+    'data': fileURLToPath(new URL('./assets/other/data', import.meta.url)),
+  },
 })
 ```
@@ -94,8 +94,8 @@ For example:
 ```ts
 export default defineNuxtConfig({
   app: {
-    baseURL: '/prefix/'
-  }
+    baseURL: '/prefix/',
+  },
 })
 ```
@@ -126,8 +126,8 @@ For example:
 ```ts
 export default defineNuxtConfig({
   app: {
-    cdnURL: 'https://mycdn.org/'
-  }
+    cdnURL: 'https://mycdn.org/',
+  },
 })
 ```
@@ -163,32 +163,34 @@ Set default configuration for `<head>` on every page.
 ```
 **Example**:
-```js
-app: {
-  head: {
-    meta: [
+```ts
+export default defineNuxtConfig({
+  app: {
+    head: {
+      meta: [
       // <meta name="viewport" content="width=device-width, initial-scale=1">
-      { name: 'viewport', content: 'width=device-width, initial-scale=1' }
-    ],
-    script: [
+        { name: 'viewport', content: 'width=device-width, initial-scale=1' },
+      ],
+      script: [
       // <script src="https://myawesome-lib.js"></script>
-      { src: 'https://awesome-lib.js' }
-    ],
-    link: [
+        { src: 'https://awesome-lib.js' },
+      ],
+      link: [
       // <link rel="stylesheet" href="https://myawesome-lib.css">
-      { rel: 'stylesheet', href: 'https://awesome-lib.css' }
-    ],
-    // please note that this is an area that is likely to change
-    style: [
+        { rel: 'stylesheet', href: 'https://awesome-lib.css' },
+      ],
+      // please note that this is an area that is likely to change
+      style: [
       // <style>:root { color: red }</style>
-      { textContent: ':root { color: red }' }
-    ],
-    noscript: [
+        { textContent: ':root { color: red }' },
+      ],
+      noscript: [
       // <noscript>JavaScript is required</noscript>
-      { textContent: 'JavaScript is required' }
-    ]
-  }
-}
+        { textContent: 'JavaScript is required' },
+      ],
+    },
+  },
+})
 ```
 ### `keepalive`
@@ -350,10 +352,12 @@ Set to `true` to enable bundle analysis, or pass an object with options: [for we
 ```
 **Example**:
-```js
-analyze: {
-  analyzerMode: 'static'
-}
+```ts
+export default defineNuxtConfig({
+  analyze: {
+    analyzerMode: 'static',
+  },
+})
 ```
 ### `templates`
@@ -363,13 +367,17 @@ It is recommended to use `addTemplate` from `@nuxt/kit` instead of this option.
 - **Type**: `array`
 **Example**:
-```js
-templates: [
-  {
-    src: '~/modules/support/plugin.js', // `src` can be absolute or relative
-    dst: 'support.js', // `dst` is relative to project `.nuxt` dir
-  }
-]
+```ts
+export default defineNuxtConfig({
+  build: {
+    templates: [
+      {
+        src: '~/modules/support/plugin.js', // `src` can be absolute or relative
+        dst: 'support.js', // `dst` is relative to project `.nuxt` dir
+      },
+    ],
+  },
+})
 ```
 ### `transpile`
@@ -381,8 +389,12 @@ You can also use a function to conditionally transpile. The function will receiv
 - **Type**: `array`
 **Example**:
-```js
-transpile: [({ isLegacy }) => isLegacy && 'ky']
+```ts
+export default defineNuxtConfig({
+  build: {
+    transpile: [({ isLegacy }) => isLegacy && 'ky'],
+  },
+})
 ```
 ## buildDir
@@ -395,10 +407,10 @@ Many tools assume that `.nuxt` is a hidden directory (because it starts with a `
 - **Default:** `"/<rootDir>/.nuxt"`
 **Example**:
-```js
-export default {
-  buildDir: 'nuxt-build'
-}
+```ts
+export default defineNuxtConfig({
+  buildDir: 'nuxt-build',
+})
 ```
 ## buildId
@@ -453,15 +465,17 @@ Nuxt will automatically guess the file type by its extension and use the appropr
 - **Type**: `array`
 **Example**:
-```js
-css: [
+```ts
+export default defineNuxtConfig({
+  css: [
   // Load a Node.js module directly (here it's a Sass file).
-  'bulma',
-  // CSS file in the project
-  '~/assets/css/main.css',
-  // SCSS file in the project
-  '~/assets/css/main.scss'
-]
+    'bulma',
+    // CSS file in the project
+    '~/assets/css/main.css',
+    // SCSS file in the project
+    '~/assets/css/main.scss',
+  ],
+})
 ```
 ## debug
@@ -516,709 +530,145 @@ export default defineNuxtConfig({
   devServer: {
     https: {
       key: './server.key',
-      cert: './server.crt'
-    }
-  }
-})
-```
-### `loadingTemplate`
-Template to show a loading screen
-- **Type**: `function`
-### `port`
-Dev server listening port
-- **Type**: `number`
-- **Default:** `3000`
-### `url`
-Listening dev server URL.
-This should not be set directly as it will always be overridden by the dev server with the full URL (for module and internal use).
-- **Type**: `string`
-- **Default:** `"http://localhost:3000"`
-## devServerHandlers
-Nitro development-only server handlers.
-- **Type**: `array`
-**See**: [Nitro server routes documentation](https://nitro.build/guide/routing)
-## devtools
-Enable Nuxt DevTools for development.
-Breaking changes for devtools might not reflect on the version of Nuxt.
-**See**:  [Nuxt DevTools](https://devtools.nuxt.com/) for more information.
-## dir
-Customize default directory structure used by Nuxt.
-It is better to stick with defaults unless needed.
-### `app`
-- **Type**: `string`
-- **Default:** `"app"`
-### `assets`
-The assets directory (aliased as `~assets` in your build).
-- **Type**: `string`
-- **Default:** `"app/assets"`
-### `layouts`
-The layouts directory, each file of which will be auto-registered as a Nuxt layout.
-- **Type**: `string`
-- **Default:** `"app/layouts"`
-### `middleware`
-The middleware directory, each file of which will be auto-registered as a Nuxt middleware.
-- **Type**: `string`
-- **Default:** `"app/middleware"`
-### `modules`
-The modules directory, each file in which will be auto-registered as a Nuxt module.
-- **Type**: `string`
-- **Default:** `"modules"`
-### `pages`
-The directory which will be processed to auto-generate your application page routes.
-- **Type**: `string`
-- **Default:** `"app/pages"`
-### `plugins`
-The plugins directory, each file of which will be auto-registered as a Nuxt plugin.
-- **Type**: `string`
-- **Default:** `"app/plugins"`
-### `public`
-The directory containing your static files, which will be directly accessible via the Nuxt server and copied across into your `dist` folder when your app is generated.
-- **Type**: `string`
-- **Default:** `"public"`
-### `shared`
-The shared directory. This directory is shared between the app and the server.
-- **Type**: `string`
-- **Default:** `"shared"`
-## esbuild
-### `options`
-Configure shared esbuild options used within Nuxt and passed to other builders, such as Vite or webpack.
-#### `jsxFactory`
-- **Type**: `string`
-- **Default:** `"h"`
-#### `jsxFragment`
-- **Type**: `string`
-- **Default:** `"Fragment"`
-#### `target`
-- **Type**: `string`
-- **Default:** `"esnext"`
-#### `tsconfigRaw`
-- **Type**: `object`
-## experimental
-### `alwaysRunFetchOnKeyChange`
-Whether to run `useFetch` when the key changes, even if it is set to `immediate: false` and it has not been triggered yet.
-`useFetch` and `useAsyncData` will always run when the key changes if `immediate: true` or if it has been already triggered.
-- **Type**: `boolean`
-- **Default:** `true`
-### `appManifest`
-Use app manifests to respect route rules on client-side.
-- **Type**: `boolean`
-- **Default:** `true`
-### `asyncContext`
-Enable native async context to be accessible for nested composables
-- **Type**: `boolean`
-- **Default:** `false`
-**See**: [Nuxt PR #20918](https://github.com/nuxt/nuxt/pull/20918)
-### `asyncEntry`
-Set to true to generate an async entry point for the Vue bundle (for module federation support).
-- **Type**: `boolean`
-- **Default:** `false`
-### `browserDevtoolsTiming`
-Enable timings for Nuxt application hooks in the performance panel of Chromium-based browsers.
-This feature adds performance markers for Nuxt hooks, allowing you to track their execution time in the browser's Performance tab. This is particularly useful for debugging performance issues.
-- **Type**: `boolean`
-- **Default:** `false`
-**Example**:
-```ts
-// nuxt.config.ts
-export default defineNuxtConfig({
-  experimental: {
-    // Enable performance markers for Nuxt hooks in browser devtools
-    browserDevtoolsTiming: true
-  }
-})
-```
-**See**: [PR #29922](https://github.com/nuxt/nuxt/pull/29922)
-**See**: [Chrome DevTools Performance API](https://developer.chrome.com/docs/devtools/performance/extension#tracks)
-### `buildCache`
-Cache Nuxt/Nitro build artifacts based on a hash of the configuration and source files.
-This only works for source files within `srcDir` and `serverDir` for the Vue/Nitro parts of your app.
-- **Type**: `boolean`
-- **Default:** `false`
-### `checkOutdatedBuildInterval`
-Set the time interval (in ms) to check for new builds. Disabled when `experimental.appManifest` is `false`.
-Set to `false` to disable.
-- **Type**: `number`
-- **Default:** `3600000`
-### `clientFallback`
-Whether to enable the experimental `<NuxtClientFallback>` component for rendering content on the client if there's an error in SSR.
-- **Type**: `boolean`
-- **Default:** `false`
-### `clientNodeCompat`
-Automatically polyfill Node.js imports in the client build using `unenv`.
-- **Type**: `boolean`
-- **Default:** `false`
-**See**: [unenv](https://github.com/unjs/unenv)
-**Note:** To make globals like `Buffer` work in the browser, you need to manually inject them.
-```ts
-import { Buffer } from 'node:buffer'
-globalThis.Buffer = globalThis.Buffer || Buffer
-```
-### `compileTemplate`
-Whether to use `lodash.template` to compile Nuxt templates.
-This flag will be removed with the release of v4 and exists only for advance testing within Nuxt v3.12+ or in [the nightly release channel](/docs/4.x/guide/going-further/nightly-release-channel).
-- **Type**: `boolean`
-- **Default:** `true`
-### `componentIslands`
-Experimental component islands support with `<NuxtIsland>` and `.island.vue` files.
-By default it is set to 'auto', which means it will be enabled only when there are islands, server components or server pages in your app.
-- **Type**: `string`
-- **Default:** `"auto"`
-### `configSchema`
-Config schema support
-- **Type**: `boolean`
-- **Default:** `true`
-**See**: [Nuxt Issue #15592](https://github.com/nuxt/nuxt/issues/15592)
-### `cookieStore`
-Enables CookieStore support to listen for cookie updates (if supported by the browser) and refresh `useCookie` ref values.
-- **Type**: `boolean`
-- **Default:** `true`
-**See**: [CookieStore](https://developer.mozilla.org/en-US/docs/Web/API/CookieStore)
-### `crossOriginPrefetch`
-Enable cross-origin prefetch using the Speculation Rules API.
-- **Type**: `boolean`
-- **Default:** `false`
-### `debugModuleMutation`
-Record mutations to `nuxt.options` in module context, helping to debug configuration changes made by modules during the Nuxt initialization phase.
-When enabled, Nuxt will track which modules modify configuration options, making it easier to trace unexpected configuration changes.
-- **Type**: `boolean`
-- **Default:** `false`
-**Example**:
-```ts
-// nuxt.config.ts
-export default defineNuxtConfig({
-  experimental: {
-    // Enable tracking of config mutations by modules
-    debugModuleMutation: true
-  }
-})
-```
-**See**: [PR #30555](https://github.com/nuxt/nuxt/pull/30555)
-### `decorators`
-Enable the use of experimental decorators in Nuxt and Nitro.
-- **Type**: `boolean`
-- **Default:** `false`
-**See**: https://github.com/tc39/proposal-decorators
-### `defaults`
-This allows specifying the default options for core Nuxt components and composables.
-These options will likely be moved elsewhere in the future, such as into `app.config` or into the `app/` directory.
-#### `nuxtLink`
-##### `componentName`
-- **Type**: `string`
-- **Default:** `"NuxtLink"`
-##### `prefetch`
-- **Type**: `boolean`
-- **Default:** `true`
-##### `prefetchOn`
-###### `visibility`
-- **Type**: `boolean`
-- **Default:** `true`
-#### `useAsyncData`
-Options that apply to `useAsyncData` (and also therefore `useFetch`)
-##### `deep`
-- **Type**: `boolean`
-- **Default:** `true`
-##### `errorValue`
-- **Type**: `string`
-- **Default:** `"null"`
-##### `value`
-- **Type**: `string`
-- **Default:** `"null"`
-#### `useFetch`
-### `emitRouteChunkError`
-Emit `app:chunkError` hook when there is an error loading vite/webpack chunks.
-By default, Nuxt will also perform a reload of the new route when a chunk fails to load when navigating to a new route (`automatic`).
-Setting `automatic-immediate` will lead Nuxt to perform a reload of the current route right when a chunk fails to load (instead of waiting for navigation).
-You can disable automatic handling by setting this to `false`, or handle chunk errors manually by setting it to `manual`.
-- **Type**: `string`
-- **Default:** `"automatic"`
-**See**: [Nuxt PR #19038](https://github.com/nuxt/nuxt/pull/19038)
-### `enforceModuleCompatibility`
-Whether Nuxt should stop if a Nuxt module is incompatible.
-- **Type**: `boolean`
-- **Default:** `false`
-### `externalVue`
-Externalize `vue`, `@vue/*` and `vue-router` when building.
-- **Type**: `boolean`
-- **Default:** `true`
-**See**: [Nuxt Issue #13632](https://github.com/nuxt/nuxt/issues/13632)
-### `extraPageMetaExtractionKeys`
-Configure additional keys to extract from the page metadata when using `scanPageMeta`.
-This allows modules to access additional metadata from the page metadata. It's recommended to augment the NuxtPage types with your keys.
-- **Type**: `array`
-### `granularCachedData`
-Whether to call and use the result from `getCachedData` on manual refresh for `useAsyncData` and `useFetch`.
-- **Type**: `boolean`
-- **Default:** `false`
-### `headNext`
-Use new experimental head optimisations:
-- Add the capo.js head plugin in order to render tags in of the head in a more performant way. - Uses the hash hydration plugin to reduce initial hydration
-- **Type**: `boolean`
-- **Default:** `true`
-**See**: [Nuxt Discussion #22632](https://github.com/nuxt/nuxt/discussions/22632)
-### `inlineRouteRules`
-Allow defining `routeRules` directly within your `~/pages` directory using `defineRouteRules`.
-Rules are converted (based on the path) and applied for server requests. For example, a rule defined in `~/pages/foo/bar.vue` will be applied to `/foo/bar` requests. A rule in `~/pages/foo/[id].vue` will be applied to `/foo/**` requests.
-For more control, such as if you are using a custom `path` or `alias` set in the page's `definePageMeta`, you should set `routeRules` directly within your `nuxt.config`.
-- **Type**: `boolean`
-- **Default:** `false`
-### `lazyHydration`
-Enable automatic configuration of hydration strategies for `<Lazy>` components.
-This feature intelligently determines when to hydrate lazy components based on visibility, idle time, or other triggers, improving performance by deferring hydration of components until they're needed.
-- **Type**: `boolean`
-- **Default:** `true`
-**Example**:
-```ts
-// nuxt.config.ts
-export default defineNuxtConfig({
-  experimental: {
-    lazyHydration: true // Enable smart hydration strategies for Lazy components
-  }
-})
-// In your Vue components
-<template>
-  <Lazy>
-    <ExpensiveComponent />
-  </Lazy>
-</template>
-```
-**See**: [PR #26468](https://github.com/nuxt/nuxt/pull/26468)
-### `localLayerAliases`
-Resolve `~`, `~~`, `@` and `@@` aliases located within layers with respect to their layer source and root directories.
-- **Type**: `boolean`
-- **Default:** `true`
-### `navigationRepaint`
-Wait for a single animation frame before navigation, which gives an opportunity for the browser to repaint, acknowledging user interaction.
-It can reduce INP when navigating on prerendered routes.
-- **Type**: `boolean`
-- **Default:** `true`
-### `noVueServer`
-Disable vue server renderer endpoint within nitro.
-- **Type**: `boolean`
-- **Default:** `false`
-### `normalizeComponentNames`
-Ensure that auto-generated Vue component names match the full component name you would use to auto-import the component.
-- **Type**: `boolean`
-- **Default:** `false`
-### `parseErrorData`
-Whether to parse `error.data` when rendering a server error page.
-- **Type**: `boolean`
-- **Default:** `false`
-### `payloadExtraction`
-When this option is enabled (by default) payload of pages that are prerendered are extracted
-- **Type**: `boolean`
-- **Default:** `true`
-### `pendingWhenIdle`
-For `useAsyncData` and `useFetch`, whether `pending` should be `true` when data has not yet started to be fetched.
-- **Type**: `boolean`
-- **Default:** `true`
-### `polyfillVueUseHead`
-Whether or not to add a compatibility layer for modules, plugins or user code relying on the old `@vueuse/head` API.
-This is disabled to reduce the client-side bundle by ~0.5kb.
-- **Type**: `boolean`
-- **Default:** `false`
-### `purgeCachedData`
-Whether to clean up Nuxt static and asyncData caches on route navigation.
-Nuxt will automatically purge cached data from `useAsyncData` and `nuxtApp.static.data`. This helps prevent memory leaks and ensures fresh data is loaded when needed, but it is possible to disable it.
-- **Type**: `boolean`
-- **Default:** `true`
-**Example**:
-```ts
-// nuxt.config.ts
-export default defineNuxtConfig({
-  experimental: {
-    // Disable automatic cache cleanup (default is true)
-    purgeCachedData: false
-  }
-})
-```
-**See**: [PR #31379](https://github.com/nuxt/nuxt/pull/31379)
-### `relativeWatchPaths`
-Whether to provide relative paths in the `builder:watch` hook.
-This flag will be removed with the release of v4 and exists only for advance testing within Nuxt v3.12+ or in [the nightly release channel](/docs/4.x/guide/going-further/nightly-release-channel).
-- **Type**: `boolean`
-- **Default:** `true`
-### `renderJsonPayloads`
-Render JSON payloads with support for revivifying complex types.
-- **Type**: `boolean`
-- **Default:** `true`
+      cert: './server.crt',
+    },
+  },
+})
+```
-### `resetAsyncDataToUndefined`
+### `loadingTemplate`
-Whether `clear` and `clearNuxtData` should reset async data to its _default_ value or update it to `null`/`undefined`.
+Template to show a loading screen
-- **Type**: `boolean`
-- **Default:** `true`
+- **Type**: `function`
-### `respectNoSSRHeader`
+### `port`
-Allow disabling Nuxt SSR responses by setting the `x-nuxt-no-ssr` header.
+Dev server listening port
-- **Type**: `boolean`
-- **Default:** `false`
+- **Type**: `number`
+- **Default:** `3000`
-### `restoreState`
+### `url`
-Whether to restore Nuxt app state from `sessionStorage` when reloading the page after a chunk error or manual `reloadNuxtApp()` call.
+Listening dev server URL.
-To avoid hydration errors, it will be applied only after the Vue app has been mounted, meaning there may be a flicker on initial load.
-Consider carefully before enabling this as it can cause unexpected behavior, and consider providing explicit keys to `useState` as auto-generated keys may not match across builds.
+This should not be set directly as it will always be overridden by the dev server with the full URL (for module and internal use).
-- **Type**: `boolean`
-- **Default:** `false`
+- **Type**: `string`
+- **Default:** `"http://localhost:3000"`
-### `scanPageMeta`
+## devServerHandlers
-Allow exposing some route metadata defined in `definePageMeta` at build-time to modules (alias, name, path, redirect, props, middleware).
+Nitro development-only server handlers.
-This only works with static or strings/arrays rather than variables or conditional assignment.
+- **Type**: `array`
-- **Type**: `boolean`
-- **Default:** `true`
+**See**: [Nitro server routes documentation](https://nitro.build/guide/routing)
-**See**: [Nuxt Issues #24770](https://github.com/nuxt/nuxt/issues/24770)
+## devtools
-### `sharedPrerenderData`
+Enable Nuxt DevTools for development.
-Automatically share payload _data_ between pages that are prerendered. This can result in a significant performance improvement when prerendering sites that use `useAsyncData` or `useFetch` and fetch the same data in different pages.
+Breaking changes for devtools might not reflect on the version of Nuxt.
-It is particularly important when enabling this feature to make sure that any unique key of your data is always resolvable to the same data. For example, if you are using `useAsyncData` to fetch data related to a particular page, you should provide a key that uniquely matches that data. (`useFetch` should do this automatically for you.)
+**See**:  [Nuxt DevTools](https://devtools.nuxt.com/) for more information.
-- **Type**: `boolean`
-- **Default:** `false`
+## dir
-**Example**:
-```ts
-// 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}`)
-})
-// 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}`)
-})
-```
+Customize default directory structure used by Nuxt.
-### `spaLoadingTemplateLocation`
+It is better to stick with defaults unless needed.
-Keep showing the spa-loading-template until suspense:resolve
+### `app`
 - **Type**: `string`
-- **Default:** `"within"`
+- **Default:** `"app"`
-**See**: [Nuxt Issues #24770](https://github.com/nuxt/nuxt/issues/21721)
+### `assets`
-### `templateImportResolution`
+The assets directory (aliased as `~assets` in your build).
-Disable resolving imports into Nuxt templates from the path of the module that added the template.
+- **Type**: `string`
+- **Default:** `"app/assets"`
-By default, Nuxt attempts to resolve imports in templates relative to the module that added them. Setting this to `false` disables this behavior, which may be useful if you're experiencing resolution conflicts in certain environments.
+### `layouts`
-- **Type**: `boolean`
-- **Default:** `true`
+The layouts directory, each file of which will be auto-registered as a Nuxt layout.
-**Example**:
-```ts
-// nuxt.config.ts
-export default defineNuxtConfig({
-  experimental: {
-    // Disable template import resolution from module path
-    templateImportResolution: false
-  }
-})
-```
+- **Type**: `string`
+- **Default:** `"app/layouts"`
-**See**: [PR #31175](https://github.com/nuxt/nuxt/pull/31175)
+### `middleware`
-### `templateRouteInjection`
+The middleware directory, each file of which will be auto-registered as a Nuxt middleware.
-By default the route object returned by the auto-imported `useRoute()` composable is kept in sync with the current page in view in `<NuxtPage>`. This is not true for `vue-router`'s exported `useRoute` or for the default `$route` object available in your Vue templates.
+- **Type**: `string`
+- **Default:** `"app/middleware"`
-By enabling this option a mixin will be injected to keep the `$route` template object in sync with Nuxt's managed `useRoute()`.
+### `modules`
-- **Type**: `boolean`
-- **Default:** `true`
+The modules directory, each file in which will be auto-registered as a Nuxt module.
-### `templateUtils`
+- **Type**: `string`
+- **Default:** `"modules"`
-Whether to provide a legacy `templateUtils` object (with `serialize`, `importName` and `importSources`) when compiling Nuxt templates.
+### `pages`
-This flag will be removed with the release of v4 and exists only for advance testing within Nuxt v3.12+ or in [the nightly release channel](/docs/4.x/guide/going-further/nightly-release-channel).
+The directory which will be processed to auto-generate your application page routes.
-- **Type**: `boolean`
-- **Default:** `true`
+- **Type**: `string`
+- **Default:** `"app/pages"`
-### `treeshakeClientOnly`
+### `plugins`
-Tree shakes contents of client-only components from server bundle.
+The plugins directory, each file of which will be auto-registered as a Nuxt plugin.
-- **Type**: `boolean`
-- **Default:** `true`
+- **Type**: `string`
+- **Default:** `"app/plugins"`
-**See**: [Nuxt PR #5750](https://github.com/nuxt/framework/pull/5750)
+### `public`
-### `typedPages`
+The directory containing your static files, which will be directly accessible via the Nuxt server and copied across into your `dist` folder when your app is generated.
-Enable the new experimental typed router using [unplugin-vue-router](https://github.com/posva/unplugin-vue-router).
+- **Type**: `string`
+- **Default:** `"public"`
-- **Type**: `boolean`
-- **Default:** `false`
+### `shared`
-### `viewTransition`
+The shared directory. This directory is shared between the app and the server.
-Enable View Transition API integration with client-side router.
+- **Type**: `string`
+- **Default:** `"shared"`
-- **Type**: `boolean`
-- **Default:** `false`
+## esbuild
+### `options`
-**See**: [View Transitions API](https://developer.chrome.com/docs/web-platform/view-transitions)
+Configure shared esbuild options used within Nuxt and passed to other builders, such as Vite or webpack.
-### `watcher`
+#### `jsxFactory`
-Set an alternative watcher that will be used as the watching service for Nuxt.
+- **Type**: `string`
+- **Default:** `"h"`
-Nuxt uses 'chokidar-granular' if your source directory is the same as your root directory . This will ignore top-level directories (like `node_modules` and `.git`) that are excluded from watching.
-You can set this instead to `parcel` to use `@parcel/watcher`, which may improve performance in large projects or on Windows platforms.
-You can also set this to `chokidar` to watch all files in your source directory.
+#### `jsxFragment`
 - **Type**: `string`
-- **Default:** `"chokidar"`
+- **Default:** `"Fragment"`
-**See**: [chokidar](https://github.com/paulmillr/chokidar)
+#### `target`
-**See**: [@parcel/watcher](https://github.com/parcel-bundler/watcher)
+- **Type**: `string`
+- **Default:** `"esnext"`
-### `writeEarlyHints`
+#### `tsconfigRaw`
-Write early hints when using node server.
+- **Type**: `object`
-- **Type**: `boolean`
-- **Default:** `false`
+## experimental
-::callout
-**Note**: nginx does not support 103 Early hints in the current version.
+::read-more{to="/docs/4.x/guide/going-further/experimental-features"} Learn more about Nuxt's experimental features.
 ::
 ## extends
@@ -1251,65 +701,13 @@ The extensions that should be resolved by the Nuxt resolver.
 ## features
-Some features of Nuxt are available on an opt-in basis, or can be disabled based on your needs.
-### `devLogs`
-Stream server logs to the client as you are developing. These logs can be handled in the `dev:ssr-logs` hook.
-If set to `silent`, the logs will not be printed to the browser console.
-- **Type**: `boolean`
-- **Default:** `false`
-### `inlineStyles`
-Inline styles when rendering HTML (currently vite only).
-You can also pass a function that receives the path of a Vue component and returns a boolean indicating whether to inline the styles for that component.
-- **Type**: `boolean`
-- **Default:** `(id) => id.includes('.vue')`
-### `noScripts`
-Turn off rendering of Nuxt scripts and JS resource hints. You can also disable scripts more granularly within `routeRules`.
-If set to 'production' or `true`, JS will be disabled in production mode only.
-- **Type**: `boolean`
-- **Default:** `false`
+::read-more{to="/docs/4.x/guide/going-further/features#features"} Learn more about Nuxt's opt-in features.
+::
 ## future
-`future` is for early opting-in to new features that will become default in a future (possibly major) version of the framework.
-### `compatibilityVersion`
-This is used for enabling early access to Nuxt features or flags.
-It is not configurable yet in Nuxt 4, but once we begin merging breaking changes for v5, it will be possible to enable it.
-### `multiApp`
-This enables early access to the experimental multi-app support.
-- **Type**: `boolean`
-- **Default:** `false`
-**See**: [Nuxt Issue #21635](https://github.com/nuxt/nuxt/issues/21635)
-### `typescriptBundlerResolution`
-This enables 'Bundler' module resolution mode for TypeScript, which is the recommended setting for frameworks like Nuxt and Vite.
-It improves type support when using modern libraries with `exports`.
-You can set it to false to use the legacy 'Node' mode, which is the default for TypeScript.
-- **Type**: `boolean`
-- **Default:** `true`
-**See**: [TypeScript PR implementing `bundler` module resolution](https://github.com/microsoft/TypeScript/pull/51669)
+::read-more{to="/docs/4.x/guide/going-further/features#features"} Learn more about opting-in to new features that will become default in a future (possibly major) version of the framework,
+::
 ## hooks
@@ -1319,22 +717,23 @@ Internally, hooks follow a naming pattern using colons (e.g., build:done).
 For ease of configuration, you can also structure them as an hierarchical object in `nuxt.config` (as below).
 **Example**:
-```js
+```ts
 import fs from 'node:fs'
 import path from 'node:path'
-export default {
+export default defineNuxtConfig({
   hooks: {
     build: {
-      done(builder) {
+      done (builder) {
         const extraFilePath = path.join(
           builder.nuxt.options.buildDir,
-          'extra-file'
+          'extra-file',
         )
         fs.writeFileSync(extraFilePath, 'Something extra')
-      }
-    }
-  }
-}
+      },
+    },
+  },
+})
 ```
 ## ignore
@@ -1363,10 +762,12 @@ Pass options directly to `node-ignore` (which is used by Nuxt to ignore files).
 **See**: [node-ignore](https://github.com/kaelzhang/node-ignore)
 **Example**:
-```js
-ignoreOptions: {
-  ignorecase: false
-}
+```ts
+export default defineNuxtConfig({
+  ignoreOptions: {
+    ignorecase: false,
+  },
+})
 ```
 ## ignorePrefix
@@ -1389,11 +790,13 @@ An array of custom directories that will be auto-imported. Note that this option
 - **Type**: `array`
 **Example**:
-```js
-imports: {
+```ts
+export default defineNuxtConfig({
+  imports: {
   // Auto-import pinia stores defined in `~/stores`
-  dirs: ['stores']
-}
+    dirs: ['stores'],
+  },
+})
 ```
 ### `global`
@@ -1432,17 +835,19 @@ directory are executed, and they load in alphabetical order.
 ::
 **Example**:
-```js
-modules: [
+```ts
+export default defineNuxtConfig({
+  modules: [
   // Using package name
-  '@nuxtjs/axios',
-  // Relative to your project srcDir
-  '~/modules/awesome.js',
-  // Providing options
-  ['@nuxtjs/google-analytics', { ua: 'X1234567' }],
-  // Inline definition
-  function () {}
-]
+    '@nuxt/scripts',
+    // Relative to your project srcDir
+    '~/custom-modules/awesome.js',
+    // Providing options
+    ['@nuxtjs/google-analytics', { ua: 'X1234567' }],
+    // Inline definition
+    function () {},
+  ],
+})
 ```
 ## modulesDir
@@ -1461,10 +866,10 @@ Setting this field may be necessary if your project is organized as a yarn works
 ```
 **Example**:
-```js
-export default {
-  modulesDir: ['../../node_modules']
-}
+```ts
+export default defineNuxtConfig({
+  modulesDir: ['../../node_modules'],
+})
 ```
 ## nitro
@@ -1600,8 +1005,17 @@ Tree shake code from specific builds.
 Tree shake composables from the server or client builds.
 **Example**:
-```js
-treeShake: { client: { myPackage: ['useServerOnlyComposable'] } }
+```ts
+export default defineNuxtConfig({
+  optimization: {
+    treeShake: {
+      composables: {
+        client: { vue: ['onMounted'] },
+        server: { vue: ['onServerPrefetch'] },
+      },
+    },
+  },
+})
 ```
 ##### `client`
@@ -1655,10 +1069,12 @@ Whether to use the vue-router integration in Nuxt 3. If you do not provide a val
 Additionally, you can provide a glob pattern or an array of patterns to scan only certain files for pages.
 **Example**:
-```js
-pages: {
-  pattern: ['**\/*\/*.vue', '!**\/*.spec.*'],
-}
+```ts
+export default defineNuxtConfig({
+  pages: {
+    pattern: ['**/*/*.vue', '!**/*.spec.*'],
+  },
+})
 ```
 ## plugins
@@ -1679,15 +1095,17 @@ need to customize their order. All plugins are deduplicated by their src path.
 **See**: [`app/plugins/` directory documentation](https://nuxt.com/docs/4.x/guide/directory-structure/plugins)
 **Example**:
-```js
-plugins: [
-  '~/plugins/foo.client.js', // only in client side
-  '~/plugins/bar.server.js', // only in server side
-  '~/plugins/baz.js', // both client & server
-  { src: '~/plugins/both-sides.js' },
-  { src: '~/plugins/client-only.js', mode: 'client' }, // only on client side
-  { src: '~/plugins/server-only.js', mode: 'server' } // only on server side
-]
+```ts
+export default defineNuxtConfig({
+  plugins: [
+    '~/custom-plugins/foo.client.js', // only in client side
+    '~/custom-plugins/bar.server.js', // only in server side
+    '~/custom-plugins/baz.js', // both client & server
+    { src: '~/custom-plugins/both-sides.js' },
+    { src: '~/custom-plugins/client-only.js', mode: 'client' }, // only on client side
+    { src: '~/custom-plugins/server-only.js', mode: 'server' }, // only on server side
+  ],
+})
 ```
 ## postcss
@@ -1789,15 +1207,15 @@ Values are automatically replaced by matching env variables at runtime, e.g. set
 ```
 **Example**:
-```js
-export default {
- runtimeConfig: {
+```ts
+export default defineNuxtConfig({
+  runtimeConfig: {
     apiKey: '', // Default to an empty string, automatically set at runtime using process.env.NUXT_API_KEY
     public: {
-       baseURL: '' // Exposed to the frontend as well.
-    }
-  }
-}
+      baseURL: '', // Exposed to the frontend as well.
+    },
+  },
+})
 ```
 ## serverDir
@@ -1825,10 +1243,12 @@ Each handler accepts the following options:
 ::
 **Example**:
-```js
-serverHandlers: [
-  { route: '/path/foo/**:name', handler: '~/server/foohandler.ts' }
-]
+```ts
+export default defineNuxtConfig({
+  serverHandlers: [
+    { route: '/path/foo/**:name', handler: '~/server/foohandler.ts' },
+  ],
+})
 ```
 ## sourcemap
@@ -1911,10 +1331,10 @@ If a relative path is specified, it will be relative to the `rootDir`.
 - **Default:** `"app"` (Nuxt 4), `"."` (Nuxt 3 with `compatibilityMode: 3`)
 **Example**:
-```js
-export default {
-  srcDir: 'app/'
-}
+```ts
+export default defineNuxtConfig({
+  srcDir: 'app/',
+})
 ```
 This expects the following folder structure:
 ```bash
@@ -2062,8 +1482,9 @@ Enable the legacy compatibility mode for `unhead` module. This applies the follo
 **Example**:
 ```ts
 export default defineNuxtConfig({
- unhead: {
-  legacy: true
+  unhead: {
+    legacy: true,
+  },
 })
 ```
@@ -2082,10 +1503,11 @@ An object that will be passed to `renderSSRHead` to customize the output.
 **Example**:
 ```ts
 export default defineNuxtConfig({
- unhead: {
-  renderSSRHeadOptions: {
-   omitLineBreaks: true
-  }
+  unhead: {
+    renderSSRHeadOptions: {
+      omitLineBreaks: true,
+    },
+  },
 })
 ```
@@ -2423,7 +1845,7 @@ Hard-replaces `typeof process`, `typeof window` and `typeof document` to tree-sh
 ### `analyze`
-Nuxt uses `webpack-bundle-analyzer` to visualize your bundles and how to optimize them.
+If you are using webpack, Nuxt uses `webpack-bundle-analyzer` to visualize your bundles and how to optimize them.
 Set to `true` to enable bundle analysis, or pass an object with options: [for webpack](https://github.com/webpack-contrib/webpack-bundle-analyzer#options-for-plugin) or [for vite](https://github.com/btd/rollup-plugin-visualizer#options).
@@ -2438,10 +1860,14 @@ Set to `true` to enable bundle analysis, or pass an object with options: [for we
 ```
 **Example**:
-```js
-analyze: {
-  analyzerMode: 'static'
-}
+```ts
+export default defineNuxtConfig({
+  webpack: {
+    analyze: {
+      analyzerMode: 'static',
+    },
+  },
+})
 ```
 ### `cssSourceMap`
@@ -2474,16 +1900,16 @@ Using [mini-css-extract-plugin](https://github.com/webpack-contrib/mini-css-extr
 - **Default:** `true`
 **Example**:
-```js
-export default {
+```ts
+export default defineNuxtConfig({
   webpack: {
     extractCSS: true,
     // or
     extractCSS: {
-      ignoreOrder: true
-    }
-  }
-}
+      ignoreOrder: true,
+    },
+  },
+})
 ```
 If you want to extract all your CSS to a single file, there is a workaround for this.
@@ -2493,8 +1919,8 @@ can also improve page performance by downloading and resolving only those resour
 that are needed.
 **Example**:
-```js
-export default {
+```ts
+export default defineNuxtConfig({
   webpack: {
     extractCSS: true,
     optimization: {
@@ -2504,13 +1930,13 @@ export default {
             name: 'styles',
             test: /\.(css|vue)$/,
             chunks: 'all',
-            enforce: true
-          }
-        }
-      }
-    }
-  }
-}
+            enforce: true,
+          },
+        },
+      },
+    },
+  },
+})
 ```
 ### `filenames`
@@ -2527,10 +1953,14 @@ as most browsers will cache the asset and not detect the changes on first load.
 This example changes fancy chunk names to numerical ids:
 **Example**:
-```js
-filenames: {
-  chunk: ({ isDev }) => (isDev ? '[name].js' : '[id].[contenthash].js')
-}
+```ts
+export default defineNuxtConfig({
+  webpack: {
+    filenames: {
+      chunk: ({ isDev }) => (isDev ? '[name].js' : '[id].[contenthash].js'),
+    },
+  },
+})
 ```
 #### `app`
@@ -2639,8 +2069,8 @@ See [css-loader](https://github.com/webpack-contrib/css-loader) for available op
 **See**: [`file-loader` Options](https://github.com/webpack-contrib/file-loader#options)
 **Default**:
-```ts
-{ esModule: false }
+```json
+{ "esModule": false }
 ```
 ##### `esModule`
@@ -2658,8 +2088,8 @@ See [css-loader](https://github.com/webpack-contrib/css-loader) for available op
 **See**: [`file-loader` Options](https://github.com/webpack-contrib/file-loader#options)
 **Default**:
-```ts
-{ esModule: false }
+```json
+{ "esModule": false }
 ```
 ##### `esModule`
@@ -2677,8 +2107,8 @@ See [css-loader](https://github.com/webpack-contrib/css-loader) for available op
 **See**: [`file-loader` Options](https://github.com/webpack-contrib/file-loader#options)
 **Default**:
-```ts
-{ esModule: false }
+```json
+{ "esModule": false }
 ```
 ##### `esModule`
@@ -2711,10 +2141,10 @@ See [css-loader](https://github.com/webpack-contrib/css-loader) for available op
 **See**: [`sass-loader` Options](https://github.com/webpack-contrib/sass-loader#options)
 **Default**:
-```ts
+```json
 {
-  sassOptions: {
-    indentedSyntax: true
+  "sassOptions": {
+    "indentedSyntax": true
   }
 }
 ```
@@ -2849,15 +2279,20 @@ Add webpack plugins.
 - **Type**: `array`
 **Example**:
-```js
+```ts
 import webpack from 'webpack'
 import { version } from './package.json'
-// ...
-plugins: [
-  new webpack.DefinePlugin({
-    'process.VERSION': version
-  })
-]
+export default defineNuxtConfig({
+  webpack: {
+    plugins: [
+      // ...
+      new webpack.DefinePlugin({
+        'process.VERSION': version,
+      }),
+    ],
+  },
+})
 ```
 ### `postcss`