@nuxt/docs 4.1.2 → 4.2.0

package/3.api/3.utils/refresh-nuxt-data.md

@@ -8,7 +8,7 @@ links:
     size: xs
 ---
 
-`refreshNuxtData` is used to refetch all or specific `asyncData` instances, including those from [`useAsyncData`](/docs/api/composables/use-async-data), [`useLazyAsyncData`](/docs/api/composables/use-lazy-async-data), [`useFetch`](/docs/api/composables/use-fetch), and [`useLazyFetch`](/docs/api/composables/use-lazy-fetch).  
+`refreshNuxtData` is used to refetch all or specific `asyncData` instances, including those from [`useAsyncData`](/docs/4.x/api/composables/use-async-data), [`useLazyAsyncData`](/docs/4.x/api/composables/use-lazy-async-data), [`useFetch`](/docs/4.x/api/composables/use-fetch), and [`useLazyFetch`](/docs/4.x/api/composables/use-lazy-fetch).  
 
 ::note
 If your component is cached by `<KeepAlive>` and enters a deactivated state, the `asyncData` inside the component will still be refetched until the component is unmounted.
@@ -16,13 +16,13 @@ If your component is cached by `<KeepAlive>` and enters a deactivated state, the
 
 ## Type
 
-```ts
-refreshNuxtData(keys?: string | string[])
+```ts [Signature]
+export function refreshNuxtData (keys?: string | string[])
 ```
 
 ## Parameters
 
-* `keys`: A single string or an array of strings as `keys` that are used to fetch the data. This parameter is **optional**. All [`useAsyncData`](/docs/api/composables/use-async-data) and [`useFetch`](/docs/api/composables/use-fetch) keys are re-fetched when no `keys` are explicitly specified.
+* `keys`: A single string or an array of strings as `keys` that are used to fetch the data. This parameter is **optional**. All [`useAsyncData`](/docs/4.x/api/composables/use-async-data) and [`useFetch`](/docs/4.x/api/composables/use-fetch) keys are re-fetched when no `keys` are explicitly specified.
 
 ## Return Values
 
@@ -50,7 +50,10 @@ async function refreshAll () {
 
 <template>
   <div>
-    <button :disabled="refreshing" @click="refreshAll">
+    <button
+      :disabled="refreshing"
+      @click="refreshAll"
+    >
       Refetch All Data
     </button>
   </div>
@@ -80,7 +83,9 @@ async function refresh () {
   <div v-if="refreshing">
     Loading
   </div>
-  <button @click="refresh">Refresh</button>
+  <button @click="refresh">
+    Refresh
+  </button>
 </template>
 ```
 
