@nuxt/docs 0.0.0 → 3.17.0

package/2.guide/4.recipes/2.vite-plugin.md

@@ -0,0 +1,65 @@
+---
+navigation.title: 'Vite Plugins'
+title: Using Vite Plugins in Nuxt
+description: Learn how to integrate Vite plugins into your Nuxt project.
+---
+
+While Nuxt modules offer extensive functionality, sometimes a specific Vite plugin might meet your needs more directly.
+
+First, we need to install the Vite plugin, for our example, we'll use `@rollup/plugin-yaml`:
+
+::code-group{sync="pm"}
+
+  ```bash [npm]
+  npm install @rollup/plugin-yaml
+  ```
+
+  ```bash [yarn]
+  yarn add @rollup/plugin-yaml
+  ```
+
+  ```bash [pnpm]
+  pnpm add @rollup/plugin-yaml
+  ```
+
+  ```bash [bun]
+  bun add @rollup/plugin-yaml
+  ```
+
+::
+
+Next, we need to import and add it to our [`nuxt.config.ts`](/docs/guide/directory-structure/nuxt-config) file:
+
+```ts [nuxt.config.ts]
+import yaml from '@rollup/plugin-yaml'
+
+export default defineNuxtConfig({
+  vite: {
+    plugins: [
+      yaml()
+    ]
+  }
+})
+```
+
+Now we installed and configured our Vite plugin, we can start using YAML files directly in our project.
+
+For example, we can have a `config.yaml` that stores configuration data and import this data in our Nuxt components:
+
+::code-group
+
+```yaml [data/hello.yaml]
+greeting: "Hello, Nuxt with Vite!"
+```
+
+```vue [components/Hello.vue]
+<script setup>
+import config from '~/data/hello.yaml'
+</script>
+
+<template>
+  <h1>{{ config.greeting }}</h1>
+</template>
+```
+
+::

package/2.guide/4.recipes/3.custom-usefetch.md

