@nuxt/docs 3.17.1 → 3.17.3

package/3.api/5.kit/11.nitro.md

@@ -12,83 +12,67 @@ Nitro is an open source TypeScript framework to build ultra-fast web servers. Nu
 
 ## `addServerHandler`
 
-Adds a nitro server handler. Use it if you want to create server middleware or custom route.
+Adds a Nitro server handler. Use this if you want to create server middleware or a custom route.
+
+### Usage
+
+```ts twoslash
+import { createResolver, defineNuxtModule, addServerHandler } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup(options) {
+    const { resolve } = createResolver(import.meta.url)
+
+    addServerHandler({
+      route: '/robots.txt',
+      handler: resolve('./runtime/robots.get')
+    })
+  }
+})
+```
 
 ### Type
 
 ```ts
 function addServerHandler (handler: NitroEventHandler): void
-
-export interface NitroEventHandler {
-  handler: string;
-  route?: string;
-  middleware?: boolean;
-  lazy?: boolean;
-  method?: string;
-}
 ```
 
 ### Parameters
 
-#### `handler`
-
-**Type**: `NitroEventHandler`
-
-**Required**: `true`
-
-A handler object with the following properties:
-
-- `handler` (required)
-
-  **Type**: `string`
-
-  Path to event handler.
-
-- `route` (optional)
-
-  **Type**: `string`
+**handler**: A handler object with the following properties:
 
-  Path prefix or route. If an empty string used, will be used as a middleware.
+| Property    | Type            | Required | Description                                                                                                     |
+| ----------- | --------------  | -------- | --------------------------------------------------------------------------------------------------------------- |
+| `handler`   | `string`        | `true`   | Path to event handler.                                                                                          |
+| `route`     | `string`        | `false`  | Path prefix or route. If an empty string used, will be used as a middleware.                                    |
+| `middleware`| `boolean`       | `false`  | Specifies this is a middleware handler. Middleware are called on every route and should normally return nothing to pass to the next handlers. |
+| `lazy`      | `boolean`       | `false`  | Use lazy loading to import the handler. This is useful when you only want to load the handler on demand.        |
+| `method`    | `string`        | `false`  | Router method matcher. If handler name contains method name, it will be used as a default value.                |
 
-- `middleware` (optional)
-
-  **Type**: `boolean`
-
-  Specifies this is a middleware handler. Middleware are called on every route and should normally return nothing to pass to the next handlers.
-
-- `lazy` (optional)
-
-  **Type**: `boolean`
-
-  Use lazy loading to import handler.
-
-- `method` (optional)
-
-  **Type**: `string`
+### Examples
 
-  Router method matcher. If handler name contains method name, it will be used as a default value.
+#### Basic Usage
 
-### Examples
+You can use `addServerHandler` to add a server handler from your module.
 
 ::code-group
 
-```ts [module.ts]
-// https://github.com/nuxt-modules/robots
+```ts twoslash [module.ts]
 import { createResolver, defineNuxtModule, addServerHandler } from '@nuxt/kit'
 
 export default defineNuxtModule({
   setup(options) {
-    const resolver = createResolver(import.meta.url)
+    const { resolve } = createResolver(import.meta.url)
 
     addServerHandler({
       route: '/robots.txt',
-      handler: resolver.resolve('./runtime/robots.get')
+      handler: resolve('./runtime/robots.get')
     })
   }
 })
 ```
 
-```ts [runtime/robots.get.ts]
+```ts twoslash [runtime/robots.get.ts]
 export default defineEventHandler(() => {
   return {
     body: `User-agent: *\nDisallow: /`
@@ -98,75 +82,67 @@ export default defineEventHandler(() => {
 
 ::
 
-## `addDevServerHandler`
+When you access `/robots.txt`, it will return the following response:
 
-Adds a nitro server handler to be used only in development mode. This handler will be excluded from production build.
-
-### Type
-
-```ts
-function addDevServerHandler (handler: NitroDevEventHandler): void
-
-export interface NitroDevEventHandler {
-  handler: EventHandler;
-  route?: string;
-}
+```txt
+User-agent: *
+Disallow: /
 ```
 
