@nuxt/docs 0.0.0 → 3.17.0

package/2.guide/2.directory-structure/1.composables.md

@@ -0,0 +1,121 @@
+---
+title: 'composables'
+head.title: 'composables/'
+description: Use the composables/ directory to auto-import your Vue composables into your application.
+navigation.icon: i-lucide-folder
+---
+
+## Usage
+
+**Method 1:** Using named export
+
+```js [composables/useFoo.ts]
+export const useFoo = () => {
+  return useState('foo', () => 'bar')
+}
+```
+
+**Method 2:** Using default export
+
+```js [composables/use-foo.ts or composables/useFoo.ts]
+// It will be available as useFoo() (camelCase of file name without extension)
+export default function () {
+  return useState('foo', () => 'bar')
+}
+```
+
+**Usage:** You can now use auto imported composable in `.js`, `.ts` and `.vue` files
+
+```vue [app.vue]
+<script setup lang="ts">
+const foo = useFoo()
+</script>
+
+<template>
+  <div>
+    {{ foo }}
+  </div>
+</template>
+```
+
+::note
+The `composables/` directory in Nuxt does not provide any additional reactivity capabilities to your code. Instead, any reactivity within composables is achieved using Vue's Composition API mechanisms, such as ref and reactive. Note that reactive code is also not limited to the boundaries of the `composables/` directory. You are free to employ reactivity features wherever they're needed in your application.
+::
+
+:read-more{to="/docs/guide/concepts/auto-imports"}
+
+:link-example{to="/docs/examples/features/auto-imports"}
+
+## Types
+
+Under the hood, Nuxt auto generates the file `.nuxt/imports.d.ts` to declare the types.
+
+Be aware that you have to run [`nuxi prepare`](/docs/api/commands/prepare), [`nuxi dev`](/docs/api/commands/dev) or [`nuxi build`](/docs/api/commands/build) in order to let Nuxt generate the types.
+
+::note
+If you create a composable without having the dev server running, TypeScript will throw an error, such as `Cannot find name 'useBar'.`
+::
+
+## Examples
+
+### Nested Composables
+
+You can use a composable within another composable using auto imports:
+
+```js [composables/test.ts]
+export const useFoo = () => {
+  const nuxtApp = useNuxtApp()
+  const bar = useBar()
+}
+```
+
+### Access plugin injections
+
+You can access [plugin injections](/docs/guide/directory-structure/plugins#providing-helpers) from composables:
+
+```js [composables/test.ts]
+export const useHello = () => {
+  const nuxtApp = useNuxtApp()
+  return nuxtApp.$hello
+}
+```
+
+## How Files Are Scanned
+
+Nuxt only scans files at the top level of the [`composables/` directory](/docs/guide/directory-structure/composables), e.g.:
+
+```bash [Directory Structure]
+-| composables/
+---| index.ts     // scanned
+---| useFoo.ts    // scanned
+---| nested/
+-----| utils.ts   // not scanned
+```
+
+Only `composables/index.ts` and `composables/useFoo.ts` would be searched for imports.
+
+To get auto imports working for nested modules, you could either re-export them (recommended) or configure the scanner to include nested directories:
+
+**Example:** Re-export the composables you need from the `composables/index.ts` file:
+
+```ts [composables/index.ts]
+// Enables auto import for this export
+export { utils } from './nested/utils.ts'
+```
+
+**Example:** Scan nested directories inside the `composables/` folder:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  imports: {
+    dirs: [
+      // Scan top-level modules
+      'composables',
+      // ... or scan modules nested one level deep with a specific name and file extension
+      'composables/*/index.{ts,js,mjs,mts}',
+      // ... or scan all modules within given directory
+      'composables/**'
+    ]
+  }
+})
+```

package/2.guide/2.directory-structure/1.content.md

@@ -0,0 +1,64 @@
+---
+title: 'content'
+head.title: 'content/'
+description: Use the content/ directory to create a file-based CMS for your application.
+navigation.icon: i-lucide-folder
+---
+
+[Nuxt Content](https://content.nuxt.com) reads the [`content/` directory](/docs/guide/directory-structure/content) in your project and parses `.md`, `.yml`, `.csv` and `.json` files to create a file-based CMS for your application.
+
+- Render your content with built-in components.
+- Query your content with a MongoDB-like API.
+- Use your Vue components in Markdown files with the MDC syntax.
+- Automatically generate your navigation.
+
+::read-more{to="https://content.nuxt.com" target="_blank"}
+Learn more in **Nuxt Content** documentation.
+::
+
+## Enable Nuxt Content
+
+Install the `@nuxt/content` module in your project as well as adding it to your `nuxt.config.ts` with one command:
+
+```bash [Terminal]
+npx nuxi module add content
+```
+
+## Create Content
+
+Place your markdown files inside the `content/` directory:
+
+```md [content/index.md]
+# Hello Content
+```
+
+The module automatically loads and parses them.
+
+## Render Content
+
+To render content pages, add a [catch-all route](/docs/guide/directory-structure/pages/#catch-all-route) using the [`<ContentRenderer>`](https://content.nuxt.com/docs/components/content-renderer) component:
+
+```vue [pages/[...slug\\].vue]
+<script lang="ts" setup>
+const route = useRoute()
+const { data: page } = await useAsyncData(route.path, () => {
+  return queryCollection('content').path(route.path).first()
+})
+</script>
+
+<template>
+  <div>
+    <header><!-- ... --></header>
+
+    <ContentRenderer v-if="page" :value="page" />
+
+    <footer><!-- ... --></footer>
+  </div>
+</template>
+```
+
+## Documentation
+
+::tip{ icon="i-lucide-book" }
+Head over to <https://content.nuxt.com> to learn more about the Content module features, such as how to build queries and use Vue components in your Markdown files with the MDC syntax.
+::

package/2.guide/2.directory-structure/1.layouts.md

@@ -0,0 +1,180 @@
+---
+title: "layouts"
+head.title: "layouts/"
+description: "Nuxt provides a layouts framework to extract common UI patterns into reusable layouts."
+navigation.icon: i-lucide-folder
+---
+
+::tip{icon="i-lucide-rocket" }
+For best performance, components placed in this directory will be automatically loaded via asynchronous import when used.
+::
+
+## Enable Layouts
+
+Layouts are enabled by adding [`<NuxtLayout>`](/docs/api/components/nuxt-layout) to your [`app.vue`](/docs/guide/directory-structure/app):
+
+```vue [app.vue]
+<template>
+  <NuxtLayout>
+    <NuxtPage />
+  </NuxtLayout>
+</template>
+```
+
+To use a layout:
+- Set a `layout` property in your page with [definePageMeta](/docs/api/utils/define-page-meta).
+- Set the `name` prop of `<NuxtLayout>`.
+
+::note
+The layout name is normalized to kebab-case, so `someLayout` becomes `some-layout`.
+::
+
+::note
+If no layout is specified, `layouts/default.vue` will be used.
+::
+
+::important
+If you only have a single layout in your application, we recommend using [`app.vue`](/docs/guide/directory-structure/app) instead.
+::
+
+::important
+Unlike other components, your layouts must have a single root element to allow Nuxt to apply transitions between layout changes - and this root element cannot be a `<slot />`.
+::
+
+## Default Layout
+
+Add a `~/layouts/default.vue`:
+
+```vue [layouts/default.vue]
+<template>
+  <div>
+    <p>Some default layout content shared across all pages</p>
+    <slot />
+  </div>
+</template>
+```
+
+In a layout file, the content of the page will be displayed in the `<slot />` component.
+
+## Named Layout
+
+```bash [Directory Structure]
+-| layouts/
+---| default.vue
+---| custom.vue
+```
+
+Then you can use the `custom` layout in your page:
+
+```vue twoslash [pages/about.vue]
+<script setup lang="ts">
+definePageMeta({
+  layout: 'custom'
+})
+</script>
+```
+
+::read-more{to="/docs/guide/directory-structure/pages#page-metadata"}
+Learn more about `definePageMeta`.
+::
+
+You can directly override the default layout for all pages using the `name` property of [`<NuxtLayout>`](/docs/api/components/nuxt-layout):
+
+```vue [app.vue]
+<script setup lang="ts">
+// You might choose this based on an API call or logged-in status
+const layout = "custom";
+</script>
+
+<template>
+  <NuxtLayout :name="layout">
+    <NuxtPage />
+  </NuxtLayout>
+</template>
+```
+
+If you have a layout in nested directories, the layout's name will be based on its own path directory and filename, with duplicate segments being removed.
+
+File | Layout Name
+-- | --
+`~/layouts/desktop/default.vue` | `desktop-default`
+`~/layouts/desktop-base/base.vue` | `desktop-base`
+`~/layouts/desktop/index.vue` | `desktop`
+
+For clarity, we recommend that the layout's filename matches its name:
+
+File | Layout Name
+-- | --
+`~/layouts/desktop/DesktopDefault.vue` | `desktop-default`
+`~/layouts/desktop-base/DesktopBase.vue` | `desktop-base`
+`~/layouts/desktop/Desktop.vue` | `desktop`
+
+:link-example{to="/docs/examples/features/layouts"}
+
+## Changing the Layout Dynamically
+
+You can also use the [`setPageLayout`](/docs/api/utils/set-page-layout) helper to change the layout dynamically:
+
+```vue twoslash
+<script setup lang="ts">
+function enableCustomLayout () {
+  setPageLayout('custom')
+}
+definePageMeta({
+  layout: false,
+});
+</script>
+
+<template>
+  <div>
+    <button @click="enableCustomLayout">Update layout</button>
+  </div>
+</template>
+```
+
+:link-example{to="/docs/examples/features/layouts"}
+
+## Overriding a Layout on a Per-page Basis
+
+If you are using pages, you can take full control by setting `layout: false` and then using the `<NuxtLayout>` component within the page.
+
+::code-group
+
+```vue [pages/index.vue]
+<script setup lang="ts">
+definePageMeta({
+  layout: false,
+})
+</script>
+
+<template>
+  <div>
+    <NuxtLayout name="custom">
+      <template #header> Some header template content. </template>
+
+      The rest of the page
+    </NuxtLayout>
+  </div>
+</template>
+```
+
+```vue [layouts/custom.vue]
+<template>
+  <div>
+    <header>
+      <slot name="header">
+        Default header content
+      </slot>
+    </header>
+    <main>
+      <slot />
+    </main>
+  </div>
+</template>
+```
+
+::
+
+::important
+If you use `<NuxtLayout>` within your pages, make sure it is not the root element (or [disable layout/page transitions](/docs/getting-started/transitions#disable-transitions)).
+::

package/2.guide/2.directory-structure/1.middleware.md

@@ -0,0 +1,209 @@
+---
+title: "middleware"
+description: "Nuxt provides middleware to run code before navigating to a particular route."
+head.title: "middleware/"
+navigation.icon: i-lucide-folder
+---
+
+Nuxt provides a customizable **route middleware** framework you can use throughout your application, ideal for extracting code that you want to run before navigating to a particular route.
+
+There are three kinds of route middleware:
+
+1. Anonymous (or inline) route middleware are defined directly within the page.
+2. Named route middleware, placed in the `middleware/` and automatically loaded via asynchronous import when used on a page.
+3. Global route middleware, placed in the `middleware/` with a `.global` suffix and is run on every route change.
+
+The first two kinds of route middleware can be defined in [`definePageMeta`](/docs/api/utils/define-page-meta).
+
+::note
+Name of middleware are normalized to kebab-case: `myMiddleware` becomes `my-middleware`.
+::
+
+::note
+Route middleware run within the Vue part of your Nuxt app. Despite the similar name, they are completely different from [server middleware](/docs/guide/directory-structure/server#server-middleware), which are run in the Nitro server part of your app.
+::
+
+:video-accordion{title="Watch a video from Vue School on all 3 kinds of middleware" videoId="761471577" platform="vimeo"}
+
+## Usage
+
+Route middleware are navigation guards that receive the current route and the next route as arguments.
+
+```ts twoslash [middleware/my-middleware.ts]
+export default defineNuxtRouteMiddleware((to, from) => {
+  if (to.params.id === '1') {
+    return abortNavigation()
+  }
+  // In a real app you would probably not redirect every route to `/`
+  // however it is important to check `to.path` before redirecting or you
+  // might get an infinite redirect loop
+  if (to.path !== '/') {
+    return navigateTo('/')
+  }
+})
+```
+
+Nuxt provides two globally available helpers that can be returned directly from the middleware.
+
+1. [`navigateTo`](/docs/api/utils/navigate-to) - Redirects to the given route
+2. [`abortNavigation`](/docs/api/utils/abort-navigation) - Aborts the navigation, with an optional error message.
+
+Unlike [navigation guards](https://router.vuejs.org/guide/advanced/navigation-guards.html#global-before-guards) from `vue-router`, a third `next()` argument is not passed, and **redirect or route cancellation is handled by returning a value from the middleware**.
+
+Possible return values are:
+
+* nothing (a simple `return` or no return at all) - does not block navigation and will move to the next middleware function, if any, or complete the route navigation
+* `return navigateTo('/')` - redirects to the given path and will set the redirect code to [`302` Found](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/302) if the redirect happens on the server side
+* `return navigateTo('/', { redirectCode: 301 })` - redirects to the given path and will set the redirect code to [`301` Moved Permanently](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/301) if the redirect happens on the server side
+* `return abortNavigation()` - stops the current navigation
+* `return abortNavigation(error)` - rejects the current navigation with an error
+
+:read-more{to="/docs/api/utils/navigate-to"}
+:read-more{to="/docs/api/utils/abort-navigation"}
+
+::important
+We recommend using the helper functions above for performing redirects or stopping navigation. Other possible return values described in [the vue-router docs](https://router.vuejs.org/guide/advanced/navigation-guards.html#global-before-guards) may work but there may be breaking changes in future.
+::
+
+## Middleware Order
+
+Middleware runs in the following order:
+
+1. Global Middleware
+2. Page defined middleware order (if there are multiple middleware declared with the array syntax)
+
+For example, assuming you have the following middleware and component:
+
+```bash [middleware/ directory]
+-| middleware/
+---| analytics.global.ts
+---| setup.global.ts
+---| auth.ts
+```
+
+```vue twoslash [pages/profile.vue]
+<script setup lang="ts">
+definePageMeta({
+  middleware: [
+    function (to, from) {
+      // Custom inline middleware
+    },
+    'auth',
+  ],
+});
+</script>
+```
+
+You can expect the middleware to be run in the following order:
+
+1. `analytics.global.ts`
+2. `setup.global.ts`
+3. Custom inline middleware
+4. `auth.ts`
+
+### Ordering Global Middleware
+
+By default, global middleware is executed alphabetically based on the filename.
+
+However, there may be times you want to define a specific order. For example, in the last scenario, `setup.global.ts` may need to run before `analytics.global.ts`. In that case, we recommend prefixing global middleware with 'alphabetical' numbering.
+
+```bash [Directory structure]
+-| middleware/
+---| 01.setup.global.ts
+---| 02.analytics.global.ts
+---| auth.ts
+```
+
+::note
+In case you're new to 'alphabetical' numbering, remember that filenames are sorted as strings, not as numeric values. For example, `10.new.global.ts` would come before `2.new.global.ts`. This is why the example prefixes single digit numbers with `0`.
+::
+
+## When Middleware Runs
+
+If your site is server-rendered or generated, middleware for the initial page will be executed both when the page is rendered and then again on the client. This might be needed if your middleware needs a browser environment, such as if you have a generated site, aggressively cache responses, or want to read a value from local storage.
+
+However, if you want to avoid this behaviour you can do so:
+
+```ts twoslash [middleware/example.ts]
+export default defineNuxtRouteMiddleware(to => {
+  // skip middleware on server
+  if (import.meta.server) return
+  // skip middleware on client side entirely
+  if (import.meta.client) return
+  // or only skip middleware on initial client load
+  const nuxtApp = useNuxtApp()
+  if (import.meta.client && nuxtApp.isHydrating && nuxtApp.payload.serverRendered) return
+})
+```
+
+This is true even if you throw an error in your middleware on the server, and an error page is rendered. The middleware will still run again in the browser.
+
+::note
+Rendering an error page is an entirely separate page load, meaning any registered middleware will run again. You can use [`useError`](/docs/getting-started/error-handling#useerror) in middleware to check if an error is being handled.
+::
+
+## Adding Middleware Dynamically
+
+It is possible to add global or named route middleware manually using the [`addRouteMiddleware()`](/docs/api/utils/add-route-middleware) helper function, such as from within a plugin.
+
+```ts twoslash
+export default defineNuxtPlugin(() => {
+  addRouteMiddleware('global-test', () => {
+    console.log('this global middleware was added in a plugin and will be run on every route change')
+  }, { global: true })
+
+  addRouteMiddleware('named-test', () => {
+    console.log('this named middleware was added in a plugin and would override any existing middleware of the same name')
+  })
+})
+```
+
+## Example
+
+```bash [Directory Structure]
+-| middleware/
+---| auth.ts
+```
+
+In your page file, you can reference this route middleware:
+
+```vue twoslash
+<script setup lang="ts">
+definePageMeta({
+  middleware: ["auth"]
+  // or middleware: 'auth'
+})
+</script>
+```
+
+Now, before navigation to that page can complete, the `auth` route middleware will be run.
+
+:link-example{to="/docs/examples/routing/middleware"}
+
+## Setting Middleware at Build Time
+
+Instead of using `definePageMeta` on each page, you can add named route middleware within the `pages:extend` hook.
+
+```ts twoslash [nuxt.config.ts]
+import type { NuxtPage } from 'nuxt/schema'
+
+export default defineNuxtConfig({
+  hooks: {
+    'pages:extend' (pages) {
+      function setMiddleware (pages: NuxtPage[]) {
+        for (const page of pages) {
+          if (/* some condition */ true) {
+            page.meta ||= {}
+            // Note that this will override any middleware set in `definePageMeta` in the page
+            page.meta.middleware = ['named']
+          }
+          if (page.children) {
+            setMiddleware(page.children)
+          }
+        }
+      }
+      setMiddleware(pages)
+    }
+  }
+})
+```

package/2.guide/2.directory-structure/1.modules.md

@@ -0,0 +1,66 @@
+---
+title: 'modules'
+head.title: 'modules/'
+description: Use the modules/ directory to automatically register local modules within your application.
+navigation.icon: i-lucide-folder
+---
+
+It is a good place to place any local modules you develop while building your application.
+
+The auto-registered files patterns are:
+- `modules/*/index.ts`
+- `modules/*.ts`
+
+You don't need to add those local modules to your [`nuxt.config.ts`](/docs/guide/directory-structure/nuxt-config) separately.
+
+::code-group
+
+```ts twoslash [modules/hello/index.ts]
+// `nuxt/kit` is a helper subpath import you can use when defining local modules
+// that means you do not need to add `@nuxt/kit` to your project's dependencies
+import { createResolver, defineNuxtModule, addServerHandler } from 'nuxt/kit'
+
+export default defineNuxtModule({
+  meta: {
+    name: 'hello'
+  },
+  setup () {
+    const resolver = createResolver(import.meta.url)
+
+    // Add an API route
+    addServerHandler({
+      route: '/api/hello',
+      handler: resolver.resolve('./runtime/api-route')
+    })
+  }
+})
+```
+
+```ts twoslash [modules/hello/runtime/api-route.ts]
+export default defineEventHandler(() => {
+  return { hello: 'world' }
+})
+```
+
+::
+
+When starting Nuxt, the `hello` module will be registered and the `/api/hello` route will be available.
+
+Modules are executed in the following sequence:
+- First, the modules defined in [`nuxt.config.ts`](/docs/api/nuxt-config#modules-1) are loaded.
+- Then, modules found in the `modules/` directory are executed, and they load in alphabetical order.
+
+You can change the order of local module by adding a number to the front of each directory name:
+
+```bash [Directory structure]
+modules/
+  1.first-module/
+    index.ts
+  2.second-module.ts
+```
+
+:read-more{to="/docs/guide/going-further/modules"}
+
+::tip{icon="i-lucide-video" to="https://vueschool.io/lessons/creating-your-first-module-from-scratch?friend=nuxt" target="_blank"}
+Watch Vue School video about Nuxt private modules.
+::

package/2.guide/2.directory-structure/1.node_modules.md

@@ -0,0 +1,12 @@
+---
+title: "node_modules"
+description: "The package manager stores the dependencies of your project in the node_modules/ directory."
+head.title: "node_modules/"
+navigation.icon: i-lucide-folder
+---
+
+The package manager ([`npm`](https://docs.npmjs.com/cli/commands/npm) or [`yarn`](https://yarnpkg.com) or [`pnpm`](https://pnpm.io/cli/install) or [`bun`](https://bun.sh/package-manager)) creates this directory to store the dependencies of your project.
+
+::important
+This directory should be added to your [`.gitignore`](/docs/guide/directory-structure/gitignore) file to avoid pushing the dependencies to your repository.
+::