@nuxt/docs 0.0.0 → 3.17.1

package/3.api/3.utils/prerender-routes.md

@@ -0,0 +1,46 @@
+---
+title: 'prerenderRoutes'
+description: prerenderRoutes hints to Nitro to prerender an additional route.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/composables/ssr.ts
+    size: xs
+---
+
+When prerendering, you can hint to Nitro to prerender additional paths, even if their URLs do not show up in the HTML of the generated page.
+
+::important
+`prerenderRoutes` can only be called within the [Nuxt context](/docs/guide/going-further/nuxt-app#the-nuxt-context).
+::
+
+::note
+`prerenderRoutes` has to be executed during prerendering. If the `prerenderRoutes` is used in dynamic pages/routes which are not prerendered, then it will not be executed.
+::
+
+```js
+const route = useRoute()
+
+prerenderRoutes('/')
+prerenderRoutes(['/', '/about'])
+```
+
+::note
+In the browser, or if called outside prerendering, `prerenderRoutes` will have no effect.
+::
+
+You can even prerender API routes which is particularly useful for full statically generated sites (SSG) because you can then `$fetch` data as if you have an available server!
+
+```js
+prerenderRoutes('/api/content/article/name-of-article')
+
+// Somewhere later in App
+const articleContent = await $fetch('/api/content/article/name-of-article', {
+  responseType: 'json',
+})
+```
+
+::warning
+Prerendered API routes in production may not return the expected response headers, depending on the provider you deploy to. For example, a JSON response might be served with an `application/octet-stream` content type.
+Always manually set `responseType` when fetching prerendered API routes.
+::

package/3.api/3.utils/refresh-cookie.md

@@ -0,0 +1,46 @@
+---
+title: "refreshCookie"
+description: "Refresh useCookie values manually when a cookie has changed"
+navigation:
+  badge: New
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/composables/cookie.ts
+    size: xs
+---
+
+::important
+This utility is available since [Nuxt v3.10](/blog/v3-10).
+::
+
+## Purpose
+
+The `refreshCookie` function is designed to refresh cookie value returned by `useCookie`.
+
+This is useful for updating the `useCookie` ref when we know the new cookie value has been set in the browser.
+
+## Usage
+
+```vue [app.vue]
+<script setup lang="ts">
+const tokenCookie = useCookie('token')
+
+const login = async (username, password) => {
+  const token = await $fetch('/api/token', { ... }) // Sets `token` cookie on response
+  refreshCookie('token')
+}
+
+const loggedIn = computed(() => !!tokenCookie.value)
+</script>
+```
+
+::note{to="/docs/guide/going-further/experimental-features#cookiestore"}
+You can enable experimental `cookieStore` option to automatically refresh `useCookie` value when cookie changes in the browser.
+::
+
+## Type
+
+```ts
+refreshCookie(name: string): void
+```

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

@@ -0,0 +1,91 @@
+---
+title: 'refreshNuxtData'
+description: Refresh all or specific asyncData instances in Nuxt
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/composables/asyncData.ts
+    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).  
+
+::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.
+::
+
+## Type
+
+```ts
+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.
+
+## Return Values
+
+`refreshNuxtData` returns a promise, resolving when all or specific `asyncData` instances have been refreshed.
+
+## Examples
+
+### Refresh All Data
+
+This example below refreshes all data being fetched using `useAsyncData` and `useFetch` in Nuxt application.
+
+```vue [pages/some-page.vue]
+<script setup lang="ts">
+const refreshing = ref(false)
+
+async function refreshAll () {
+  refreshing.value = true
+  try {
+    await refreshNuxtData()
+  } finally {
+    refreshing.value = false
+  }
+}
+</script>
+
+<template>
+  <div>
+    <button :disabled="refreshing" @click="refreshAll">
+      Refetch All Data
+    </button>
+  </div>
+</template>
+```
+
+### Refresh Specific Data
+
+This example below refreshes only data where the key matches to `count` and `user`.
+
+```vue [pages/some-page.vue]
+<script setup lang="ts">
+const refreshing = ref(false)
+
+async function refresh () {
+  refreshing.value = true
+  try {
+    // you could also pass an array of keys to refresh multiple data
+    await refreshNuxtData(['count', 'user'])
+  } finally {
+    refreshing.value = false
+  }
+}
+</script>
+
+<template>
+  <div v-if="refreshing">
+    Loading
+  </div>
+  <button @click="refresh">Refresh</button>
+</template>
+```
+
+::note
+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"}

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

@@ -0,0 +1,74 @@
+---
+title: 'reloadNuxtApp'
+description: reloadNuxtApp will perform a hard reload of the page.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/composables/chunk.ts
+    size: xs
+---
+
+::note
+`reloadNuxtApp` will perform a hard reload of your app, re-requesting a page and its dependencies from the server.
+::
+
+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"}
+You can enable experimental restoration of this state by enabling the `experimental.restoreState` option in your `nuxt.config` file.
+::
+
+## Type
+
+```ts
+reloadNuxtApp(options?: ReloadNuxtAppOptions)
+
+interface ReloadNuxtAppOptions {
+  ttl?: number
+  force?: boolean
+  path?: string
+  persistState?: boolean
+}
+```
+
+### `options` (optional)
+
+**Type**: `ReloadNuxtAppOptions`
+
+An object accepting the following properties:
+
+- `path` (optional)
+
+  **Type**: `string`
+
+  **Default**: `window.location.pathname`
+
+  The path to reload (defaulting to the current path). If this is different from the current window location it
+  will trigger a navigation and add an entry in the browser history.
+
+- `ttl` (optional)
+
+  **Type**: `number`
+
+  **Default**: `10000`
+
+  The number of milliseconds in which to ignore future reload requests. If called again within this time period,
+  `reloadNuxtApp` will not reload your app to avoid reload loops.
+
+- `force` (optional)
+
+  **Type**: `boolean`
+
+  **Default**: `false`
+
+  This option allows bypassing reload loop protection entirely, forcing a reload even if one has occurred within
+  the previously specified TTL.
+
+- `persistState` (optional)
+
+  **Type**: `boolean`
+
+  **Default**: `false`
+
+  Whether to dump the current Nuxt state to sessionStorage (as `nuxt:reload:state`). By default this will have no
+  effect on reload unless `experimental.restoreState` is also set, or unless you handle restoring the state yourself.

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

@@ -0,0 +1,24 @@
+---
+title: 'setPageLayout'
+description: setPageLayout allows you to dynamically change the layout of a page.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/composables/router.ts
+    size: xs
+---
+
+::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).
+::
+
+```ts [middleware/custom-layout.ts]
+export default defineNuxtRouteMiddleware((to) => {
+  // Set the layout on the route you are navigating _to_
+  setPageLayout('other')
+})
+```
+
+::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/3.api/3.utils/set-response-status.md

@@ -0,0 +1,36 @@
+---
+title: 'setResponseStatus'
+description: setResponseStatus sets the statusCode (and optionally the statusMessage) of the response.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/composables/ssr.ts
+    size: xs
+---
+
+Nuxt provides composables and utilities for first-class server-side-rendering support.
+
+`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).
+::
+
+```js
+const event = useRequestEvent()
+
+// event will be undefined in the browser
+if (event) {
+  // Set the status code to 404 for a custom 404 page
+  setResponseStatus(event, 404)
+
+  // Set the status message as well
+  setResponseStatus(event, 404, 'Page Not Found')
+}
+```
+
+::note
+In the browser, `setResponseStatus` will have no effect.
+::
+
+:read-more{to="/docs/getting-started/error-handling"}

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