@@ -88,4 +93,4 @@ async function refresh () {
 If you have access to the `asyncData` instance, it is recommended to use its `refresh` or `execute` method as the preferred way to refetch the data.
 ::
 
-:read-more{to="/docs/getting-started/data-fetching"}
+:read-more{to="/docs/4.x/getting-started/data-fetching"}

package/3.api/3.utils/reload-nuxt-app.md

@@ -14,14 +14,14 @@ links:
 
 By default, it will also save the current `state` of your app (that is, any state you could access with `useState`).
 
-::read-more{to="/docs/guide/going-further/experimental-features#restorestate" icon="i-lucide-star"}
+::read-more{to="/docs/4.x/guide/going-further/experimental-features#restorestate" icon="i-lucide-star"}
 You can enable experimental restoration of this state by enabling the `experimental.restoreState` option in your `nuxt.config` file.
 ::
 
 ## Type
 
-```ts
-reloadNuxtApp(options?: ReloadNuxtAppOptions)
+```ts [Signature]
+export function reloadNuxtApp (options?: ReloadNuxtAppOptions)
 
 interface ReloadNuxtAppOptions {
   ttl?: number

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

@@ -9,7 +9,7 @@ links:
 ---
 
 ::important
-`setPageLayout` allows you to dynamically change the layout of a page. It relies on access to the Nuxt context and therefore can only be called within the [Nuxt context](/docs/guide/going-further/nuxt-app#the-nuxt-context).
+`setPageLayout` allows you to dynamically change the layout of a page. It relies on access to the Nuxt context and therefore can only be called within the [Nuxt context](/docs/4.x/guide/going-further/nuxt-app#the-nuxt-context).
 ::
 
 ```ts [app/middleware/custom-layout.ts]

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

@@ -13,10 +13,10 @@ Nuxt provides composables and utilities for first-class server-side-rendering su
 `setResponseStatus` sets the statusCode (and optionally the statusMessage) of the response.
 
 ::important
-`setResponseStatus` can only be called in the [Nuxt context](/docs/guide/going-further/nuxt-app#the-nuxt-context).
+`setResponseStatus` can only be called in the [Nuxt context](/docs/4.x/guide/going-further/nuxt-app#the-nuxt-context).
 ::
 
-```js
+```ts
 const event = useRequestEvent()
 
 // event will be undefined in the browser
@@ -33,4 +33,4 @@ if (event) {
 In the browser, `setResponseStatus` will have no effect.
 ::
 
-:read-more{to="/docs/getting-started/error-handling"}
+:read-more{to="/docs/4.x/getting-started/error-handling"}

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

@@ -8,24 +8,24 @@ links:
     size: xs
 ---
 
-Within the [Nuxt context](/docs/guide/going-further/nuxt-app#the-nuxt-context) you can use `showError` to show an error.
+Within the [Nuxt context](/docs/4.x/guide/going-further/nuxt-app#the-nuxt-context) you can use `showError` to show an error.
 
 **Parameters:**
 
 - `error`: `string | Error | Partial<{ cause, data, message, name, stack, statusCode, statusMessage }>`
 
 ```ts
-showError("😱 Oh no, an error has been thrown.")
+showError('😱 Oh no, an error has been thrown.')
 showError({
   statusCode: 404,
-  statusMessage: "Page Not Found"
+  statusMessage: 'Page Not Found',
 })
 ```
 
-The error is set in the state using [`useError()`](/docs/api/composables/use-error) to create a reactive and SSR-friendly shared error state across components.
+The error is set in the state using [`useError()`](/docs/4.x/api/composables/use-error) to create a reactive and SSR-friendly shared error state across components.
 
 ::tip
 `showError` calls the `app:error` hook.
 ::
 
-:read-more{to="/docs/getting-started/error-handling"}
+:read-more{to="/docs/4.x/getting-started/error-handling"}

package/3.api/3.utils/update-app-config.md

@@ -9,19 +9,20 @@ links:
 ---
 
 ::note
-Updates the [`app.config`](/docs/guide/directory-structure/app-config) using deep assignment. Existing (nested) properties will be preserved.
+Updates the [`app.config`](/docs/4.x/guide/directory-structure/app-config) using deep assignment. Existing (nested) properties will be preserved.
 ::
 
 ## Usage
 
 ```js
+import { updateAppConfig, useAppConfig } from '#imports'
+
 const appConfig = useAppConfig() // { foo: 'bar' }
 
 const newAppConfig = { foo: 'baz' }
-
 updateAppConfig(newAppConfig)
 
 console.log(appConfig) // { foo: 'baz' }
 ```
 
-:read-more{to="/docs/guide/directory-structure/app-config"}
+:read-more{to="/docs/4.x/guide/directory-structure/app-config"}

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

@@ -19,7 +19,7 @@ npx nuxt add <TEMPLATE> <NAME> [--cwd=<directory>] [--logLevel=<silent|info|verb
 <!--add-args-->
 Argument | Description
 --- | ---
-`TEMPLATE` | Specify which template to generate (options: <api\|plugin\|component\|composable\|middleware\|layout\|page\|layer>)
+`TEMPLATE` | Specify which template to generate (options: <api\|app\|app-config\|component\|composable\|error\|layer\|layout\|middleware\|module\|page\|plugin\|server-middleware\|server-plugin\|server-route\|server-util>)
 `NAME` | Specify name of the generated file
 <!--/add-args-->
 

package/3.api/4.commands/analyze.md

@@ -10,7 +10,7 @@ links:
 
 <!--analyze-cmd-->
 ```bash [Terminal]
-npx nuxt analyze [ROOTDIR] [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [--dotenv] [--name=<name>] [--no-serve]
+npx nuxt analyze [ROOTDIR] [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [--dotenv] [-e, --extends=<layer-name>] [--name=<name>] [--no-serve]
 ```
 <!--/analyze-cmd-->
 
@@ -32,6 +32,7 @@ Option | Default | Description
 `--cwd=<directory>` |  | Specify the working directory, this takes precedence over ROOTDIR (default: `.`)
 `--logLevel=<silent\|info\|verbose>` |  | Specify build-time log level
 `--dotenv` |  | Path to `.env` file to load, relative to the root directory
+`-e, --extends=<layer-name>` |  | Extend from a Nuxt layer
 `--name=<name>` | `default` | Name of the analysis
 `--no-serve` |  | Skip serving the analysis results
 <!--/analyze-opts-->

package/3.api/4.commands/build.md

@@ -10,7 +10,7 @@ links:
 
 <!--build-cmd-->
 ```bash [Terminal]
-npx nuxt build [ROOTDIR] [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [--prerender] [--preset] [--dotenv] [--envName]
+npx nuxt build [ROOTDIR] [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [--prerender] [--preset] [--dotenv] [--envName] [-e, --extends=<layer-name>]
 ```
 <!--/build-cmd-->
 
@@ -35,6 +35,7 @@ Option | Default | Description
 `--preset` |  | Nitro server preset
 `--dotenv` |  | Path to `.env` file to load, relative to the root directory
 `--envName` |  | The environment to use when resolving configuration overrides (default is `production` when building, and `development` when running the dev server)
+`-e, --extends=<layer-name>` |  | Extend from a Nuxt layer
 <!--/build-opts-->
 
 ::note

package/3.api/4.commands/dev.md

@@ -10,7 +10,7 @@ links:
 
 <!--dev-cmd-->
 ```bash [Terminal]
-npx nuxt dev [ROOTDIR] [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [--dotenv] [--envName] [--no-clear] [--no-fork] [-p, --port] [-h, --host] [--clipboard] [-o, --open] [--https] [--publicURL] [--qr] [--public] [--tunnel] [--sslCert] [--sslKey]
+npx nuxt dev [ROOTDIR] [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [--dotenv] [--envName] [-e, --extends=<layer-name>] [--clear] [--no-f, --no-fork] [-p, --port] [-h, --host] [--clipboard] [-o, --open] [--https] [--publicURL] [--qr] [--public] [--tunnel] [--sslCert] [--sslKey]
 ```
 <!--/dev-cmd-->
 
@@ -33,10 +33,11 @@ Option | Default | Description
 `--logLevel=<silent\|info\|verbose>` |  | Specify build-time log level
 `--dotenv` |  | Path to `.env` file to load, relative to the root directory
 `--envName` |  | The environment to use when resolving configuration overrides (default is `production` when building, and `development` when running the dev server)
-`--no-clear` |  | Disable clear console on restart
-`--no-fork` |  | Disable forked mode
+`-e, --extends=<layer-name>` |  | Extend from a Nuxt layer
+`--clear` | `false` | Clear console on restart
+`--no-f, --no-fork` |  | Disable forked mode
 `-p, --port` |  | Port to listen on (default: `NUXT_PORT \|\| NITRO_PORT \|\| PORT \|\| nuxtOptions.devServer.port`)
-`-h, --host` |  | Host to listen on (default: `NUXT_HOST \|\| NITRO_HOST \|\| HOST \|\| nuxtOptions._layers?.[0]?.devServer?.host`)
+`-h, --host` |  | Host to listen on (default: `NUXT_HOST \|\| NITRO_HOST \|\| HOST \|\| nuxtOptions.devServer?.host`)
 `--clipboard` | `false` | Copy the URL to the clipboard
 `-o, --open` | `false` | Open the URL in the browser
 `--https` |  | Enable HTTPS

package/3.api/4.commands/generate.md

@@ -10,7 +10,7 @@ links:
 
 <!--generate-cmd-->
 ```bash [Terminal]
-npx nuxt generate [ROOTDIR] [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [--preset] [--dotenv] [--envName]
+npx nuxt generate [ROOTDIR] [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [--preset] [--dotenv] [--envName] [-e, --extends=<layer-name>]
 ```
 <!--/generate-cmd-->
 
@@ -34,8 +34,9 @@ Option | Default | Description
 `--preset` |  | Nitro server preset
 `--dotenv` |  | Path to `.env` file to load, relative to the root directory
 `--envName` |  | The environment to use when resolving configuration overrides (default is `production` when building, and `development` when running the dev server)
+`-e, --extends=<layer-name>` |  | Extend from a Nuxt layer
 <!--/generate-opts-->
 
-::read-more{to="/docs/getting-started/deployment#static-hosting"}
+::read-more{to="/docs/4.x/getting-started/deployment#static-hosting"}
 Read more about pre-rendering and static hosting.
 ::

package/3.api/4.commands/init.md

@@ -10,7 +10,7 @@ links:
 
 <!--init-cmd-->
 ```bash [Terminal]
-npm create nuxt@latest [DIR] [--cwd=<directory>] [-t, --template] [-f, --force] [--offline] [--preferOffline] [--no-install] [--gitInit] [--shell] [--packageManager] [--nightly]
+npm create nuxt@latest [DIR] [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [-t, --template] [-f, --force] [--offline] [--preferOffline] [--no-install] [--gitInit] [--shell] [--packageManager] [-M, --modules] [--no-modules] [--nightly]
 ```
 <!--/init-cmd-->
 
@@ -30,6 +30,7 @@ Argument | Description
 Option | Default | Description
 --- | --- | ---
 `--cwd=<directory>` | `.` | Specify the working directory
+`--logLevel=<silent\|info\|verbose>` |  | Specify build-time log level
 `-t, --template` |  | Template name
 `-f, --force` |  | Override existing directory
 `--offline` |  | Force offline mode
@@ -38,7 +39,7 @@ Option | Default | Description
 `--gitInit` |  | Initialize git repository
 `--shell` |  | Start shell after installation in project directory
 `--packageManager` |  | Package manager choice (npm, pnpm, yarn, bun)
-`--modules` |  | Nuxt modules to install (comma separated without spaces)
+`-M, --modules` |  | Nuxt modules to install (comma separated without spaces)
 `--no-modules` |  | Skip module installation prompt
 `--nightly` |  | Use Nuxt nightly release channel (3x or latest)
 <!--/init-opts-->

package/3.api/4.commands/module.md

@@ -21,7 +21,7 @@ npx nuxt module add <MODULENAME> [--cwd=<directory>] [--logLevel=<silent|info|ve
 <!--module-add-args-->
 Argument | Description
 --- | ---
-`MODULENAME` | Module name
+`MODULENAME` | Specify one or more modules to install by name, separated by spaces
 <!--/module-add-args-->
 
 <!--module-add-opts-->
@@ -31,7 +31,7 @@ Option | Default | Description
 `--logLevel=<silent\|info\|verbose>` |  | Specify build-time log level
 `--skipInstall` |  | Skip npm install
 `--skipConfig` |  | Skip nuxt.config.ts update
-`--dev` |  | Install module as dev dependency
+`--dev` |  | Install modules as dev dependencies
 <!--/module-add-opts-->
 
 The command lets you install [Nuxt modules](/modules) in your application with no manual work.
@@ -39,8 +39,8 @@ The command lets you install [Nuxt modules](/modules) in your application with n
 When running the command, it will:
 
 - install the module as a dependency using your package manager
-- add it to your [package.json](/docs/guide/directory-structure/package) file
-- update your [`nuxt.config`](/docs/guide/directory-structure/nuxt-config) file
+- add it to your [package.json](/docs/4.x/guide/directory-structure/package) file
+- update your [`nuxt.config`](/docs/4.x/guide/directory-structure/nuxt-config) file
 
 **Example:**
 

package/3.api/4.commands/prepare.md

@@ -10,11 +10,11 @@ links:
 
 <!--prepare-cmd-->
 ```bash [Terminal]
-npx nuxt prepare [ROOTDIR] [--dotenv] [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [--envName]
+npx nuxt prepare [ROOTDIR] [--dotenv] [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [--envName] [-e, --extends=<layer-name>]
 ```
 <!--/prepare-cmd-->
 
-The `prepare` command creates a [`.nuxt`](/docs/guide/directory-structure/nuxt) directory in your application and generates types. This can be useful in a CI environment or as a `postinstall` command in your [`package.json`](/docs/guide/directory-structure/package).
+The `prepare` command creates a [`.nuxt`](/docs/4.x/guide/directory-structure/nuxt) directory in your application and generates types. This can be useful in a CI environment or as a `postinstall` command in your [`package.json`](/docs/4.x/guide/directory-structure/package).
 
 ## Arguments
 
@@ -33,4 +33,9 @@ Option | Default | Description
 `--cwd=<directory>` |  | Specify the working directory, this takes precedence over ROOTDIR (default: `.`)
 `--logLevel=<silent\|info\|verbose>` |  | Specify build-time log level
 `--envName` |  | The environment to use when resolving configuration overrides (default is `production` when building, and `development` when running the dev server)
+`-e, --extends=<layer-name>` |  | Extend from a Nuxt layer
 <!--/prepare-opts-->
+
+::note
+This command sets `process.env.NODE_ENV` to `production`.
+::

package/3.api/4.commands/preview.md

@@ -10,11 +10,11 @@ links:
 
 <!--preview-cmd-->
 ```bash [Terminal]
-npx nuxt preview [ROOTDIR] [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [--envName] [--dotenv] [-p, --port]
+npx nuxt preview [ROOTDIR] [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [--envName] [-e, --extends=<layer-name>] [-p, --port] [--dotenv]
 ```
 <!--/preview-cmd-->
 
-The `preview` command starts a server to preview your Nuxt application after running the `build` command. The `start` command is an alias for `preview`. When running your application in production refer to the [Deployment section](/docs/getting-started/deployment).
+The `preview` command starts a server to preview your Nuxt application after running the `build` command. The `start` command is an alias for `preview`. When running your application in production refer to the [Deployment section](/docs/4.x/getting-started/deployment).
 
 ## Arguments
 
@@ -32,12 +32,13 @@ Option | Default | Description
 `--cwd=<directory>` |  | Specify the working directory, this takes precedence over ROOTDIR (default: `.`)
 `--logLevel=<silent\|info\|verbose>` |  | Specify build-time log level
 `--envName` |  | The environment to use when resolving configuration overrides (default is `production` when building, and `development` when running the dev server)
+`-e, --extends=<layer-name>` |  | Extend from a Nuxt layer
+`-p, --port` |  | Port to listen on (use `PORT` environment variable to override)
 `--dotenv` |  | Path to `.env` file to load, relative to the root directory
-`-p, --port` |  | Port to listen on (default: `NUXT_PORT \|\| NITRO_PORT \|\| PORT`)
 <!--/preview-opts-->
 
 This command sets `process.env.NODE_ENV` to `production`. To override, define `NODE_ENV` in a `.env` file or as command-line argument.
 
 ::note
-For convenience, in preview mode, your [`.env`](/docs/guide/directory-structure/env) file will be loaded into `process.env`. (However, in production you will need to ensure your environment variables are set yourself. For example, with Node.js 20+ you could do this by running `node --env-file .env .output/server/index.mjs` to start your server.)
+For convenience, in preview mode, your [`.env`](/docs/4.x/guide/directory-structure/env) file will be loaded into `process.env`. (However, in production you will need to ensure your environment variables are set yourself. For example, with Node.js 20+ you could do this by running `node --env-file .env .output/server/index.mjs` to start your server.)
 ::

package/3.api/4.commands/test.md

@@ -0,0 +1,40 @@
+---
+title: "nuxt test"
+description: The test command runs tests using @nuxt/test-utils.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/cli/blob/main/packages/nuxi/src/commands/test.ts
+    size: xs
+---
+
+<!--test-cmd-->
+```bash [Terminal]
+npx nuxt test [ROOTDIR] [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [--dev] [--watch]
+```
+<!--/test-cmd-->
+
+The `test` command runs tests using [`@nuxt/test-utils`](/docs/getting-started/testing). This command sets `process.env.NODE_ENV` to `test` if not already set.
+
+## Arguments
+
+<!--test-args-->
+Argument | Description
+--- | ---
+`ROOTDIR="."` | Specifies the working directory (default: `.`)
+<!--/test-args-->
+
+## Options
+
+<!--test-opts-->
+Option | Default | Description
+--- | --- | ---
+`--cwd=<directory>` |  | Specify the working directory, this takes precedence over ROOTDIR (default: `.`)
+`--logLevel=<silent\|info\|verbose>` |  | Specify build-time log level
+`--dev` |  | Run in dev mode
+`--watch` |  | Watch mode
+<!--/test-opts-->
+
+::note
+This command sets `process.env.NODE_ENV` to `test`.
+::

package/3.api/4.commands/typecheck.md

@@ -10,7 +10,7 @@ links:
 
 <!--typecheck-cmd-->
 ```bash [Terminal]
-npx nuxt typecheck [ROOTDIR] [--cwd=<directory>] [--logLevel=<silent|info|verbose>]
+npx nuxt typecheck [ROOTDIR] [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [--dotenv] [-e, --extends=<layer-name>]
 ```
 <!--/typecheck-cmd-->
 
@@ -31,12 +31,14 @@ Option | Default | Description
 --- | --- | ---
 `--cwd=<directory>` |  | Specify the working directory, this takes precedence over ROOTDIR (default: `.`)
 `--logLevel=<silent\|info\|verbose>` |  | Specify build-time log level
+`--dotenv` |  | Path to `.env` file to load, relative to the root directory
+`-e, --extends=<layer-name>` |  | Extend from a Nuxt layer
 <!--/typecheck-opts-->
 
 ::note
-This command sets `process.env.NODE_ENV` to `production`. To override, define `NODE_ENV` in a [`.env`](/docs/guide/directory-structure/env) file or as a command-line argument.
+This command sets `process.env.NODE_ENV` to `production`. To override, define `NODE_ENV` in a [`.env`](/docs/4.x/guide/directory-structure/env) file or as a command-line argument.
 ::
 
-::read-more{to="/docs/guide/concepts/typescript#type-checking"}
+::read-more{to="/docs/4.x/guide/concepts/typescript#type-checking"}
 Read more on how to enable type-checking at build or development time.
 ::

package/3.api/4.commands/upgrade.md

@@ -10,7 +10,7 @@ links:
 
 <!--upgrade-cmd-->
 ```bash [Terminal]
-npx nuxt upgrade [ROOTDIR] [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [--dedupe] [-f, --force] [-ch, --channel=<stable|nightly>]
+npx nuxt upgrade [ROOTDIR] [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [--dedupe] [-f, --force] [-ch, --channel=<stable|nightly|v3|v4|v4-nightly|v3-nightly>]
 ```
 <!--/upgrade-cmd-->
 
@@ -31,7 +31,7 @@ Option | Default | Description
 --- | --- | ---
 `--cwd=<directory>` |  | Specify the working directory, this takes precedence over ROOTDIR (default: `.`)
 `--logLevel=<silent\|info\|verbose>` |  | Specify build-time log level
-`--dedupe` |  | Will deduplicate dependencies but not recreate the lockfile
+`--dedupe` |  | Dedupe dependencies after upgrading
 `-f, --force` |  | Force upgrade to recreate lockfile and node_modules
-`-ch, --channel=<stable\|nightly>` | `stable` | Specify a channel to install from (default: stable)
+`-ch, --channel=<stable\|nightly\|v3\|v4\|v4-nightly\|v3-nightly>` | `stable` | Specify a channel to install from (default: stable)
 <!--/upgrade-opts-->