@nuxt/docs 0.0.0 → 3.17.1

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

@@ -0,0 +1,546 @@
+---
+title: server
+head.title: 'server/'
+description: The server/ directory is used to register API and server handlers to your application.
+navigation.icon: i-lucide-folder
+---
+
+Nuxt automatically scans files inside these directories to register API and server handlers with Hot Module Replacement (HMR) support.
+
+```bash [Directory structure]
+-| server/
+---| api/
+-----| hello.ts      # /api/hello
+---| routes/
+-----| bonjour.ts    # /bonjour
+---| middleware/
+-----| log.ts        # log all requests
+```
+
+Each file should export a default function defined with `defineEventHandler()` or `eventHandler()` (alias).
+
+The handler can directly return JSON data, a `Promise`, or use `event.node.res.end()` to send a response.
+
+```ts twoslash [server/api/hello.ts]
+export default defineEventHandler((event) => {
+  return {
+    hello: 'world'
+  }
+})
+```
+
+You can now universally call this API in your pages and components:
+
+```vue [pages/index.vue]
+<script setup lang="ts">
+const { data } = await useFetch('/api/hello')
+</script>
+
+<template>
+  <pre>{{ data }}</pre>
+</template>
+```
+
+## Server Routes
+
+Files inside the `~/server/api` are automatically prefixed with `/api` in their route.
+
+:video-accordion{title="Watch a video from Vue School on API routes" videoId="761468863" platform="vimeo"}
+
+To add server routes without `/api` prefix, put them into `~/server/routes` directory.
+
+**Example:**
+
+```ts [server/routes/hello.ts]
+export default defineEventHandler(() => 'Hello World!')
+```
+
+Given the example above, the `/hello` route will be accessible at <http://localhost:3000/hello>.
+
+::note
+Note that currently server routes do not support the full functionality of dynamic routes as [pages](/docs/guide/directory-structure/pages#dynamic-routes) do.
+::
+
+## Server Middleware
+
+Nuxt will automatically read in any file in the `~/server/middleware` to create server middleware for your project.
+
+Middleware handlers will run on every request before any other server route to add or check headers, log requests, or extend the event's request object.
+
+::note
+Middleware handlers should not return anything (nor close or respond to the request) and only inspect or extend the request context or throw an error.
+::
+
+**Examples:**
+
+```ts [server/middleware/log.ts]
+export default defineEventHandler((event) => {
+  console.log('New request: ' + getRequestURL(event))
+})
+```
+
+```ts [server/middleware/auth.ts]
+export default defineEventHandler((event) => {
+  event.context.auth = { user: 123 }
+})
+```
+
+## Server Plugins
+
+Nuxt will automatically read any files in the `~/server/plugins` directory and register them as Nitro plugins. This allows extending Nitro's runtime behavior and hooking into lifecycle events.
+
+**Example:**
+
+```ts [server/plugins/nitroPlugin.ts]
+export default defineNitroPlugin((nitroApp) => {
+  console.log('Nitro plugin', nitroApp)
+})
+```
+
+:read-more{to="https://nitro.unjs.io/guide/plugins" title="Nitro Plugins" target="_blank"}
+
+## Server Utilities
+
+Server routes are powered by [unjs/h3](https://github.com/unjs/h3) which comes with a handy set of helpers.
+
+:read-more{to="https://www.jsdocs.io/package/h3#package-index-functions" title="Available H3 Request Helpers" target="_blank"}
+
+You can add more helpers yourself inside the `~/server/utils` directory.
+
+For example, you can define a custom handler utility that wraps the original handler and performs additional operations before returning the final response.
+
+**Example:**
+
+```ts [server/utils/handler.ts]
+import type { EventHandler, EventHandlerRequest } from 'h3'
+
+export const defineWrappedResponseHandler = <T extends EventHandlerRequest, D> (
+  handler: EventHandler<T, D>
+): EventHandler<T, D> =>
+  defineEventHandler<T>(async event => {
+    try {
+      // do something before the route handler
+      const response = await handler(event)
+      // do something after the route handler
+      return { response }
+    } catch (err) {
+      // Error handling
+      return { err }
+    }
+  })
+```
+
+## Server Types
+
+::tip
+This feature is available from Nuxt >= 3.5
+::
+
+To improve clarity within your IDE between the auto-imports from 'nitro' and 'vue', you can add a `~/server/tsconfig.json` with the following content:
+
+```json [server/tsconfig.json]
+{
+  "extends": "../.nuxt/tsconfig.server.json"
+}
+```
+
+Currently, these values won't be respected when type checking ([`nuxi typecheck`](/docs/api/commands/typecheck)), but you should get better type hints in your IDE.
+
+## Recipes
+
+### Route Parameters
+
+Server routes can use dynamic parameters within brackets in the file name like `/api/hello/[name].ts` and be accessed via `event.context.params`.
+
+```ts [server/api/hello/[name\\].ts]
+export default defineEventHandler((event) => {
+  const name = getRouterParam(event, 'name')
+
+  return `Hello, ${name}!`
+})
+```
+
+::tip{to="https://h3.unjs.io/examples/validate-data#validate-params"}
+Alternatively, use `getValidatedRouterParams` with a schema validator such as Zod for runtime and type safety.
+::
+
+You can now universally call this API on `/api/hello/nuxt` and get `Hello, nuxt!`.
+
+### Matching HTTP Method
+
+Handle file names can be suffixed with `.get`, `.post`, `.put`, `.delete`, ... to match request's [HTTP Method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods).
+
+```ts [server/api/test.get.ts]
+export default defineEventHandler(() => 'Test get handler')
+```
+
+```ts [server/api/test.post.ts]
+export default defineEventHandler(() => 'Test post handler')
+```
+
+Given the example above, fetching `/test` with:
+
+- **GET** method: Returns `Test get handler`
+- **POST** method: Returns `Test post handler`
+- Any other method: Returns 405 error
+
+You can also use `index.[method].ts` inside a directory for structuring your code differently, this is useful to create API namespaces.
+
+::code-group
+```ts [server/api/foo/index.get.ts]
+export default defineEventHandler((event) => {
+  // handle GET requests for the `api/foo` endpoint
+})
+```
+```ts [server/api/foo/index.post.ts]
+export default defineEventHandler((event) => {
+  // handle POST requests for the `api/foo` endpoint
+})
+```
+```ts [server/api/foo/bar.get.ts]
+export default defineEventHandler((event) => {
+  // handle GET requests for the `api/foo/bar` endpoint
+})
+```
+::
+
+### Catch-all Route
+
+Catch-all routes are helpful for fallback route handling.
+
+For example, creating a file named `~/server/api/foo/[...].ts` will register a catch-all route for all requests that do not match any route handler, such as `/api/foo/bar/baz`.
+
+```ts [server/api/foo/[...\\].ts]
+export default defineEventHandler((event) => {
+  // event.context.path to get the route path: '/api/foo/bar/baz'
+  // event.context.params._ to get the route segment: 'bar/baz'
+  return `Default foo handler`
+})
+```
+
+You can set a name for the catch-all route by using `~/server/api/foo/[...slug].ts` and access it via `event.context.params.slug`.
+
+```ts [server/api/foo/[...slug\\].ts]
+export default defineEventHandler((event) => {
+  // event.context.params.slug to get the route segment: 'bar/baz'
+  return `Default foo handler`
+})
+```
+
+### Body Handling
+
+```ts [server/api/submit.post.ts]
+export default defineEventHandler(async (event) => {
+  const body = await readBody(event)
+  return { body }
+})
+```
+
+::tip{to="https://unjs.io/blog/2023-08-15-h3-towards-the-edge-of-the-web#runtime-type-safe-request-utils"}
+Alternatively, use `readValidatedBody` with a schema validator such as Zod for runtime and type safety.
+::
+
+You can now universally call this API using:
+
+```vue [app.vue]
+<script setup lang="ts">
+async function submit() {
+  const { body } = await $fetch('/api/submit', {
+    method: 'post',
+    body: { test: 123 }
+  })
+}
+</script>
+```
+
+::note
+We are using `submit.post.ts` in the filename only to match requests with `POST` method that can accept the request body. When using `readBody` within a GET request, `readBody` will throw a `405 Method Not Allowed` HTTP error.
+::
+
+### Query Parameters
+
+Sample query `/api/query?foo=bar&baz=qux`
+
+```ts [server/api/query.get.ts]
+export default defineEventHandler((event) => {
+  const query = getQuery(event)
+
+  return { a: query.foo, b: query.baz }
+})
+```
+
+::tip{to="https://unjs.io/blog/2023-08-15-h3-towards-the-edge-of-the-web#runtime-type-safe-request-utils"}
+Alternatively, use `getValidatedQuery` with a schema validator such as Zod for runtime and type safety.
+::
+
+### Error Handling
+
+If no errors are thrown, a status code of `200 OK` will be returned.
+
+Any uncaught errors will return a `500 Internal Server Error` HTTP Error.
+
+To return other error codes, throw an exception with [`createError`](/docs/api/utils/create-error):
+
+```ts [server/api/validation/[id\\].ts]
+export default defineEventHandler((event) => {
+  const id = parseInt(event.context.params.id) as number
+
+  if (!Number.isInteger(id)) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: 'ID should be an integer',
+    })
+  }
+  return 'All good'
+})
+```
+
+### Status Codes
+
+To return other status codes, use the [`setResponseStatus`](/docs/api/utils/set-response-status) utility.
+
+For example, to return `202 Accepted`
+
+```ts [server/api/validation/[id\\].ts]
+export default defineEventHandler((event) => {
+  setResponseStatus(event, 202)
+})
+```
+
+### Runtime Config
+
+::code-group
+```ts [server/api/foo.ts]
+export default defineEventHandler(async (event) => {
+  const config = useRuntimeConfig(event)
+
+  const repo = await $fetch('https://api.github.com/repos/nuxt/nuxt', {
+    headers: {
+      Authorization: `token ${config.githubToken}`
+    }
+  })
+
+  return repo
+})
+```
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  runtimeConfig: {
+    githubToken: ''
+  }
+})
+```
+```ini [.env]
+NUXT_GITHUB_TOKEN='<my-super-token>'
+```
+::
+
+::note
+Giving the `event` as argument to `useRuntimeConfig` is optional, but it is recommended to pass it to get the runtime config overwritten by [environment variables](/docs/guide/going-further/runtime-config#environment-variables) at runtime for server routes.
+::
+
+### Request Cookies
+
+```ts [server/api/cookies.ts]
+export default defineEventHandler((event) => {
+  const cookies = parseCookies(event)
+
+  return { cookies }
+})
+```
+
+### Forwarding Context & Headers
+
+By default, neither the headers from the incoming request nor the request context are forwarded when
+making fetch requests in server routes. You can use `event.$fetch` to forward the request context and headers when making fetch requests in server routes.
+
+```ts [server/api/forward.ts]
+export default defineEventHandler((event) => {
+  return event.$fetch('/api/forwarded')
+})
+```
+
+::note
+Headers that are **not meant to be forwarded** will **not be included** in the request. These headers include, for example:
+`transfer-encoding`, `connection`, `keep-alive`, `upgrade`, `expect`, `host`, `accept`
+::
+
+### Awaiting Promises After Response
+
+When handling server requests, you might need to perform asynchronous tasks that shouldn't block the response to the client (for example, caching and logging). You can use `event.waitUntil` to await a promise in the background without delaying the response.
+
+The `event.waitUntil` method accepts a promise that will be awaited before the handler terminates, ensuring the task is completed even if the server would otherwise terminate the handler right after the response is sent. This integrates with runtime providers to leverage their native capabilities for handling asynchronous operations after the response is sent.
+
+```ts [server/api/background-task.ts]
+const timeConsumingBackgroundTask = async () => {
+  await new Promise((resolve) => setTimeout(resolve, 1000))
+};
+
+export default eventHandler((event) => {
+  // schedule a background task without blocking the response
+  event.waitUntil(timeConsumingBackgroundTask())
+
+  // immediately send the response to the client
+  return 'done'
+});
+```
+
+## Advanced Usage
+
+### Nitro Config
+
+You can use `nitro` key in `nuxt.config` to directly set [Nitro configuration](https://nitro.unjs.io/config).
+
+::warning
+This is an advanced option. Custom config can affect production deployments, as the configuration interface might change over time when Nitro is upgraded in semver-minor versions of Nuxt.
+::
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  // https://nitro.unjs.io/config
+  nitro: {}
+})
+```
+
+:read-more{to="/docs/guide/concepts/server-engine"}
+
+### Nested Router
+
+```ts [server/api/hello/[...slug\\].ts]
+import { createRouter, defineEventHandler, useBase } from 'h3'
+
+const router = createRouter()
+
+router.get('/test', defineEventHandler(() => 'Hello World'))
+
+export default useBase('/api/hello', router.handler)
+```
+
+### Sending Streams
+
+::tip
+This is an experimental feature and is available in all environments.
+::
+
+```ts [server/api/foo.get.ts]
+import fs from 'node:fs'
+import { sendStream } from 'h3'
+
+export default defineEventHandler((event) => {
+  return sendStream(event, fs.createReadStream('/path/to/file'))
+})
+```
+
+### Sending Redirect
+
+```ts [server/api/foo.get.ts]
+export default defineEventHandler(async (event) => {
+  await sendRedirect(event, '/path/redirect/to', 302)
+})
+```
+
+### Legacy Handler or Middleware
+
+```ts [server/api/legacy.ts]
+export default fromNodeMiddleware((req, res) => {
+  res.end('Legacy handler')
+})
+```
+
+::important
+Legacy support is possible using [unjs/h3](https://github.com/unjs/h3), but it is advised to avoid legacy handlers as much as you can.
+::
+
+```ts [server/middleware/legacy.ts]
+export default fromNodeMiddleware((req, res, next) => {
+  console.log('Legacy middleware')
+  next()
+})
+```
+
+::warning
+Never combine `next()` callback with a legacy middleware that is `async` or returns a `Promise`.
+::
+
+### Server Storage
+
+Nitro provides a cross-platform [storage layer](https://nitro.unjs.io/guide/storage). In order to configure additional storage mount points, you can use `nitro.storage`, or [server plugins](#server-plugins).
+
+**Example of adding a Redis storage:**
+
+Using `nitro.storage`:
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  nitro: {
+    storage: {
+      redis: {
+        driver: 'redis',
+        /* redis connector options */
+        port: 6379, // Redis port
+        host: "127.0.0.1", // Redis host
+        username: "", // needs Redis >= 6
+        password: "",
+        db: 0, // Defaults to 0
+        tls: {} // tls/ssl
+      }
+    }
+  }
+})
+```
+
+Then in your API handler:
+
+```ts [server/api/storage/test.ts]
+export default defineEventHandler(async (event) => {
+  // List all keys with
+  const keys = await useStorage('redis').getKeys()
+
+  // Set a key with
+  await useStorage('redis').setItem('foo', 'bar')
+
+  // Remove a key with
+  await useStorage('redis').removeItem('foo')
+
+  return {}
+})
+```
+
+::read-more{to="https://nitro.unjs.io/guide/storage" target="_blank"}
+Read more about Nitro Storage Layer.
+::
+
+Alternatively, you can create a storage mount point using a server plugin and runtime config:
+
+::code-group
+```ts [server/plugins/storage.ts]
+import redisDriver from 'unstorage/drivers/redis'
+
+export default defineNitroPlugin(() => {
+  const storage = useStorage()
+
+  // Dynamically pass in credentials from runtime configuration, or other sources
+  const driver = redisDriver({
+      base: 'redis',
+      host: useRuntimeConfig().redis.host,
+      port: useRuntimeConfig().redis.port,
+      /* other redis connector options */
+    })
+
+  // Mount driver
+  storage.mount('redis', driver)
+})
+```
+
+``` ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  runtimeConfig: {
+    redis: { // Default values
+      host: '',
+      port: 0,
+      /* other redis connector options */
+    }
+  }
+})
+```
+::

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

@@ -0,0 +1,104 @@
+---
+title: 'shared'
+head.title: 'shared/'
+description: 'Use the shared/ directory to share functionality between the Vue app and the Nitro server.'
+navigation.icon: i-lucide-folder
+---
+
+The `shared/` directory allows you to share code that can be used in both the Vue app and the Nitro server.
+
+::note
+The `shared/` directory is available in Nuxt v3.14+.
+::
+
+::important
+Code in the `shared/` directory cannot import any Vue or Nitro code.
+::
+
+::warning
+Auto-imports are not enabled by default in Nuxt v3 to prevent breaking changes in existing projects.
+
+To use these auto-imported utils and types, you must first [set `future.compatibilityVersion: 4` in your `nuxt.config.ts`](/docs/getting-started/upgrade#opting-in-to-nuxt-4).
+::
+
+:video-accordion{title="Watch a video from Vue School on sharing utils and types between app and server" videoId="nnAR-MO3q5M"}
+
+## Usage
+
+**Method 1:** Named export
+
+```ts twoslash [shared/utils/capitalize.ts]
+export const capitalize = (input: string) => {
+  return input[0] ? input[0].toUpperCase() + input.slice(1) : ''
+}
+```
+
+**Method 2:** Default export
+
+```ts twoslash [shared/utils/capitalize.ts]
+export default function (input: string) {
+  return input[0] ? input[0].toUpperCase() + input.slice(1) : ''
+}
+```
+
+You can now use [auto-imported](/docs/guide/directory-structure/shared#auto-imports) utilities in your Nuxt app and `server/` directory.
+
+```vue [app.vue]
+<script setup lang="ts">
+const hello = capitalize('hello')
+</script>
+
+<template>
+  <div>
+    {{ hello }}
+  </div>
+</template>
+```
+
+```ts [server/api/hello.get.ts]
+export default defineEventHandler((event) => {
+  return {
+    hello: capitalize('hello')
+  }
+})
+```
+
+## How Files Are Scanned
+
+Only files in the `shared/utils/` and `shared/types/` directories will be auto-imported. Files nested within subdirectories of these directories will not be auto-imported unless you add these directories to `imports.dirs` and `nitro.imports.dirs`.
+
+::tip
+The way `shared/utils` and `shared/types` auto-imports work and are scanned is identical to the [`composables/`](/docs/guide/directory-structure/composables) and [`utils/`](/docs/guide/directory-structure/utils) directories.
+::
+
+:read-more{to="/docs/guide/directory-structure/composables#how-files-are-scanned"}
+
+```bash [Directory Structure]
+-| shared/
+---| capitalize.ts        # Not auto-imported
+---| formatters
+-----| lower.ts           # Not auto-imported
+---| utils/
+-----| lower.ts           # Auto-imported
+-----| formatters
+-------| upper.ts         # Not auto-imported
+---| types/
+-----| bar.d.ts           # Auto-imported
+```
+
+Any other files you create in the `shared/` folder must be manually imported using the `#shared` alias (automatically configured by Nuxt):
+
+```ts
+// For files directly in the shared directory
+import capitalize from '#shared/capitalize'
+
+// For files in nested directories
+import lower from '#shared/formatters/lower'
+
+// For files nested in a folder within utils
+import upper from '#shared/utils/formatters/upper'
+```
+
+This alias ensures consistent imports across your application, regardless of the importing file's location.
+
+:read-more{to="/docs/guide/concepts/auto-imports"}

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