-### Parameters
-
-#### `handler`
-
-**Type**: `NitroEventHandler`
-
-**Required**: `true`
-
-A handler object with the following properties:
-
-- `handler` (required)
-
-  **Type**: `string`
-
-  The event handler.
-
-- `route` (optional)
-
-  **Type**: `string`
-
-  Path prefix or route. If an empty string used, will be used as a middleware.
+## `addDevServerHandler`
 
-### Examples
+Adds a Nitro server handler to be used only in development mode. This handler will be excluded from production build.
 
-::code-group
+### Usage
 
-```ts [module.ts]
+```ts twoslash
+import { defineEventHandler } from 'h3'
 import { createResolver, defineNuxtModule, addDevServerHandler } from '@nuxt/kit'
 
 export default defineNuxtModule({
   setup() {
-    const resolver = createResolver(import.meta.url)
-
     addDevServerHandler({
-      handler: () => {
+      handler: defineEventHandler(() => {
         return {
           body: `Response generated at ${new Date().toISOString()}`
         }
-      },
+      }),
       route: '/_handler'
     })
   }
 })
 ```
 
-::
+### Type
+
+```ts twoslash
+// @errors: 2391
+import type { NitroDevEventHandler } from 'nitropack'
+// ---cut---
+function addDevServerHandler (handler: NitroDevEventHandler): void
+```
+
+### Parameters
+
+**handler**: A handler object with the following properties:
+
+| Property    | Type            | Required | Description                                                                                                     |
+| ----------- | --------------  | -------- | --------------------------------------------------------------------------------------------------------------- |
+| `handler`   | `EventHandler`  | `true`   | Event handler.                                                                                                  |
+| `route`     | `string`        | `false`  | Path prefix or route. If an empty string used, will be used as a middleware.                                    |
+
+### Examples
+
+#### Basic Usage
+
+In some cases, you may want to create a server handler specifically for development purposes, such as a Tailwind config viewer.
 
 ```ts
