@nuxt/docs 4.2.2 → 4.3.0

package/3.guide/4.modules/6.best-practices.md

@@ -0,0 +1,104 @@
+---
+title: "Follow Best Practices"
+description: "Build performant and maintainable Nuxt modules with these guidelines."
+---
+
+With great power comes great responsibility. While modules are powerful, here are some best practices to keep in mind while authoring modules to keep applications performant and developer experience great.
+
+## Handle Async Setup
+
+As we've seen, Nuxt modules can be asynchronous. For example, you may want to develop a module that needs fetching some API or calling an async function.
+
+However, be careful with asynchronous behaviors as Nuxt will wait for your module to setup before going to the next module and starting the development server, build process, etc. Prefer deferring time-consuming logic to Nuxt hooks.
+
+::warning
+If your module takes more than **1 second** to setup, Nuxt will emit a warning about it.
+::
+
+## Prefix Your Exports
+
+Nuxt modules should provide an explicit prefix for any exposed configuration, plugin, API, composable, component, or server route to avoid conflicts with other modules, Nuxt internals, or user-defined code.
+
+Ideally, prefix them with your module's name. For example, if your module is called `nuxt-foo`:
+
+| Type | ❌ Avoid | ✅ Prefer |
+| --- | --- | --- |
+| Components | `<Button>`, `<Modal>` | `<FooButton>`, `<FooModal>` |
+| Composables | `useData()`, `useModal()` | `useFooData()`, `useFooModal()` |
+| Server routes | `/api/track`, `/api/data` | `/api/_foo/track`, `/api/_foo/data` |
+
+### Server Routes
+
+This is particularly important for server routes, where common paths like `/api/auth`, `/api/login`, or `/api/user` are very likely already used by the application.
+
+Use a unique prefix based on your module name:
+- `/api/_foo/...` (using underscore prefix)
+- `/_foo/...` (for non-API routes)
+
+## Use Lifecycle Hooks
+
+When your module needs to perform one-time setup tasks (like generating configuration files, setting up databases, or installing dependencies), use lifecycle hooks instead of running the logic in your main `setup` function.
+
+```ts
+import { addServerHandler, defineNuxtModule } from 'nuxt/kit'
+import semver from 'semver'
+
+export default defineNuxtModule({
+  meta: {
+    name: 'my-database-module',
+    version: '1.0.0',
+  },
+  async onInstall (nuxt) {
+    // One-time setup: create database schema, generate config files, etc.
+    await generateDatabaseConfig(nuxt.options.rootDir)
+  },
+  async onUpgrade (nuxt, options, previousVersion) {
+    // Handle version-specific migrations
+    if (semver.lt(previousVersion, '1.0.0')) {
+      await migrateLegacyData()
+    }
+  },
+  setup (options, nuxt) {
+    // Regular setup logic that runs on every build
+    addServerHandler({ /* ... */ })
+  },
+})
+```
+
+This pattern prevents unnecessary work on every build and provides a better developer experience. See the [lifecycle hooks documentation](/docs/4.x/api/kit/modules#using-lifecycle-hooks-for-module-installation-and-upgrade) for more details.
+
+## Be TypeScript Friendly
+
+Nuxt has first-class TypeScript integration for the best developer experience.
+
+Exposing types and using TypeScript to develop modules benefits users even when not using TypeScript directly.
+
+## Use ESM Syntax
+
+Nuxt relies on native ESM. Please read [Native ES Modules](/docs/4.x/guide/concepts/esm) for more information.
+
+## Document Your Module
+
+Consider documenting module usage in the readme file:
+
+- Why use this module?
+- How to use this module?
+- What does this module do?
+
+Linking to the integration website and documentation is always a good idea.
+
+## Provide a Demo
+
+It's a good practice to make a minimal reproduction with your module and [StackBlitz](https://nuxt.new/s/v4) that you add to your module readme.
+
+This not only provides potential users of your module a quick and easy way to experiment with the module but also an easy way for them to build minimal reproductions they can send you when they encounter issues.
+
+## Stay Version Agnostic
+
+Nuxt, Nuxt Kit, and other new toolings are made to have both forward and backward compatibility in mind.
+
+Please use "X for Nuxt" instead of "X for Nuxt 3" to avoid fragmentation in the ecosystem and prefer using `meta.compatibility` to set Nuxt version constraints.
+
+## Follow Starter Conventions
+
+The module starter comes with a default set of tools and configurations (e.g. ESLint configuration). If you plan on open-sourcing your module, sticking with those defaults ensures your module shares a consistent coding style with other [community modules](/modules) out there, making it easier for others to contribute.

package/3.guide/4.modules/7.ecosystem.md

@@ -0,0 +1,32 @@
+---
+title: "Publish & Share Your Module"
+description: "Join the Nuxt module ecosystem and publish your module to npm."
+---
+
+The [Nuxt module ecosystem](/modules) represents more than 35 million monthly NPM downloads and provides extended functionalities and integrations with all sort of tools. You can be part of this ecosystem!
+
+::tip{icon="i-lucide-video" to="https://vueschool.io/lessons/exploring-nuxt-modules-ecosystem-and-module-types?friend=nuxt" target="_blank"}
+Watch Vue School video about Nuxt module types.
+::
+
+## Understand Module Types
+
+**Official modules** are modules prefixed (scoped) with `@nuxt/` (e.g. [`@nuxt/content`](https://content.nuxt.com)). They are made and maintained actively by the Nuxt team. Like with the framework, contributions from the community are more than welcome to help make them better!
+
+**Community modules** are modules prefixed (scoped) with `@nuxtjs/` (e.g. [`@nuxtjs/tailwindcss`](https://tailwindcss.nuxtjs.org)). They are proven modules made and maintained by community members. Again, contributions are welcome from anyone.
+
+**Third-party and other community modules** are modules (often) prefixed with `nuxt-`. Anyone can make them, using this prefix allows these modules to be discoverable on npm. This is the best starting point to draft and try an idea!
+
+**Private or personal modules** are modules made for your own use case or company. They don't need to follow any naming rules to work with Nuxt and are often seen scoped under an npm organization (e.g. `@my-company/nuxt-auth`)
+
+## List Your Module
+
+Any community modules are welcome to be listed on [the module list](/modules). To be listed, [open an issue in the nuxt/modules](https://github.com/nuxt/modules/issues/new?template=module_request.yml) repository. The Nuxt team can help you to apply best practices before listing.
+
+## Join nuxt-modules
+
+By moving your modules to [nuxt-modules](https://github.com/nuxt-modules), there is always someone else to help, and this way, we can join forces to make one perfect solution.
+
+If you have an already published and working module, and want to transfer it to `nuxt-modules`, [open an issue in nuxt/modules](https://github.com/nuxt/modules/issues/new).
+
+By joining `nuxt-modules` we can rename your community module under the `@nuxtjs/` scope and provide a subdomain (e.g. `my-module.nuxtjs.org`) for its documentation.

package/3.guide/4.modules/index.md

@@ -0,0 +1,36 @@
+---
+title: 'Module Author Guide'
+titleTemplate: '%s'
+description: 'Learn how to create a Nuxt module to integrate, enhance or extend any Nuxt applications.'
+navigation: false
+surround: false
+---
+
+Nuxt's [configuration](/docs/4.x/api/nuxt-config) and [hooks](/docs/4.x/guide/going-further/hooks) systems make it possible to customize every aspect of Nuxt and add any integration you might need (Vue plugins, CMS, server routes, components, logging, etc.).
+
+**Nuxt modules** are functions that sequentially run when starting Nuxt in development mode using `nuxt dev` or building a project for production with `nuxt build`.
+With modules, you can encapsulate, properly test, and share custom solutions as npm packages without adding unnecessary boilerplate to your project, or requiring changes to Nuxt itself.
+
+::card-group{class="sm:grid-cols-1"}
+  ::card{icon="i-lucide-rocket" title="Create Your First Module" to="/docs/4.x/guide/modules/getting-started"}
+  Learn how to create your first Nuxt module using the official starter template.
+  ::
+  ::card{icon="i-lucide-box" title="Understand Module Structure" to="/docs/4.x/guide/modules/module-anatomy"}
+  Learn how Nuxt modules are structured and how to define them.
+  ::
+  ::card{icon="i-lucide-code" title="Add Plugins, Components & More" to="/docs/4.x/guide/modules/recipes-basics"}
+  Learn how to inject plugins, components, composables and server routes from your module.
+  ::
+  ::card{icon="i-lucide-layers" title="Use Hooks & Extend Types" to="/docs/4.x/guide/modules/recipes-advanced"}
+  Master lifecycle hooks, virtual files and TypeScript declarations in your modules.
+  ::
+  ::card{icon="i-lucide-test-tube" title="Test Your Module" to="/docs/4.x/guide/modules/testing"}
+  Learn how to test your Nuxt module with unit, integration and E2E tests.
+  ::
+  ::card{icon="i-lucide-medal" title="Follow Best Practices" to="/docs/4.x/guide/modules/best-practices"}
+  Build performant and maintainable Nuxt modules with these guidelines.
+  ::
+  ::card{icon="i-lucide-globe" title="Publish & Share Your Module" to="/docs/4.x/guide/modules/ecosystem"}
+  Join the Nuxt module ecosystem and publish your module to npm.
+  ::
+::

package/3.guide/{4.recipes → 5.recipes}/2.vite-plugin.md

@@ -26,6 +26,10 @@ First, we need to install the Vite plugin, for our example, we'll use `@rollup/p
   bun add @rollup/plugin-yaml
   ```
 
+  ```bash [deno]
+  deno add npm:@rollup/plugin-yaml
+  ```
+
 ::
 
 Next, we need to import and add it to our [`nuxt.config.ts`](/docs/4.x/directory-structure/nuxt-config) file:

package/3.guide/{4.recipes → 5.recipes}/3.custom-usefetch.md

@@ -98,7 +98,7 @@ import type { UseFetchOptions } from 'nuxt/app'
 
 interface CustomError {
   message: string
-  statusCode: number
+  status: number
 }
 
 export function useAPI<T> (

package/3.guide/{4.recipes → 5.recipes}/4.sessions-and-authentication.md

@@ -65,7 +65,7 @@ export default defineEventHandler(async (event) => {
     return {}
   }
   throw createError({
-    statusCode: 401,
+    status: 401,
     message: 'Bad credentials',
   })
 })

package/3.guide/{5.going-further → 6.going-further}/1.experimental-features.md

@@ -248,6 +248,21 @@ export default defineNuxtConfig({
 })
 ```
 
+Payload extraction also works for routes using ISR (Incremental Static Regeneration) or SWR (Stale-While-Revalidate) caching strategies. This allows CDNs to cache payload files alongside HTML, improving client-side navigation performance for cached routes.
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    payloadExtraction: true,
+  },
+  routeRules: {
+    // Payload files will be generated for these cached routes
+    '/products/**': { isr: 3600 },
+    '/blog/**': { swr: true },
+  },
+})
+```
+
 ## clientFallback
 
 Enables the experimental [`<NuxtClientFallback>`](/docs/4.x/api/components/nuxt-client-fallback) component for rendering content on the client if there's an error in SSR.

package/3.guide/{5.going-further → 6.going-further}/1.internals.md

@@ -16,7 +16,7 @@ allowing different components to communicate with each other. You can think of i
 This context is globally available to be used with [Nuxt Kit](/docs/4.x/guide/going-further/kit) composables.
 Therefore only one instance of Nuxt is allowed to run per process.
 
-To extend the Nuxt interface and hook into different stages of the build process, we can use [Nuxt Modules](/docs/4.x/guide/going-further/modules).
+To extend the Nuxt interface and hook into different stages of the build process, we can use [Nuxt modules](/docs/4.x/guide/modules).
 
 For more details, check out [the source code](https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/core/nuxt.ts).
 
@@ -77,6 +77,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/directory-structure/app/plugins) can be used to extend runtime.
+`nuxt.config` and [Nuxt modules](/docs/4.x/guide/modules) can be used to extend the build context, and [Nuxt Plugins](/docs/4.x/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).
+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/modules).

package/3.guide/{5.going-further → 6.going-further}/10.runtime-config.md

@@ -41,7 +41,7 @@ Instead of passing non-serializable objects or functions into your application f
 
 ### Environment Variables
 
-The most common way to provide configuration is by using [Environment Variables](https://medium.com/chingu/an-introduction-to-environment-variables-and-how-to-use-them-f602f66d15fa).
+The most common way to provide configuration is by using environment variables.
 
 ::note
 The Nuxt CLI has built-in support for reading your `.env` file in development, build and generate. But when you run your built server, **your `.env` file will not be read**.

package/3.guide/{5.going-further → 6.going-further}/2.hooks.md

@@ -9,7 +9,7 @@ The hooking system is powered by [unjs/hookable](https://github.com/unjs/hookabl
 
 ## Nuxt Hooks (Build Time)
 
-These hooks are available for [Nuxt Modules](/docs/4.x/guide/going-further/modules) and build context.
+These hooks are available for [Nuxt modules](/docs/4.x/guide/modules) and build context.
 
 ### Within `nuxt.config.ts`
 

package/3.guide/{5.going-further → 6.going-further}/4.kit.md

@@ -3,7 +3,7 @@ title: "Nuxt Kit"
 description: "@nuxt/kit provides features for module authors."
 ---
 
-Nuxt Kit provides composable utilities to make interacting with [Nuxt Hooks](/docs/4.x/api/advanced/hooks), the [Nuxt Interface](/docs/4.x/guide/going-further/internals#the-nuxt-interface) and developing [Nuxt Modules](/docs/4.x/guide/going-further/modules) super easy.
+Nuxt Kit provides composable utilities to make interacting with [Nuxt Hooks](/docs/4.x/api/advanced/hooks), the [Nuxt Interface](/docs/4.x/guide/going-further/internals#the-nuxt-interface) and developing [Nuxt modules](/docs/4.x/guide/modules) super easy.
 
 ::read-more{to="/docs/4.x/api/kit"}
 Discover all Nuxt Kit utilities.

package/3.guide/{5.going-further → 6.going-further}/7.layers.md

@@ -249,6 +249,32 @@ export default defineNuxtConfig({
 })
 ```
 
+## Disabling Modules from Layers
+
+When extending a layer, you might want to disable certain modules that it includes. You can do this by setting the module's config key to `false` in your Nuxt config.
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  extends: ['./base-layer'],
+  // Disable modules from the layer by setting their config key to false
+  image: false, // Disables @nuxt/image
+  pinia: false, // Disables @pinia/nuxt
+})
+```
+
+::note
+The config key is defined by each module. Common examples include `image` for `@nuxt/image`, `pinia` for `@pinia/nuxt`, and `content` for `@nuxt/content`. Check the module's documentation for its specific config key.
+::
+
+This is useful when:
+- A layer includes modules you don't need in your project
+- You want to use a different implementation than what the layer provides
+- You need to disable analytics or other modules in specific environments
+
+::tip
+You can also use this approach to disable modules in your own project - not just those from layers. Setting a module's config key to `false` will prevent its setup function from running while still generating types for the module.
+::
+
 ## Multi-Layer Support for Nuxt Modules
 
 You can use the [`getLayerDirectories`](/docs/4.x/api/kit/layers#getlayerdirectories) utility from Nuxt Kit to support custom multi-layer handling for your modules.

package/4.api/1.components/1.nuxt-client-fallback.md

@@ -54,6 +54,10 @@ This component is experimental and in order to use it you must enable the `exper
   - **type**: `boolean`
   - **default**: `false`
 
+::warning{icon="i-ph-warning-duotone"}
+The `placeholder` and `fallback` props render content as raw HTML. Do not pass untrusted user input to these props as it may lead to XSS vulnerabilities. Use the `#fallback` or `#placeholder` slots instead for dynamic content that needs proper escaping.
+::
+
 ```vue
 <template>
   <!-- render <span>Hello world</span> server-side if the default slot fails to render -->

package/4.api/1.components/3.nuxt-layout.md

@@ -22,8 +22,8 @@ You can use `<NuxtLayout />` component to activate the `default` layout on `app.
 
 ## Props
 
-- `name`: Specify a layout name to be rendered, can be a string, reactive reference or a computed property. It **must** match the name of the corresponding layout file in the [`app/layouts/`](/docs/4.x/directory-structure/app/layouts) directory.
-  - **type**: `string`
+- `name`: Specify a layout name to be rendered, can be a string, reactive reference or a computed property. It **must** match the name of the corresponding layout file in the [`app/layouts/`](/docs/4.x/directory-structure/app/layouts) directory, or `false` to disable the layout.
+  - **type**: `string | false`
   - **default**: `default`
 
 ```vue [app/pages/index.vue]

package/4.api/1.components/8.nuxt-island.md

@@ -32,13 +32,20 @@ Server only components use `<NuxtIsland>` under the hood
   - **type**: `Record<string, any>`
 - `source`: Remote source to call the island to render.
   - **type**: `string`
-- **dangerouslyLoadClientComponents**: Required to load components from a remote source.
+- **dangerouslyLoadClientComponents**: Required to load client components from a remote source.
   - **type**: `boolean`
   - **default**: `false`
 
 ::note
 Remote islands need `experimental.componentIslands` to be `'local+remote'` in your `nuxt.config`.
-It is strongly discouraged to enable `dangerouslyLoadClientComponents` as you can't trust a remote server's javascript.
+::
+
+::warning{icon="i-ph-warning-duotone"}
+Using the `source` prop to render content from a remote server is inherently dangerous. When you specify a remote `source`, you are fully trusting that server to provide safe HTML content that will be rendered directly in your application.
+
+This is similar to using `v-html` with external content - the remote server can inject any HTML, including potentially malicious content. **Only use `source` with servers you fully trust and control.**
+
+The `dangerouslyLoadClientComponents` prop controls an additional layer of risk: whether to also download and execute client components from the remote source. Even with `dangerouslyLoadClientComponents` disabled (the default), you are still trusting the remote server's HTML output.
 ::
 
 ::note

package/4.api/2.composables/use-async-data.md

@@ -25,8 +25,8 @@ const { data, status, pending, error, refresh, clear } = await useAsyncData(
 </script>
 ```
 
-::warning
-If you're using a custom useAsyncData wrapper, do not await it in the composable, as that can cause unexpected behavior. Please follow [this recipe](/docs/4.x/guide/recipes/custom-usefetch#custom-usefetchuseasyncdata) for more information on how to make a custom async data fetcher.
+::warning{to="/docs/4.x/guide/recipes/custom-usefetch#custom-usefetchuseasyncdata"}
+If you're using a custom `useAsyncData` wrapper, do not await it in the composable as that can cause unexpected behavior. See recipe for custom async data fetcher.
 ::
 
 ::note
@@ -148,7 +148,7 @@ The `handler` function should be **side-effect free** to ensure predictable beha
   - `immediate`: when set to `false`, will prevent the request from firing immediately. (defaults to `true`)
   - `default`: a factory function to set the default value of the `data`, before the async function resolves - useful with the `lazy: true` or `immediate: false` option
   - `transform`: a function that can be used to alter `handler` function result after resolving
-  - `getCachedData`: Provide a function which returns cached data. A `null` or `undefined` return value will trigger a fetch. By default, this is:
+  - `getCachedData`: Provide a function which returns cached data. An `undefined` return value will trigger a fetch. By default, this is:
     ```ts
     const getDefaultCachedData = (key, nuxtApp, ctx) => nuxtApp.isHydrating
       ? nuxtApp.payload.data[key]

package/4.api/2.composables/use-error.md

@@ -22,8 +22,8 @@ You can use this composable in your components, pages, or plugins to access or r
 
 ```ts
 interface NuxtError<DataT = unknown> {
-  statusCode: number
-  statusMessage: string
+  status: number
+  statusText: string
   message: string
   data?: DataT
   error?: true

package/4.api/2.composables/use-fetch.md

@@ -25,8 +25,8 @@ const { data, status, error, refresh, clear } = await useFetch('/api/modules', {
 </script>
 ```
 
-::warning
-If you're using a custom useFetch wrapper, do not await it in the composable, as that can cause unexpected behavior. Please follow [this recipe](/docs/4.x/guide/recipes/custom-usefetch#custom-usefetchuseasyncdata) for more information on how to make a custom async data fetcher.
+::warning{to="/docs/4.x/guide/recipes/custom-usefetch#custom-usefetchuseasyncdata"}
+If you're using a custom `useFetch` wrapper, do not await it in the composable as that can cause unexpected behavior. See recipe for custom async data fetcher.
 ::
 
 ::note

package/4.api/2.composables/use-head.md

@@ -38,7 +38,7 @@ The properties of `useHead` can be dynamic, accepting `ref`, `computed` and `rea
 ## Type
 
 ```ts [Signature]
-export function useHead (meta: MaybeComputedRef<MetaObject>): void
+export function useHead (meta: MaybeComputedRef<MetaObject>): ActiveHeadEntry<UseHeadInput>
 
 interface MetaObject {
   title?: string
@@ -52,6 +52,21 @@ interface MetaObject {
   htmlAttrs?: HtmlAttributes
   bodyAttrs?: BodyAttributes
 }
+
+interface ActiveHeadEntry<Input> {
+  /**
+   * Updates the entry with new input.
+   *
+   * Will first clear any side effects for previous input.
+   */
+  patch: (input: Input) => void
+  /**
+   * Dispose the entry, removing it from the active head.
+   *
+   * Will queue side effects for removal.
+   */
+  dispose: () => void
+}
 ```
 
 See [@unhead/schema](https://github.com/unjs/unhead/blob/main/packages/vue/src/types/schema.ts) for more detailed types.

package/4.api/2.composables/use-nuxt-app.md

@@ -136,6 +136,8 @@ Nuxt exposes the following properties through `ssrContext`:
 
   It is also possible to use more advanced types, such as `ref`, `reactive`, `shallowRef`, `shallowReactive` and `NuxtError`.
 
+#### Custom Reducer/Reviver
+
   Since [Nuxt v3.4](https://nuxt.com/blog/v3-4#payload-enhancements), it is possible to define your own reducer/reviver for types that are not supported by Nuxt.
 
   :video-accordion{title="Watch a video from Alexander Lichter about serializing payloads, especially with regards to classes" videoId="8w6ffRBs8a4"}

package/4.api/2.composables/use-state.md

@@ -46,3 +46,13 @@ export function useState<T> (key: string, init?: () => T | Ref<T>): Ref<T>
 - `key`: A unique key ensuring that data fetching is properly de-duplicated across requests. If you do not provide a key, then a key that is unique to the file and line number of the instance of [`useState`](/docs/4.x/api/composables/use-state) will be generated for you.
 - `init`: A function that provides initial value for the state when not initiated. This function can also return a `Ref`.
 - `T`: (typescript only) Specify the type of state
+
+## Troubleshooting
+
+### `Cannot stringify arbitrary non-POJOs`
+
+This error occurs when you try to store a non-serializable payload with `useState`, such as class instances.
+
+If you want to store class instances with `useState` that are not supported by Nuxt, you can use [`definePayloadPlugin`](/docs/4.x/api/composables/use-nuxt-app#custom-reducerreviver) to add a custom serializer and deserializer for your classes.
+
+:read-more{to="/docs/4.x/api/composables/use-nuxt-app#payload"}

package/4.api/3.utils/create-error.md

@@ -12,9 +12,9 @@ You can use this function to create an error object with additional metadata. It
 
 ## Parameters
 
-- `err`: `string | { cause, data, message, name, stack, statusCode, statusMessage, fatal }`
+- `err`: `string | { cause, data, message, name, stack, status, statusText, fatal }`
 
-You can pass either a string or an object to the `createError` function. If you pass a string, it will be used as the error `message`, and the `statusCode` will default to `500`. If you pass an object, you can set multiple properties of the error, such as `statusCode`, `message`, and other error properties.
+You can pass either a string or an object to the `createError` function. If you pass a string, it will be used as the error `message`, and the `status` will default to `500`. If you pass an object, you can set multiple properties of the error, such as `status`, `message`, and other error properties.
 
 ## In Vue App
 
@@ -30,7 +30,7 @@ If you throw an error created with `createError`:
 const route = useRoute()
 const { data } = await useFetch(`/api/movies/${route.params.slug}`)
 if (!data.value) {
-  throw createError({ statusCode: 404, statusMessage: 'Page Not Found' })
+  throw createError({ status: 404, statusText: 'Page Not Found' })
 }
 </script>
 ```
@@ -44,12 +44,12 @@ Use `createError` to trigger error handling in server API routes.
 ```ts [server/api/error.ts]
 export default eventHandler(() => {
   throw createError({
-    statusCode: 404,
-    statusMessage: 'Page Not Found',
+    status: 404,
+    statusText: 'Page Not Found',
   })
 })
 ```
 
-In API routes, using `createError` by passing an object with a short `statusMessage` is recommended because it can be accessed on the client side. Otherwise, a `message` passed to `createError` on an API route will not propagate to the client. Alternatively, you can use the `data` property to pass data back to the client. In any case, always consider avoiding to put dynamic user input to the message to avoid potential security issues.
+In API routes, using `createError` by passing an object with a short `statusText` is recommended because it can be accessed on the client side. Otherwise, a `message` passed to `createError` on an API route will not propagate to the client. Alternatively, you can use the `data` property to pass data back to the client. In any case, always consider avoiding to put dynamic user input to the message to avoid potential security issues.
 
 :read-more{to="/docs/4.x/getting-started/error-handling"}

package/4.api/3.utils/define-nuxt-route-middleware.md

@@ -39,7 +39,7 @@ You can use route middleware to throw errors and show helpful error messages:
 ```ts [app/middleware/error.ts]
 export default defineNuxtRouteMiddleware((to) => {
   if (to.params.id === '1') {
-    throw createError({ statusCode: 404, statusMessage: 'Page Not Found' })
+    throw createError({ status: 404, statusText: 'Page Not Found' })
   }
 })
 ```

package/4.api/3.utils/define-page-meta.md

@@ -32,6 +32,7 @@ interface PageMeta {
   path?: string
   props?: RouteRecordRaw['props']
   alias?: string | string[]
+  groups?: string[]
   pageTransition?: boolean | TransitionProps
   layoutTransition?: boolean | TransitionProps
   viewTransition?: boolean | 'always'
@@ -76,6 +77,12 @@ interface PageMeta {
 
     Aliases for the record. Allows defining extra paths that will behave like a copy of the record. Allows having paths shorthands like `/users/:id` and `/u/:id`. All `alias` and `path` values must share the same params.
 
+  **`groups`**
+
+  - **Type**: `string[]`
+
+    Route groups the page belongs to, based on the folder structure. Automatically populated for pages within [route groups](/docs/4.x/guide/directory-structure/app/pages#route-groups).
+
   **`keepalive`**
 
   - **Type**: `boolean` | [`KeepAliveProps`](https://vuejs.org/api/built-in-components#keepalive)
@@ -130,7 +137,7 @@ interface PageMeta {
 
   - **Type**: `(route: RouteLocationNormalized) => boolean | Promise<boolean> | Partial<NuxtError> | Promise<Partial<NuxtError>>`
 
-    Validate whether a given route can validly be rendered with this page. Return true if it is valid, or false if not. If another match can't be found, this will mean a 404. You can also directly return an object with `statusCode`/`statusMessage` to respond immediately with an error (other matches will not be checked).
+    Validate whether a given route can validly be rendered with this page. Return true if it is valid, or false if not. If another match can't be found, this will mean a 404. You can also directly return an object with `status`/`statusText` to respond immediately with an error (other matches will not be checked).
 
   **`scrollToTop`**
 

package/4.api/3.utils/set-page-layout.md

@@ -19,6 +19,42 @@ export default defineNuxtRouteMiddleware((to) => {
 })
 ```
 
+## Passing Props to Layouts
+
+You can pass props to the layout by providing an object as the second argument:
+
+```ts [app/middleware/admin-layout.ts]
+export default defineNuxtRouteMiddleware((to) => {
+  setPageLayout('admin', {
+    sidebar: true,
+    title: 'Dashboard',
+  })
+})
+```
+
+The layout can then receive these props:
+
+```vue [app/layouts/admin.vue]
+<script setup lang="ts">
+const props = defineProps<{
+  sidebar?: boolean
+  title?: string
+}>()
+</script>
+
+<template>
+  <div>
+    <aside v-if="sidebar">
+      Sidebar
+    </aside>
+    <main>
+      <h1>{{ title }}</h1>
+      <slot />
+    </main>
+  </div>
+</template>
+```
+
 ::note
 If you choose to set the layout dynamically on the server side, you _must_ do so before the layout is rendered by Vue (that is, within a plugin or route middleware) to avoid a hydration mismatch.
 ::

package/4.api/3.utils/set-response-status.md

@@ -1,6 +1,6 @@
 ---
 title: 'setResponseStatus'
-description: setResponseStatus sets the statusCode (and optionally the statusMessage) of the response.
+description: setResponseStatus sets the status (and optionally the statusText) of the response.
 links:
   - label: Source
     icon: i-simple-icons-github
@@ -10,7 +10,7 @@ links:
 
 Nuxt provides composables and utilities for first-class server-side-rendering support.
 
-`setResponseStatus` sets the statusCode (and optionally the statusMessage) of the response.
+`setResponseStatus` sets the status (and optionally the statusText) of the response.
 
 ::important
 `setResponseStatus` can only be called in the [Nuxt context](/docs/4.x/guide/going-further/nuxt-app#the-nuxt-context).

package/4.api/3.utils/show-error.md

@@ -12,13 +12,13 @@ Within the [Nuxt context](/docs/4.x/guide/going-further/nuxt-app#the-nuxt-contex
 
 **Parameters:**
 
-- `error`: `string | Error | Partial<{ cause, data, message, name, stack, statusCode, statusMessage }>`
+- `error`: `string | Error | Partial<{ cause, data, message, name, stack, status, statusText }>`
 
 ```ts
 showError('😱 Oh no, an error has been thrown.')
 showError({
-  statusCode: 404,
-  statusMessage: 'Page Not Found',
+  status: 404,
+  statusText: 'Page Not Found',
 })
 ```
 

package/4.api/4.commands/add.md

@@ -23,7 +23,7 @@ npx nuxt add <TEMPLATE> <NAME> [--cwd=<directory>] [--logLevel=<silent|info|verb
 | `NAME`     | Specify name of the generated file                                                                                                                                                                               |
 <!--/add-args-->
 
-### Options
+## Options
 
 <!--add-opts-->
 | Option                               | Default | Description                              |