@@ -0,0 +1,31 @@
+---
+title: 'showError'
+description: Nuxt provides a quick and simple way to show a full screen error page if needed.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/composables/error.ts
+    size: xs
+---
+
+Within the [Nuxt context](/docs/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({
+  statusCode: 404,
+  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.
+
+::tip
+`showError` calls the `app:error` hook.
+::
+
+:read-more{to="/docs/getting-started/error-handling"}

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

@@ -0,0 +1,27 @@
+---
+title: 'updateAppConfig'
+description: 'Update the App Config at runtime.'
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/config.ts
+    size: xs
+---
+
+::note
+Updates the [`app.config`](/docs/guide/directory-structure/app-config) using deep assignment. Existing (nested) properties will be preserved.
+::
+
+## Usage
+
+```js
+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"}

package/3.api/4.commands/.navigation.yml

@@ -0,0 +1,3 @@
+title: 'Commands'
+titleTemplate: '%s · Nuxt Commands'
+icon: i-lucide-square-terminal

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

@@ -0,0 +1,112 @@
+---
+title: "nuxi add"
+description: "Scaffold an entity into your Nuxt application."
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/cli/blob/main/packages/nuxi/src/commands/add.ts
+    size: xs
+---
+
+<!--add-cmd-->
+```bash [Terminal]
+npx nuxi add <TEMPLATE> <NAME> [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [--force]
+```
+<!--/add-cmd-->
+
+### Arguments
+
+<!--add-args-->
+Argument | Description
+--- | ---
+`TEMPLATE` | Specify which template to generate (options: <api\|plugin\|component\|composable\|middleware\|layout\|page\|layer>)
+`NAME` | Specify name of the generated file
+<!--/add-args-->
+
+### Options
+
+<!--add-opts-->
+Option | Default | Description
+--- | --- | ---
+`--cwd=<directory>` | `.` | Specify the working directory
+`--logLevel=<silent\|info\|verbose>` |  | Specify build-time log level
+`--force` | `false` | Force override file if it already exists
+<!--/add-opts-->
+
+**Modifiers:**
+
+Some templates support additional modifier flags to add a suffix (like `.client` or `.get`) to their name.
+
+```bash [Terminal]
+# Generates `/plugins/sockets.client.ts`
+npx nuxi add plugin sockets --client
+```
+
+## `nuxi add component`
+
+* Modifier flags: `--mode client|server` or `--client` or `--server`
+
+```bash [Terminal]
+# Generates `components/TheHeader.vue`
+npx nuxi add component TheHeader
+```
+
+## `nuxi add composable`
+
+```bash [Terminal]
+# Generates `composables/foo.ts`
+npx nuxi add composable foo
+```
+
+## `nuxi add layout`
+
+```bash [Terminal]
+# Generates `layouts/custom.vue`
+npx nuxi add layout custom
+```
+
+## `nuxi add plugin`
+
+* Modifier flags: `--mode client|server` or `--client`or `--server`
+
+```bash [Terminal]
+# Generates `plugins/analytics.ts`
+npx nuxi add plugin analytics
+```
+
+## `nuxi add page`
+
+```bash [Terminal]
+# Generates `pages/about.vue`
+npx nuxi add page about
+```
+
+```bash [Terminal]
+# Generates `pages/category/[id].vue`
+npx nuxi add page "category/[id]"
+```
+
+## `nuxi add middleware`
+
+* Modifier flags: `--global`
+
+```bash [Terminal]
+# Generates `middleware/auth.ts`
+npx nuxi add middleware auth
+```
+
+## `nuxi add api`
+
+* Modifier flags: `--method` (can accept `connect`, `delete`, `get`, `head`, `options`, `patch`, `post`, `put` or `trace`) or alternatively you can directly use `--get`, `--post`, etc.
+
+```bash [Terminal]
+# Generates `server/api/hello.ts`
+npx nuxi add api hello
+```
+
+## `nuxi add layer`
+
+```bash [Terminal]
+# Generates `layers/subscribe/nuxt.config.ts`
+npx nuxi add layer subscribe
+```

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

@@ -0,0 +1,41 @@
+---
+title: "nuxi analyze"
+description: "Analyze the production bundle or your Nuxt application."
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/cli/blob/main/packages/nuxi/src/commands/analyze.ts
+    size: xs
+---
+
+<!--analyze-cmd-->
+```bash [Terminal]
+npx nuxi analyze [ROOTDIR] [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [--dotenv] [--name=<name>] [--no-serve]
+```
+<!--/analyze-cmd-->
+
+The `analyze` command builds Nuxt and analyzes the production bundle (experimental).
+
+## Arguments
+
+<!--analyze-args-->
+Argument | Description
+--- | ---
+`ROOTDIR="."` | Specifies the working directory (default: `.`)
+<!--/analyze-args-->
+
+## Options
+
+<!--analyze-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
+`--dotenv` |  | Path to `.env` file to load, relative to the root directory
+`--name=<name>` | `default` | Name of the analysis
+`--no-serve` |  | Skip serving the analysis results
+<!--/analyze-opts-->
+
+::note
+This command sets `process.env.NODE_ENV` to `production`.
+::

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

@@ -0,0 +1,42 @@
+---
+title: 'nuxi build-module'
+description: 'Nuxt command to build your Nuxt module before publishing.'
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/module-builder/blob/main/src/cli.ts
+    size: xs
+---
+
+<!--build-module-cmd-->
+```bash [Terminal]
+npx nuxi build-module [ROOTDIR] [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [--build] [--stub] [--sourcemap] [--prepare]
+```
+<!--/build-module-cmd-->
+
+The `build-module` command runs `@nuxt/module-builder` to generate `dist` directory within your `rootDir` that contains the full build for your **nuxt-module**.
+
+## Arguments
+
+<!--build-module-args-->
+Argument | Description
+--- | ---
+`ROOTDIR="."` | Specifies the working directory (default: `.`)
+<!--/build-module-args-->
+
+## Options
+
+<!--build-module-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
+`--build` | `false` | Build module for distribution
+`--stub` | `false` | Stub dist instead of actually building it for development
+`--sourcemap` | `false` | Generate sourcemaps
+`--prepare` | `false` | Prepare module for local development
+<!--/build-module-opts-->
+
+::read-more{to="https://github.com/nuxt/module-builder" icon="i-simple-icons-github" target="\_blank"}
+Read more about `@nuxt/module-builder`.
+::

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

@@ -0,0 +1,46 @@
+---
+title: "nuxi build"
+description: "Build your Nuxt application."
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/cli/blob/main/packages/nuxi/src/commands/build.ts
+    size: xs
+---
+
+<!--build-cmd-->
+```bash [Terminal]
+npx nuxi build [ROOTDIR] [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [--prerender] [--preset] [--dotenv] [--envName]
+```
+<!--/build-cmd-->
+
+The `build` command creates a `.output` directory with all your application, server and dependencies ready for production.
+
+## Arguments
+
+<!--build-args-->
+Argument | Description
+--- | ---
+`ROOTDIR="."` | Specifies the working directory (default: `.`)
+<!--/build-args-->
+
+## Options
+
+<!--build-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
+`--prerender` |  | Build Nuxt and prerender static routes
+`--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)
+<!--/build-opts-->
+
+::note
+This command sets `process.env.NODE_ENV` to `production`.
+::
+
+::note
+`--prerender` will always set the `preset` to `static`
+::

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

@@ -0,0 +1,38 @@
+---
+title: 'nuxi cleanup'
+description: 'Remove common generated Nuxt files and caches.'
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/cli/blob/main/packages/nuxi/src/commands/cleanup.ts
+    size: xs
+---
+
+<!--cleanup-cmd-->
+```bash [Terminal]
+npx nuxi cleanup [ROOTDIR] [--cwd=<directory>]
+```
+<!--/cleanup-cmd-->
+
+The `cleanup` command removes common generated Nuxt files and caches, including:
+
+- `.nuxt`
+- `.output`
+- `node_modules/.vite`
+- `node_modules/.cache`
+
+## Arguments
+
+<!--cleanup-args-->
+Argument | Description
+--- | ---
+`ROOTDIR="."` | Specifies the working directory (default: `.`)
+<!--/cleanup-args-->
+
+## Options
+
+<!--cleanup-opts-->
+Option | Default | Description
+--- | --- | ---
+`--cwd=<directory>` |  | Specify the working directory, this takes precedence over ROOTDIR (default: `.`)
+<!--/cleanup-opts-->