@@ -0,0 +1,125 @@
+---
+navigation.title: 'Custom useFetch'
+title: Custom useFetch in Nuxt
+description: How to create a custom fetcher for calling your external API in Nuxt.
+---
+
+When working with Nuxt, you might be making the frontend and fetching an external API, and you might want to set some default options for fetching from your API.
+
+The [`$fetch`](/docs/api/utils/dollarfetch) utility function (used by the [`useFetch`](/docs/api/composables/use-fetch) composable) is intentionally not globally configurable. This is important so that fetching behavior throughout your application remains consistent, and other integrations (like modules) can rely on the behavior of core utilities like `$fetch`.
+
+However, Nuxt provides a way to create a custom fetcher for your API (or multiple fetchers if you have multiple APIs to call).
+
+## Custom `$fetch`
+
+Let's create a custom `$fetch` instance with a [Nuxt plugin](/docs/guide/directory-structure/plugins).
+
+::note
+`$fetch` is a configured instance of [ofetch](https://github.com/unjs/ofetch) which supports adding the base URL of your Nuxt server as well as direct function calls during SSR (avoiding HTTP roundtrips).
+::
+
+Let's pretend here that:
+- The main API is https://api.nuxt.com
+- We are storing the JWT token in a session with [nuxt-auth-utils](https://github.com/atinux/nuxt-auth-utils)
+- If the API responds with a `401` status code, we redirect the user to the `/login` page
+
+```ts [plugins/api.ts]
+export default defineNuxtPlugin((nuxtApp) => {
+  const { session } = useUserSession()
+
+  const api = $fetch.create({
+    baseURL: 'https://api.nuxt.com',
+    onRequest({ request, options, error }) {
+      if (session.value?.token) {
+        // note that this relies on ofetch >= 1.4.0 - you may need to refresh your lockfile
+        options.headers.set('Authorization', `Bearer ${session.value?.token}`)
+      }
+    },
+    async onResponseError({ response }) {
+      if (response.status === 401) {
+        await nuxtApp.runWithContext(() => navigateTo('/login'))
+      }
+    }
+  })
+
+  // Expose to useNuxtApp().$api
+  return {
+    provide: {
+      api
+    }
+  }
+})
+```
+
+With this Nuxt plugin, `$api` is exposed from `useNuxtApp()` to make API calls directly from the Vue components:
+
+```vue [app.vue]
+<script setup>
+const { $api } = useNuxtApp()
+const { data: modules } = await useAsyncData('modules', () => $api('/modules'))
+</script>
+```
+
+::callout
+Wrapping with [`useAsyncData`](/docs/api/composables/use-async-data) **avoid double data fetching when doing server-side rendering** (server & client on hydration).
+::
+
+## Custom `useFetch`/`useAsyncData`
+
+Now that `$api` has the logic we want, let's create a `useAPI` composable to replace the usage of `useAsyncData` + `$api`:
+
+```ts [composables/useAPI.ts]
+import type { UseFetchOptions } from 'nuxt/app'
+
+export function useAPI<T>(
+  url: string | (() => string),
+  options?: UseFetchOptions<T>,
+) {
+  return useFetch(url, {
+    ...options,
+    $fetch: useNuxtApp().$api as typeof $fetch
+  })
+}
+```
+
+Let's use the new composable and have a nice and clean component:
+
+```vue [app.vue]
+<script setup>
+const { data: modules } = await useAPI('/modules')
+</script>
+```
+
+If you want to customize the type of any error returned, you can also do so:
+
+```ts
+import type { FetchError } from 'ofetch'
+import type { UseFetchOptions } from 'nuxt/app'
+
+interface CustomError {
+  message: string
+  statusCode: number
+}
+
+export function useAPI<T>(
+  url: string | (() => string),
+  options?: UseFetchOptions<T>,
+) {
+  return useFetch<T, FetchError<CustomError>>(url, {
+    ...options,
+    $fetch: useNuxtApp().$api
+  })
+}
+```
+
+::note
+This example demonstrates how to use a custom `useFetch`, but the same structure is identical for a custom `useAsyncData`.
+::
+
+:link-example{to="/docs/examples/advanced/use-custom-fetch-composable"}
+
+:video-accordion{title="Watch a video about custom $fetch and Repository Pattern in Nuxt" videoId="jXH8Tr-exhI"}
+
+::note
+We are currently discussing to find a cleaner way to let you create a custom fetcher, see https://github.com/nuxt/nuxt/issues/14736.
+::

package/2.guide/4.recipes/4.sessions-and-authentication.md

@@ -0,0 +1,203 @@
+---
+title: 'Sessions and Authentication'
+description: "Authentication is an extremely common requirement in web apps. This recipe will show you how to implement basic user registration and authentication in your Nuxt app."
+---
+
+## Introduction
+
+In this recipe we'll be setting up authentication in a full-stack Nuxt app using [Nuxt Auth Utils](https://github.com/Atinux/nuxt-auth-utils) which provides convenient utilities for managing client-side and server-side session data.
+
+The module uses secured & sealed cookies to store session data, so you don't need to setup a database to store session data.
+
+## Install nuxt-auth-utils
+
+Install the `nuxt-auth-utils` module using the `nuxi` CLI.
+
+```bash [Terminal]
+npx nuxi@latest module add auth-utils
+```
+
+::callout
+This command will install `nuxt-auth-utils` as dependency and push it in the `modules` section of our `nuxt.config.ts`
+::
+
+## Cookie Encryption Key
+
+As `nuxt-auth-utils` uses sealed cookies to store session data, session cookies are encrypted using a secret key from the `NUXT_SESSION_PASSWORD` environment variable.
+
+::note
+If not set, this environment variable will be added to your `.env` automatically when running in development mode.
+::
+
+```ini [.env]
+NUXT_SESSION_PASSWORD=a-random-password-with-at-least-32-characters
+```
+
+::important
+You'll need to add this environment variable to your production environment before deploying.
+::
+
+## Login API Route
+
+For this recipe, we'll create a simple API route to sign-in a user based on static data.
+
+Let's create a `/api/login` API route that will accept a POST request with the email and password in the request body.
+
+```ts [server/api/login.post.ts]
+import { z } from 'zod'
+
+const bodySchema = z.object({
+  email: z.string().email(),
+  password: z.string().min(8)
+})
+
+export default defineEventHandler(async (event) => {
+  const { email, password } = await readValidatedBody(event, bodySchema.parse)
+
+  if (email === 'admin@admin.com' && password === 'iamtheadmin') {
+    // set the user session in the cookie
+    // this server util is auto-imported by the auth-utils module
+    await setUserSession(event, {
+      user: {
+        name: 'John Doe'
+      }
+    })
+    return {}
+  }
+  throw createError({
+    statusCode: 401,
+    message: 'Bad credentials'
+  })
+})
+```
+
+::callout
+Make sure to install the `zod` dependency in your project (`npm i zod`).
+::
+
+::tip{to="https://github.com/atinux/nuxt-auth-utils#server-utils"}
+Read more about the `setUserSession` server helper exposed by `nuxt-auth-utils`.
+::
+
+## Login Page
+
+The module exposes a Vue composable to know if a user is authenticated in our application:
+
+```vue
+<script setup>
+const { loggedIn, session, user, clear, fetch } = useUserSession()
+</script>
+```
+
+Let's create a login page with a form to submit the login data to our `/api/login` route.
+
+```vue [pages/login.vue]
+<script setup lang="ts">
+const { loggedIn, user, fetch: refreshSession } = useUserSession()
+const credentials = reactive({
+  email: '',
+  password: '',
+})
+async function login() {
+  $fetch('/api/login', {
+    method: 'POST',
+    body: credentials
+  })
+  .then(async () => {
+    // Refresh the session on client-side and redirect to the home page
+    await refreshSession()
+    await navigateTo('/')
+  })
+  .catch(() => alert('Bad credentials'))
+}
+</script>
+
+<template>
+  <form @submit.prevent="login">
+    <input v-model="credentials.email" type="email" placeholder="Email" />
+    <input v-model="credentials.password" type="password" placeholder="Password" />
+    <button type="submit">Login</button>
+  </form>
+</template>
+```
+
+## Protect API Routes
+
+Protecting server routes is key to making sure your data is safe. Client-side middleware is helpful for the user, but without server-side protection your data can still be accessed. It is critical to protect any routes with sensitive data, we should return a 401 error if the user is not logged in on those.
+
+The `auth-utils` module provides the `requireUserSession` utility function to help make sure that users are logged in and have an active session.
+
+Let's create an example of a `/api/user/stats` route that only authenticated users can access.
+
+```ts [server/api/user/stats.get.ts]
+export default defineEventHandler(async (event) => {
+  // make sure the user is logged in
+  // This will throw a 401 error if the request doesn't come from a valid user session
+  const { user } = await requireUserSession(event)
+
+  // TODO: Fetch some stats based on the user
+
+  return {}
+});
+```
+
+## Protect App Routes
+
+Our data is safe with the server-side route in place, but without doing anything else, unauthenticated users would probably get some odd data when trying to access the `/users` page. We should create a [client-side middleware](https://nuxt.com/docs/guide/directory-structure/middleware) to protect the route on the client side and redirect users to the login page.
+
+`nuxt-auth-utils` provides a convenient `useUserSession` composable which we'll use to check if the user is logged in, and redirect them if they are not.
+
+We'll create a middleware in the `/middleware` directory. Unlike on the server, client-side middleware is not automatically applied to all endpoints, and we'll need to specify where we want it applied.
+
+```typescript [middleware/authenticated.ts]
+export default defineNuxtRouteMiddleware(() => {
+  const { loggedIn } = useUserSession()
+
+  // redirect the user to the login screen if they're not authenticated
+  if (!loggedIn.value) {
+    return navigateTo('/login')
+  }
+})
+```
+
+## Home Page
+
+Now that we have our app middleware to protect our routes, we can use it on our home page that display our authenticated user informations. If the user is not authenticated, they will be redirected to the login page.
+
+We'll use [`definePageMeta`](/docs/api/utils/define-page-meta) to apply the middleware to the route that we want to protect.
+
+```vue [pages/index.vue]
+<script setup lang="ts">
+definePageMeta({
+  middleware: ['authenticated'],
+})
+  
+const { user, clear: clearSession } = useUserSession()
+
+async function logout() {
+  await clearSession()
+  await navigateTo('/login')
+}
+</script>
+
+<template>
+  <div>
+    <h1>Welcome {{ user.name }}</h1>
+    <button @click="logout">Logout</button>
+  </div>
+</template>
+```
+
+We also added a logout button to clear the session and redirect the user to the login page.
+
+## Conclusion
+
+We've successfully set up a very basic user authentication and session management in our Nuxt app. We've also protected sensitive routes on the server and client side to ensure that only authenticated users can access them.
+
+As next steps, you can:
+- Add authentication using the [20+ supported OAuth providers](https://github.com/atinux/nuxt-auth-utils?tab=readme-ov-file#supported-oauth-providers)
+- Add a database to store users, see [Nitro SQL Database](https://nitro.build/guide/database) or [NuxtHub SQL Database](https://hub.nuxt.com/docs/features/database)
+- Let user signup with email & password using [password hashing](https://github.com/atinux/nuxt-auth-utils?tab=readme-ov-file#password-hashing)
+- Add support for [WebAuthn / Passkeys](https://github.com/atinux/nuxt-auth-utils?tab=readme-ov-file#webauthn-passkey)
+
+Checkout the open source [atidone repository](https://github.com/atinux/atidone) for a full example of a Nuxt app with OAuth authentication, database and CRUD operations.

package/3.api/.navigation.yml

@@ -0,0 +1,3 @@
+title: API
+titleTemplate: '%s · Nuxt API'
+icon: i-lucide-code-xml

package/3.api/1.components/.navigation.yml

@@ -0,0 +1,3 @@
+title: 'Components'
+titleTemplate: '%s · Nuxt Components'
+icon: i-lucide-box

package/3.api/1.components/1.client-only.md

@@ -0,0 +1,76 @@
+---
+title: '<ClientOnly>'
+description: Render components only in client-side with the <ClientOnly> component.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/components/client-only.ts
+    size: xs
+---
+
+The `<ClientOnly>` component is used for purposely rendering a component only on client side.
+
+::note
+The content of the default slot will be tree-shaken out of the server build. (This does mean that any CSS used by components within it may not be inlined when rendering the initial HTML.)
+::
+
+## Props
+
+- `placeholderTag` | `fallbackTag`: specify a tag to be rendered server-side.
+- `placeholder` | `fallback`: specify a content to be rendered server-side.
+
+```vue
+<template>
+  <div>
+    <Sidebar />
+    <!-- The <Comment> component will only be rendered on client-side -->
+    <ClientOnly fallback-tag="span" fallback="Loading comments...">
+      <Comment />
+    </ClientOnly>
+  </div>
+</template>
+```
+
+## Slots
+
+- `#fallback`: specify a content to be rendered on the server and displayed until `<ClientOnly>` is mounted in the browser.
+
+```vue [pages/example.vue]
+<template>
+  <div>
+    <Sidebar />
+    <!-- This renders the "span" element on the server side -->
+    <ClientOnly fallbackTag="span">
+      <!-- this component will only be rendered on client side -->
+      <Comments />
+      <template #fallback>
+        <!-- this will be rendered on server side -->
+        <p>Loading comments...</p>
+      </template>
+    </ClientOnly>
+  </div>
+</template>
+```
+
+## Examples
+
+### Accessing HTML Elements
+
+Components inside `<ClientOnly>` are rendered only after being mounted. To access the rendered elements in the DOM, you can watch a template ref:
+
+```vue [pages/example.vue]
+<script setup lang="ts">
+const nuxtWelcomeRef = useTemplateRef('nuxtWelcomeRef')
+
+// The watch will be triggered when the component is available
+watch(nuxtWelcomeRef, () => {
+ console.log('<NuxtWelcome /> mounted')
+}, { once: true })
+</script>
+
+<template>
+  <ClientOnly>
+    <NuxtWelcome ref="nuxtWelcomeRef" />
+  </ClientOnly>
+</template>
+```

package/3.api/1.components/1.dev-only.md

@@ -0,0 +1,51 @@
+---
+title: '<DevOnly>'
+description: Render components only during development with the <DevOnly> component.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/components/dev-only.ts
+    size: xs
+---
+
+Nuxt provides the `<DevOnly>` component to render a component only during development.
+
+The content will not be included in production builds.
+
+```vue [pages/example.vue]
+<template>
+  <div>
+    <Sidebar />
+    <DevOnly>
+      <!-- this component will only be rendered during development -->
+      <LazyDebugBar />
+
+      <!-- if you ever require to have a replacement during production -->
+      <!-- be sure to test these using `nuxt preview` -->
+      <template #fallback>
+        <div><!-- empty div for flex.justify-between --></div>
+      </template>
+    </DevOnly>
+  </div>
+</template>
+```
+
+## Slots
+
+- `#fallback`: if you ever require to have a replacement during production.
+
+```vue
+<template>
+  <div>
+    <Sidebar />
+    <DevOnly>
+      <!-- this component will only be rendered during development -->
+      <LazyDebugBar />
+      <!-- be sure to test these using `nuxt preview` -->
+      <template #fallback>
+        <div><!-- empty div for flex.justify-between --></div>
+      </template>
+    </DevOnly>
+  </div>
+</template>
+```

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

@@ -0,0 +1,80 @@
+---
+title: "<NuxtClientFallback>"
+description: "Nuxt provides the <NuxtClientFallback> component to render its content on the client if any of its children trigger an error in SSR"
+links:
+  - label: Source (client)
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/components/client-fallback.client.ts
+    size: xs
+  - label: Source (server)
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/components/client-fallback.server.ts
+    size: xs
+---
+
+Nuxt provides the `<NuxtClientFallback>` component to render its content on the client if any of its children trigger an error in SSR.
+
+::note{to="/docs/guide/going-further/experimental-features#clientfallback"}
+This component is experimental and in order to use it you must enable the `experimental.clientFallback` option in your `nuxt.config`.
+::
+
+```vue [pages/example.vue]
+<template>
+  <div>
+    <Sidebar />
+    <!-- this component will be rendered on client-side -->
+    <NuxtClientFallback fallback-tag="span">
+      <Comments />
+      <BrokeInSSR />
+    </NuxtClientFallback>
+  </div>
+</template>
+```
+
+## Events
+
+- `@ssr-error`: Event emitted when a child triggers an error in SSR. Note that this will only be triggered on the server.
+
+  ```vue
+  <template>
+    <NuxtClientFallback @ssr-error="logSomeError">
+      <!-- ... -->
+    </NuxtClientFallback>
+  </template>
+  ```
+
+## Props
+
+- `placeholderTag` | `fallbackTag`: Specify a fallback tag to be rendered if the slot fails to render on the server.
+  - **type**: `string`
+  - **default**: `div`
+- `placeholder` | `fallback`: Specify fallback content to be rendered if the slot fails to render.
+  - **type**: `string`
+- `keepFallback`: Keep the fallback content if it failed to render server-side.
+  - **type**: `boolean`
+  - **default**: `false`
+
+```vue
+  <template>
+    <!-- render <span>Hello world</span> server-side if the default slot fails to render -->
+    <NuxtClientFallback fallback-tag="span" fallback="Hello world">
+      <BrokeInSsr />
+    </NuxtClientFallback>
+  </template>
+```
+
+## Slots
+
+- `#fallback`: specify content to be displayed server-side if the slot fails to render.
+
+```vue
+<template>
+  <NuxtClientFallback>
+    <!-- ... -->
+    <template #fallback>
+      <!-- this will be rendered on server side if the default slot fails to render in ssr -->
+      <p>Hello world</p>
+    </template>
+  </NuxtClientFallback>
+</template>
+```

package/3.api/1.components/10.nuxt-picture.md

@@ -0,0 +1,27 @@
+---
+title: "<NuxtPicture>"
+description: "Nuxt provides a <NuxtPicture> component to handle automatic image optimization."
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/image/blob/main/src/runtime/components/NuxtPicture.vue
+    size: xs
+---
+
+`<NuxtPicture>` is a drop-in replacement for the native `<picture>` tag.
+
+Usage of `<NuxtPicture>` is almost identical to [`<NuxtImg>`](/docs/api/components/nuxt-img) but it also allows serving modern formats like `webp` when possible.
+
+Learn more about the [`<picture>` tag on MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/picture).
+
+## Setup
+
+In order to use `<NuxtPicture>` you should install and enable the Nuxt Image module:
+
+```bash [Terminal]
+npx nuxi@latest module add image
+```
+
+::read-more{to="https://image.nuxt.com/usage/nuxt-picture" target="_blank"}
+Read more about the `<NuxtPicture>` component.
+::

package/3.api/1.components/11.teleports.md

@@ -0,0 +1,40 @@
+---
+title: '<Teleport>'
+description: The <Teleport> component teleports a component to a different location in the DOM.
+---
+
+::warning
+The `to` target of [`<Teleport>`](https://vuejs.org/guide/built-ins/teleport.html) expects a CSS selector string or an actual DOM node. Nuxt currently has SSR support for teleports to `#teleports` only, with client-side support for other targets using a `<ClientOnly>` wrapper.
+::
+
+## Body Teleport
+
+```vue
+<template>
+  <button @click="open = true">
+    Open Modal
+  </button>
+  <Teleport to="#teleports">
+    <div v-if="open" class="modal">
+      <p>Hello from the modal!</p>
+      <button @click="open = false">
+        Close
+      </button>
+    </div>
+  </Teleport>
+</template>
+```
+
+## Client-side Teleport
+
+```vue
+<template>
+  <ClientOnly>
+    <Teleport to="#some-selector">
+      <!-- content -->
+    </Teleport>
+  </ClientOnly>
+</template>
+```
+
+:link-example{to="/docs/examples/advanced/teleport"}