@nuxt/docs 0.0.0 → 3.17.1

package/1.getting-started/11.state-management.md

@@ -0,0 +1,223 @@
+---
+title: 'State Management'
+description: Nuxt provides powerful state management libraries and the useState composable to create a reactive and SSR-friendly shared state.
+navigation.icon: i-lucide-database
+---
+
+Nuxt provides the [`useState`](/docs/api/composables/use-state) composable to create a reactive and SSR-friendly shared state across components.
+
+[`useState`](/docs/api/composables/use-state) is an SSR-friendly [`ref`](https://vuejs.org/api/reactivity-core.html#ref) replacement. Its value will be preserved after server-side rendering (during client-side hydration) and shared across all components using a unique key.
+
+:video-accordion{title="Watch a video from Alexander Lichter about why and when to use useState" videoId="mv0WcBABcIk"}
+
+::important
+Because the data inside [`useState`](/docs/api/composables/use-state) will be serialized to JSON, it is important that it does not contain anything that cannot be serialized, such as classes, functions or symbols.
+::
+
+::read-more{to="/docs/api/composables/use-state"}
+Read more about `useState` composable.
+::
+
+## Best Practices
+
+::warning
+Never define `const state = ref()` outside of `<script setup>` or `setup()` function.<br>
+For example, doing `export myState = ref({})` would result in state shared across requests on the server and can lead to memory leaks.
+::
+
+::tip{icon="i-lucide-circle-check"}
+Instead use `const useX = () => useState('x')`
+::
+
+## Examples
+
+### Basic Usage
+
+In this example, we use a component-local counter state. Any other component that uses `useState('counter')` shares the same reactive state.
+
+```vue twoslash [app.vue]
+<script setup lang="ts">
+const counter = useState('counter', () => Math.round(Math.random() * 1000))
+</script>
+
+<template>
+  <div>
+    Counter: {{ counter }}
+    <button @click="counter++">
+      +
+    </button>
+    <button @click="counter--">
+      -
+    </button>
+  </div>
+</template>
+```
+
+:link-example{to="/docs/examples/features/state-management"}
+
+::note
+To globally invalidate cached state, see [`clearNuxtState`](/docs/api/utils/clear-nuxt-state) util.
+::
+
+### Initializing State
+
+Most of the time, you will want to initialize your state with data that resolves asynchronously. You can use the [`app.vue`](/docs/guide/directory-structure/app) component with the [`callOnce`](/docs/api/utils/call-once) util to do so.
+
+```vue twoslash [app.vue]
+<script setup lang="ts">
+const websiteConfig = useState('config')
+
+await callOnce(async () => {
+  websiteConfig.value = await $fetch('https://my-cms.com/api/website-config')
+})
+</script>
+```
+
+::tip
+This is similar to the [`nuxtServerInit` action](https://v2.nuxt.com/docs/directory-structure/store/#the-nuxtserverinit-action) in Nuxt 2, which allows filling the initial state of your store server-side before rendering the page.
+::
+
+:read-more{to="/docs/api/utils/call-once"}
+
+### Usage with Pinia
+
+In this example, we leverage the [Pinia module](/modules/pinia) to create a global store and use it across the app.
+
+::important
+Make sure to install the Pinia module with `npx nuxi@latest module add pinia` or follow the [module's installation steps](https://pinia.vuejs.org/ssr/nuxt.html#Installation).
+::
+
+::code-group
+```ts [stores/website.ts]
+export const useWebsiteStore = defineStore('websiteStore', {
+  state: () => ({
+    name: '',
+    description: ''
+  }),
+  actions: {
+    async fetch() {
+      const infos = await $fetch('https://api.nuxt.com/modules/pinia')
+
+      this.name = infos.name
+      this.description = infos.description
+    }
+  }
+})
+```
+```vue [app.vue]
+<script setup lang="ts">
+const website = useWebsiteStore()
+
+await callOnce(website.fetch)
+</script>
+
+<template>
+  <main>
+    <h1>{{ website.name }}</h1>
+    <p>{{ website.description }}</p>
+  </main>
+</template>
+```
+::
+
+## Advanced Usage
+
+::code-group
+```ts [composables/locale.ts]
+import type { Ref } from 'vue'
+
+export const useLocale = () => {
+  return useState<string>('locale', () => useDefaultLocale().value)
+}
+
+export const useDefaultLocale = (fallback = 'en-US') => {
+  const locale = ref(fallback)
+  if (import.meta.server) {
+    const reqLocale = useRequestHeaders()['accept-language']?.split(',')[0]
+    if (reqLocale) {
+      locale.value = reqLocale
+    }
+  } else if (import.meta.client) {
+    const navLang = navigator.language
+    if (navLang) {
+      locale.value = navLang
+    }
+  }
+  return locale
+}
+
+export const useLocales = () => {
+  const locale = useLocale()
+  const locales = ref([
+    'en-US',
+    'en-GB',
+    ...
+    'ja-JP-u-ca-japanese'
+  ])
+  if (!locales.value.includes(locale.value)) {
+    locales.value.unshift(locale.value)
+  }
+  return locales
+}
+
+export const useLocaleDate = (date: Ref<Date> | Date, locale = useLocale()) => {
+  return computed(() => new Intl.DateTimeFormat(locale.value, { dateStyle: 'full' }).format(unref(date)))
+}
+```
+
+```vue [app.vue]
+<script setup lang="ts">
+const locales = useLocales()
+const locale = useLocale()
+const date = useLocaleDate(new Date('2016-10-26'))
+</script>
+
+<template>
+  <div>
+    <h1>Nuxt birthday</h1>
+    <p>{{ date }}</p>
+    <label for="locale-chooser">Preview a different locale</label>
+    <select id="locale-chooser" v-model="locale">
+      <option v-for="locale of locales" :key="locale" :value="locale">
+        {{ locale }}
+      </option>
+    </select>
+  </div>
+</template>
+```
+::
+
+:link-example{to="/docs/examples/advanced/locale"}
+
+## Shared State
+
+By using [auto-imported composables](/docs/guide/directory-structure/composables) we can define global type-safe states and import them across the app.
+
+```ts twoslash [composables/states.ts]
+export const useColor = () => useState<string>('color', () => 'pink')
+```
+
+```vue [app.vue]
+<script setup lang="ts">
+// ---cut-start---
+const useColor = () => useState<string>('color', () => 'pink')
+// ---cut-end---
+const color = useColor() // Same as useState('color')
+</script>
+
+<template>
+  <p>Current color: {{ color }}</p>
+</template>
+```
+
+:video-accordion{title="Watch a video from Daniel Roe on how to deal with global state and SSR in Nuxt" videoId="dZSNW07sO-A"}
+
+## Using third-party libraries
+
+Nuxt **used to rely** on the Vuex library to provide global state management. If you are migrating from Nuxt 2, please head to [the migration guide](/docs/migration/configuration#vuex).
+
+Nuxt is not opinionated about state management, so feel free to choose the right solution for your needs. There are multiple integrations with the most popular state management libraries, including:
+
+- [Pinia](/modules/pinia) - the official Vue recommendation
+- [Harlem](/modules/harlem) - immutable global state management
+- [XState](/modules/xstate) - state machine approach with tools for visualizing and testing your state logic

package/1.getting-started/12.error-handling.md

@@ -0,0 +1,233 @@
+---
+title: 'Error Handling'
+description: 'Learn how to catch and handle errors in Nuxt.'
+navigation.icon: i-lucide-bug-off
+---
+
+Nuxt is a full-stack framework, which means there are several sources of unpreventable user runtime errors that can happen in different contexts:
+
+- Errors during the Vue rendering lifecycle (SSR & CSR)
+- Server and client startup errors (SSR + CSR)
+- Errors during Nitro server lifecycle ([`server/`](/docs/guide/directory-structure/server) directory)
+- Errors downloading JS chunks
+
+::tip
+**SSR** stands for **Server-Side Rendering** and **CSR** for **Client-Side Rendering**.
+::
+
+## Vue Errors
+
+You can hook into Vue errors using [`onErrorCaptured`](https://vuejs.org/api/composition-api-lifecycle.html#onerrorcaptured).
+
+In addition, Nuxt provides a [`vue:error`](/docs/api/advanced/hooks#app-hooks-runtime) hook that will be called if any errors propagate up to the top level.
+
+If you are using an error reporting framework, you can provide a global handler through [`vueApp.config.errorHandler`](https://vuejs.org/api/application.html#app-config-errorhandler). It will receive all Vue errors, even if they are handled.
+
+```ts twoslash [plugins/error-handler.ts]
+export default defineNuxtPlugin((nuxtApp) => {
+  nuxtApp.vueApp.config.errorHandler = (error, instance, info) => {
+    // handle error, e.g. report to a service
+  }
+
+  // Also possible
+  nuxtApp.hook('vue:error', (error, instance, info) => {
+    // handle error, e.g. report to a service
+  })
+})
+```
+
+::note
+Note that the `vue:error` hook is based on [`onErrorCaptured`](https://vuejs.org/api/composition-api-lifecycle.html#onerrorcaptured) lifecycle hook.
+::
+
+## Startup Errors
+
+Nuxt will call the `app:error` hook if there are any errors in starting your Nuxt application.
+
+This includes:
+- running [Nuxt plugins](/docs/guide/directory-structure/plugins)
+- processing `app:created` and `app:beforeMount` hooks
+- rendering your Vue app to HTML (during SSR)
+- mounting the app (on client-side), though you should handle this case with `onErrorCaptured` or with `vue:error`
+- processing the `app:mounted` hook
+
+## Nitro Server Errors
+
+You cannot currently define a server-side handler for these errors, but can render an error page, see the [Render an Error Page](#error-page) section.
+
+## Errors with JS Chunks
+
+You might encounter chunk loading errors due to a network connectivity failure or a new deployment (which invalidates your old, hashed JS chunk URLs). Nuxt provides built-in support for handling chunk loading errors by performing a hard reload when a chunk fails to load during route navigation.
+
+You can change this behavior by setting `experimental.emitRouteChunkError` to `false` (to disable hooking into these errors at all) or to `manual` if you want to handle them yourself. If you want to handle chunk loading errors manually, you can check out the [the automatic implementation](https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/plugins/chunk-reload.client.ts) for ideas.
+
+## Error Page
+
+::note
+When Nuxt encounters a fatal error (any unhandled error on the server, or an error created with `fatal: true` on the client) it will either render a JSON response (if requested with `Accept: application/json` header) or trigger a full-screen error page.
+::
+
+An error may occur during the server lifecycle when:
+- processing your Nuxt plugins
+- rendering your Vue app into HTML
+- a server API route throws an error
+
+It can also occur on the client side when:
+- processing your Nuxt plugins
+- before mounting the application (`app:beforeMount` hook)
+- mounting your app if the error was not handled with `onErrorCaptured` or `vue:error` hook
+- the Vue app is initialized and mounted in browser (`app:mounted`).
+
+::read-more{to="/docs/api/advanced/hooks"}
+Discover all the Nuxt lifecycle hooks.
+::
+
+Customize the default error page by adding `~/error.vue` in the source directory of your application, alongside `app.vue`.
+
+<!-- TODO:twoslash: Twoslash does not support tsconfig paths yet -->
+
+```vue [error.vue]
+<script setup lang="ts">
+import type { NuxtError } from '#app'
+
+const props = defineProps({
+  error: Object as () => NuxtError
+})
+
+const handleError = () => clearError({ redirect: '/' })
+</script>
+
+<template>
+  <div>
+    <h2>{{ error.statusCode }}</h2>
+    <button @click="handleError">Clear errors</button>
+  </div>
+</template>
+```
+
+::read-more{to="/docs/guide/directory-structure/error"}
+Read more about `error.vue` and its uses.
+::
+
+For custom errors we highly recommend to use `onErrorCaptured` composable that can be called in a page/component setup function or `vue:error` runtime nuxt hook that can be configured in a nuxt plugin.
+
+```ts twoslash [plugins/error-handler.ts]
+export default defineNuxtPlugin(nuxtApp => {
+  nuxtApp.hook('vue:error', (err) => {
+    //
+  })
+})
+```
+
+When you are ready to remove the error page, you can call the [`clearError`](/docs/api/utils/clear-error) helper function, which takes an optional path to redirect to (for example, if you want to navigate to a 'safe' page).
+
+::important
+Make sure to check before using anything dependent on Nuxt plugins, such as `$route` or `useRouter`, as if a plugin threw an error, then it won't be re-run until you clear the error.
+::
+
+::note
+Rendering an error page is an entirely separate page load, meaning any registered middleware will run again. You can use [`useError`](#useerror) in middleware to check if an error is being handled.
+::
+
+::note
+If you are running on Node 16 and you set any cookies when rendering your error page, they will [overwrite cookies previously set](https://github.com/nuxt/nuxt/pull/20585). We recommend using a newer version of Node as Node 16 reached end-of-life in September 2023.
+::
+
+## Error Utils
+
+### `useError`
+
+```ts [TS Signature]
+function useError (): Ref<Error | { url, statusCode, statusMessage, message, description, data }>
+```
+
+This function will return the global Nuxt error that is being handled.
+
+::read-more{to="/docs/api/composables/use-error"}
+Read more about `useError` composable.
+::
+
+### `createError`
+
+```ts [TS Signature]
+function createError (err: string | { cause, data, message, name, stack, statusCode, statusMessage, fatal }): Error
+```
+
+Create an error object with additional metadata. You can pass a string to be set as the error `message` or an object containing error properties. It is usable in both the Vue and Server portions of your app, and is meant to be thrown.
+
+If you throw an error created with `createError`:
+- on server-side, it will trigger a full-screen error page which you can clear with [`clearError`](#clearerror).
+- on client-side, it will throw a non-fatal error for you to handle. If you need to trigger a full-screen error page, then you can do this by setting `fatal: true`.
+
+```vue twoslash [pages/movies/[slug\\].vue]
+<script setup lang="ts">
+const route = useRoute()
+const { data } = await useFetch(`/api/movies/${route.params.slug}`)
+
+if (!data.value) {
+  throw createError({
+    statusCode: 404,
+    statusMessage: 'Page Not Found'
+  })
+}
+</script>
+```
+
+::read-more{to="/docs/api/utils/create-error"}
+Read more about `createError` util.
+::
+
+### `showError`
+
+```ts [TS Signature]
+function showError (err: string | Error | { statusCode, statusMessage }): Error
+```
+
+You can call this function at any point on client-side, or (on server side) directly within middleware, plugins or `setup()` functions. It will trigger a full-screen error page which you can clear with [`clearError`](#clearerror).
+
+It is recommended instead to use `throw createError()`.
+
+::read-more{to="/docs/api/utils/show-error"}
+Read more about `showError` util.
+::
+
+### `clearError`
+
+```ts [TS Signature]
+function clearError (options?: { redirect?: string }): Promise<void>
+```
+
+This function will clear the currently handled Nuxt error. It also takes an optional path to redirect to (for example, if you want to navigate to a 'safe' page).
+
+::read-more{to="/docs/api/utils/clear-error"}
+Read more about `clearError` util.
+::
+
+## Render Error in Component
+
+Nuxt also provides a [`<NuxtErrorBoundary>`](/docs/api/components/nuxt-error-boundary) component that allows you to handle client-side errors within your app, without replacing your entire site with an error page.
+
+This component is responsible for handling errors that occur within its default slot. On client-side, it will prevent the error from bubbling up to the top level, and will render the `#error` slot instead.
+
+The `#error` slot will receive `error` as a prop. (If you set `error = null` it will trigger re-rendering the default slot; you'll need to ensure that the error is fully resolved first or the error slot will just be rendered a second time.)
+
+::tip
+If you navigate to another route, the error will be cleared automatically.
+::
+
+```vue [pages/index.vue]
+<template>
+  <!-- some content -->
+  <NuxtErrorBoundary @error="someErrorLogger">
+    <!-- You use the default slot to render your content -->
+    <template #error="{ error, clearError }">
+      You can display the error locally here: {{ error }}
+      <button @click="clearError">
+        This will clear the error.
+      </button>
+    </template>
+  </NuxtErrorBoundary>
+</template>
+```
+
+:link-example{to="/docs/examples/advanced/error-handling"}

package/1.getting-started/13.server.md

@@ -0,0 +1,94 @@
+---
+title: 'Server'
+description: Build full-stack applications with Nuxt's server framework. You can fetch data from your database or another server, create APIs, or even generate static server-side content like a sitemap or a RSS feed - all from a single codebase.
+navigation.icon: i-lucide-pc-case
+---
+
+:read-more{to="/docs/guide/directory-structure/server"}
+
+## Powered by Nitro
+
+![Server engine](/assets/docs/getting-started/server.svg)
+
+Nuxt's server is [Nitro](https://github.com/nitrojs/nitro). It was originally created for Nuxt but is now part of [UnJS](https://unjs.io) and open for other frameworks - and can even be used on its own.
+
+Using Nitro gives Nuxt superpowers:
+
+- Full control of the server-side part of your app
+- Universal deployment on any provider (many zero-config)
+- Hybrid rendering
+
+Nitro is internally using [h3](https://github.com/unjs/h3), a minimal H(TTP) framework built for high performance and portability.
+
+:video-accordion{title="Watch a video from Alexander Lichter to understand the responsibilities of Nuxt and Nitro in your application" videoId="DkvgJa-X31k"}
+
+## Server Endpoints & Middleware
+
+You can easily manage the server-only part of your Nuxt app, from API endpoints to middleware.
+
+Both endpoints and middleware can be defined like this:
+
+```ts twoslash [server/api/test.ts]
+export default defineEventHandler(async (event) => {
+  // ... Do whatever you want here
+})
+```
+
+And you can directly return `text`, `json`, `html` or even a `stream`.
+
+Out-of-the-box, it supports **hot module replacement** and **auto-import** like the other parts of your Nuxt application.
+
+:read-more{to="/docs/guide/directory-structure/server"}
+
+## Universal Deployment
+
+Nitro offers the ability to deploy your Nuxt app anywhere, from a bare metal server to the edge network, with a start time of just a few milliseconds. That's fast!
+
+:read-more{to="/blog/nuxt-on-the-edge"}
+
+There are more than 15 presets to build your Nuxt app for different cloud providers and servers, including:
+
+- [Cloudflare Workers](https://workers.cloudflare.com)
+- [Netlify Functions](https://www.netlify.com/products/functions)
+- [Vercel Edge Network](https://vercel.com/docs/edge-network)
+
+Or for other runtimes:
+
+::card-group
+  :card{icon="i-logos-deno" title="Deno" to="https://deno.land" target="_blank"}
+  :card{icon="i-logos-bun" title="Bun" to="https://bun.sh" target="_blank"}
+::
+
+:read-more{to="/docs/getting-started/deployment"}
+
+## Hybrid Rendering
+
+Nitro has a powerful feature called `routeRules` which allows you to define a set of rules to customize how each route of your Nuxt app is rendered (and more).
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  routeRules: {
+    // Generated at build time for SEO purpose
+    '/': { prerender: true },
+    // Cached for 1 hour
+    '/api/*': { cache: { maxAge: 60 * 60 } },
+    // Redirection to avoid 404
+    '/old-page': {
+      redirect: { to: '/new-page', statusCode: 302 }
+    }
+    // ...
+  }
+})
+```
+
+::read-more{to="/docs/guide/concepts/rendering#hybrid-rendering"}
+Learn about all available route rules are available to customize the rendering mode of your routes.
+::
+
+In addition, there are some route rules (for example, `ssr`, `appMiddleware`, and `noScripts`) that are Nuxt specific to change the behavior when rendering your pages to HTML.
+
+Some route rules (`appMiddleware`, `redirect` and `prerender`) also affect client-side behavior.
+
+Nitro is used to build the app for server side rendering, as well as pre-rendering.
+
+:read-more{to="/docs/guide/concepts/rendering"}

package/1.getting-started/14.layers.md

@@ -0,0 +1,92 @@
+---
+title: 'Layers'
+description: Nuxt provides a powerful system that allows you to extend the default files, configs, and much more.
+navigation.icon: i-lucide-layers
+---
+
+One of the core features of Nuxt is the layers and extending support. You can extend a default Nuxt application to reuse components, utils, and configuration. The layers structure is almost identical to a standard Nuxt application which makes them easy to author and maintain.
+
+## Use Cases
+
+- Share reusable configuration presets across projects using `nuxt.config` and `app.config`
+- Create a component library using [`components/`](/docs/guide/directory-structure/components) directory
+- Create utility and composable library using [`composables/`](/docs/guide/directory-structure/composables) and [`utils/`](/docs/guide/directory-structure/utils) directories
+- Create Nuxt module presets
+- Share standard setup across projects
+- Create Nuxt themes
+- Enhance code organization by implementing a modular architecture and support Domain-Driven Design (DDD) pattern in large scale projects.
+
+## Usage
+
+By default, any layers within your project in the `~~/layers` directory will be automatically registered as layers in your project.
+
+::note
+Layer auto-registration was introduced in Nuxt v3.12.0.
+::
+
+In addition, named layer aliases to the `srcDir` of each of these layers will automatically be created. For example, you will be able to access the `~~/layers/test` layer via `#layers/test`.
+
+::note
+Named layer aliases were introduced in Nuxt v3.16.0.
+::
+
+In addition, you can extend from a layer by adding the [extends](/docs/api/nuxt-config#extends) property to your [`nuxt.config`](/docs/guide/directory-structure/nuxt-config) file.
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  extends: [
+    '../base',                     // Extend from a local layer
+    '@my-themes/awesome',          // Extend from an installed npm package
+    'github:my-themes/awesome#v1', // Extend from a git repository
+  ]
+})
+```
+
+You can also pass an authentication token if you are extending from a private GitHub repository:
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  extends: [
+    // per layer configuration
+    ['github:my-themes/private-awesome', { auth: process.env.GITHUB_TOKEN }]
+  ]
+})
+```
+
+::tip
+You can override a layer's alias by specifying it in the options next to the layer source.
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  extends: [
+    [
+      'github:my-themes/awesome',
+      { 
+        meta: {
+          name: 'my-awesome-theme',
+        },
+      },
+    ],
+  ]
+})
+```
+
+::
+
+Nuxt uses [unjs/c12](https://c12.unjs.io) and [unjs/giget](https://giget.unjs.io) for extending remote layers. Check the documentation for more information and all available options.
+
+::read-more{to="/docs/guide/going-further/layers"}
+Read more about layers in the **Layer Author Guide**.
+::
+
+:video-accordion{title="Watch a video from Learn Vue about Nuxt Layers" videoId="lnFCM7c9f7I"}
+
+:video-accordion{title="Watch a video from Alexander Lichter about Nuxt Layers" videoId="fr5yo3aVkfA"}
+
+## Examples
+
+::card-group
+  ::card{icon="i-simple-icons-github" title="Content Wind" to="https://github.com/Atinux/content-wind" target="_blank"}
+  A lightweight Nuxt theme to build a Markdown driven website. Powered by Nuxt Content, TailwindCSS and Iconify.
+  ::
+::