-// https://github.com/nuxt-modules/tailwindcss
 import { joinURL } from 'ufo'
 import { defineNuxtModule, addDevServerHandler } from '@nuxt/kit'
 
 export default defineNuxtModule({
-  async setup(options) {
+  async setup(options, nuxt) {
     const route = joinURL(nuxt.options.app?.baseURL, '/_tailwind')
 
     // @ts-ignore
@@ -190,29 +166,10 @@ You can call `useNitro()` only after `ready` hook.
 Changes to the Nitro instance configuration are not applied.
 ::
 
-### Type
-
-```ts
-function useNitro (): Nitro
-
-export interface Nitro {
-  options: NitroOptions;
-  scannedHandlers: NitroEventHandler[];
-  vfs: Record<string, string>;
-  hooks: Hookable<NitroHooks>;
-  unimport?: Unimport;
-  logger: ConsolaInstance;
-  storage: Storage;
-  close: () => Promise<void>;
-  updateConfig: (config: NitroDynamicConfig) => void | Promise<void>;
-}
-```
-
-### Examples
+### Usage
 
 ```ts
-// https://github.com/nuxt/nuxt/blob/4e05650cde31ca73be4d14b1f0d23c7854008749/packages/nuxt/src/core/nuxt.ts#L404
-import { defineNuxtModule, useNitro, addPlugin, createResolver } from '@nuxt/kit'
+import { defineNuxtModule, useNitro } from '@nuxt/kit'
 
 export default defineNuxtModule({
   setup(options, nuxt) {
@@ -220,29 +177,39 @@ export default defineNuxtModule({
 
     nuxt.hook('ready', () => {
       const nitro = useNitro()
-      if (nitro.options.static && nuxt.options.experimental.payloadExtraction === undefined) {
-        console.warn('Using experimental payload extraction for full-static output. You can opt-out by setting `experimental.payloadExtraction` to `false`.')
-        nuxt.options.experimental.payloadExtraction = true
-      }
-      nitro.options.replace['process.env.NUXT_PAYLOAD_EXTRACTION'] = String(!!nuxt.options.experimental.payloadExtraction)
-      nitro.options._config.replace!['process.env.NUXT_PAYLOAD_EXTRACTION'] = String(!!nuxt.options.experimental.payloadExtraction)
-
-      if (!nuxt.options.dev && nuxt.options.experimental.payloadExtraction) {
-        addPlugin(resolver.resolve(nuxt.options.appDir, 'plugins/payload.client'))
-      }
+      // Do something with Nitro instance
     })
   }
 })
 ```
 
+### Type
+
+```ts
+function useNitro (): Nitro
+```
+
 ## `addServerPlugin`
 
 Add plugin to extend Nitro's runtime behavior.
 
 ::tip
-You can read more about Nitro plugins in the [Nitro documentation](https://nitro.unjs.io/guide/plugins).
+You can read more about Nitro plugins in the [Nitro documentation](https://nitro.build/guide/plugins).
 ::
 
+### Usage
+
+```ts twoslash
+import { createResolver, defineNuxtModule, addServerPlugin } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup() {
+    const { resolve } = createResolver(import.meta.url)
+    addServerPlugin(resolve('./runtime/plugin.ts'))
+  }
+})
+```
+
 ### Type
 
 ```ts
@@ -251,13 +218,9 @@ function addServerPlugin (plugin: string): void
 
 ### Parameters
 
-#### `plugin`
-
-**Type**: `string`
-
-**Required**: `true`
-
-Path to the plugin. The plugin must export a function that accepts Nitro instance as an argument.
+| Property    | Type            | Required | Description                                                                                                     |
+| ----------- | --------------  | -------- | --------------------------------------------------------------------------------------------------------------- |
+| `plugin`    | `string`        | `true`   | Path to the plugin. The plugin must export a default function that accepts the Nitro instance as an argument.   |
 
 ### Examples
 
@@ -268,8 +231,8 @@ import { createResolver, defineNuxtModule, addServerPlugin } from '@nuxt/kit'
 
 export default defineNuxtModule({
   setup() {
-    const resolver = createResolver(import.meta.url)
-    addServerPlugin(resolver.resolve('./runtime/plugin.ts'))
+    const { resolve } = createResolver(import.meta.url)
+    addServerPlugin(resolve('./runtime/plugin.ts'))
   }
 })
 ```
@@ -296,23 +259,7 @@ export default defineNitroPlugin((nitroApp) => {
 
 Add routes to be prerendered to Nitro.
 
-### Type
-
-```ts
-function function addPrerenderRoutes (routes: string | string[]): void
-```
-
-### Parameters
-
-#### `routes`
-
-**Type**: `string | string[]`
-
-**Required**: `true`
-
-A route or an array of routes to prerender.
-
-### Examples
+### Usage
 
 ```ts
 import { defineNuxtModule, addPrerenderRoutes } from '@nuxt/kit'
@@ -334,10 +281,39 @@ export default defineNuxtModule({
 })
 ```
 
+### Type
+
+```ts
+function addPrerenderRoutes (routes: string | string[]): void
+```
+
+### Parameters
+
+| Property    | Type                            | Required | Description                                    |
+| ----------- | ------------------------------- | -------- | ---------------------------------------------- |
+| `routes`    | `string \| string[]`{lang="ts"} | `true`   | A route or an array of routes to prerender.    |
+
 ## `addServerImportsDir`
 
 Add a directory to be scanned for auto-imports by Nitro.
 
+### Usage
+
+```ts twoslash
+import { defineNuxtModule, createResolver, addServerImportsDir } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  meta: {
+    name: 'my-module',
+    configKey: 'myModule',
+  },
+  setup(options) {
+    const { resolve } = createResolver(import.meta.url)
+    addServerImportsDir(resolve('./runtime/server/composables'))
+  }
+})
+```
+
 ### Type
 
 ```ts
@@ -346,17 +322,18 @@ function addServerImportsDir (dirs: string | string[], opts: { prepend?: boolean
 
 ### Parameters
 
-#### `dirs`
-
-**Type**: `string | string[]`
+| Property    | Type                            | Required | Description                                    |
+| ----------- | ------------------------------- | -------- | ---------------------------------------------- |
+| `dirs`      | `string \| string[]`{lang="ts"} | `true`   | A directory or an array of directories to register to be scanned by Nitro. |
+| `opts`      | `{ prepend?: boolean }`         | `false`  | Options for the import directory. If `prepend` is `true`, the directory is added to the beginning of the scan list. |
 
-**Required**: `true`
+### Examples
 
-A directory or an array of directories to register to be scanned by Nitro
+You can use `addServerImportsDir` to add a directory to be scanned by Nitro. This is useful when you want Nitro to auto-import functions from a custom server directory.
 
-### Examples
+::code-group
 
-```ts
+```ts twoslash [module.ts]
 import { defineNuxtModule, createResolver, addServerImportsDir } from '@nuxt/kit'
 
 export default defineNuxtModule({
@@ -365,17 +342,58 @@ export default defineNuxtModule({
     configKey: 'myModule',
   },
   setup(options) {
-    const resolver = createResolver(import.meta.url)
-    addServerImportsDir(resolver.resolve('./runtime/server/utils'))
+    const { resolve } = createResolver(import.meta.url)
+    addServerImportsDir(resolve('./runtime/server/composables'))
   }
 })
 ```
 
+```ts twoslash [runtime/server/composables/index.ts]
+export function useApiSecret() {
+  const { apiSecret } = useRuntimeConfig()
+  return apiSecret
+}
+```
+
+::
+
+You can then use the `useApiSecret` function in your server code:
+
+```ts twoslash [runtime/server/api/hello.ts]
+const useApiSecret = (): string => ''
+// ---cut---
+export default defineEventHandler(() => {
+  const apiSecret = useApiSecret()
+  // Do something with the apiSecret
+})
+```
+
 ## `addServerScanDir`
 
 Add directories to be scanned by Nitro. It will check for subdirectories, which will be registered
 just like the `~/server` folder is.
 
+::note
+Only `~/server/api`, `~/server/routes`, `~/server/middleware`, and `~/server/utils` are scanned.
+::
+
+### Usage
+
+```ts twoslash
+import { defineNuxtModule, createResolver, addServerScanDir } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  meta: {
+    name: 'my-module',
+    configKey: 'myModule',
+  },
+  setup(options) {
+    const { resolve } = createResolver(import.meta.url)
+    addServerScanDir(resolve('./runtime/server'))
+  }
+})
+```
+
 ### Type
 
 ```ts
@@ -384,26 +402,47 @@ function addServerScanDir (dirs: string | string[], opts: { prepend?: boolean })
 
 ### Parameters
 
-#### `dirs`
-
-**Type**: `string | string[]`
+| Property    | Type                            | Required | Description                                    |
+| ----------- | ------------------------------- | -------- | ---------------------------------------------- |
+| `dirs`      | `string \| string[]`{lang="ts"} | `true`   | A directory or an array of directories to register to be scanned for by Nitro as server dirs. |
+| `opts`      | `{ prepend?: boolean }`         | `false`  | Options for the import directory. If `prepend` is `true`, the directory is added to the beginning of the scan list. |
 
-**Required**: `true`
+### Examples
 
-A directory or an array of directories to register to be scanned for by Nitro as server dirs.
+You can use `addServerScanDir` to add a directory to be scanned by Nitro. This is useful when you want to add a custom server directory.
 
-### Examples
+::code-group
 
-```ts
+```ts twoslash [module.ts]
 import { defineNuxtModule, createResolver, addServerScanDir } from '@nuxt/kit'
+
 export default defineNuxtModule({
   meta: {
     name: 'my-module',
     configKey: 'myModule',
   },
   setup(options) {
-    const resolver = createResolver(import.meta.url)
-    addServerScanDir(resolver.resolve('./runtime/server'))
+    const { resolve } = createResolver(import.meta.url)
+    addServerScanDir(resolve('./runtime/server'))
   }
 })
 ```
+
+```ts twoslash [runtime/server/utils/index.ts]
+export function hello() {
+  return 'Hello from server utils!'
+}
+```
+::
+
+You can then use the `hello` function in your server code.
+
+```ts twoslash [runtime/server/api/hello.ts]
+function hello() {
+  return 'Hello from server utils!'
+}
+// ---cut---
+export default defineEventHandler(() => {
+  return hello() // Hello from server utils!
+})
+```