@@ -0,0 +1,49 @@
+---
+title: 'utils'
+head.title: 'utils/'
+description: Use the utils/ directory to auto-import your utility functions throughout your application.
+navigation.icon: i-lucide-folder
+---
+
+The main purpose of the [`utils/` directory](/docs/guide/directory-structure/utils) is to allow a semantic distinction between your Vue composables and other auto-imported utility functions.
+
+## Usage
+
+**Method 1:** Using named export
+
+```ts twoslash [utils/index.ts]
+export const { format: formatNumber } = Intl.NumberFormat('en-GB', {
+  notation: 'compact',
+  maximumFractionDigits: 1
+})
+```
+
+**Method 2:** Using default export
+
+```ts twoslash [utils/random-entry.ts or utils/randomEntry.ts]
+// It will be available as randomEntry() (camelCase of file name without extension)
+export default function (arr: Array<any>) {
+  return arr[Math.floor(Math.random() * arr.length)]
+}
+```
+
+You can now use auto imported utility functions in `.js`, `.ts` and `.vue` files
+
+```vue [app.vue]
+<template>
+  <p>{{ formatNumber(1234) }}</p>
+</template>
+```
+
+:read-more{to="/docs/guide/concepts/auto-imports"}
+
+:link-example{to="/docs/examples/features/auto-imports"}
+
+::tip
+The way `utils/` auto-imports work and are scanned is identical to the [`composables/`](/docs/guide/directory-structure/composables) directory.
+::
+
+::important
+These utils are only available within the Vue part of your app. :br
+Only `server/utils` are auto-imported in the [`server/`](/docs/guide/directory-structure/server#server-utilities) directory.
+::