@nuxt/docs 3.17.1 → 3.17.3

package/3.api/5.kit/10.runtime-config.md

@@ -22,6 +22,8 @@ function useRuntimeConfig (): Record<string, unknown>
 
 It is also possible to update runtime configuration. This will be merged with the existing runtime configuration, and if Nitro has already been initialized it will trigger an HMR event to reload the Nitro runtime config.
 
+### Type
+
 ```ts
 function updateRuntimeConfig (config: Record<string, unknown>): void | Promise<void>
 ```

package/3.api/5.kit/10.templates.md

@@ -12,105 +12,79 @@ Templates allows to generate extra files during development and build time. Thes
 
 ## `addTemplate`
 
-Renders given template during build into the project buildDir.
+Renders given template during build into the virtual file system, and optionally to disk in the project `buildDir`
 
-### Type
-
-```ts
-function addTemplate (template: NuxtTemplate | string): ResolvedNuxtTemplate
-
-interface NuxtTemplate {
-  src?: string
-  filename?: string
-  dst?: string
-  options?: Record<string, any>
-  getContents?: (data: Record<string, any>) => string | Promise<string>
-  write?: boolean
-}
-
-interface ResolvedNuxtTemplate {
-  src: string
-  filename: string
-  dst: string
-  options: Record<string, any>
-  getContents: (data: Record<string, any>) => string | Promise<string>
-  write: boolean
-  filename: string
-  dst: string
-}
-```
-
-### Parameters
-
-#### `template`
-
-**Type**: `NuxtTemplate | string`
-
-**Required**: `true`
-
-A template object or a string with the path to the template. If a string is provided, it will be converted to a template object with `src` set to the string value. If a template object is provided, it must have the following properties:
-
-- `src` (optional)
+### Usage
 
-  **Type**: `string`
-
-  Path to the template. If `src` is not provided, `getContents` must be provided instead.
-
-- `filename` (optional)
-
-  **Type**: `string`
-
-  Filename of the template. If `filename` is not provided, it will be generated from the `src` path. In this case, the `src` option is required.
-
-- `dst` (optional)
-
-  **Type**: `string`
+```ts twoslash
+import { addTemplate, defineNuxtModule } from '@nuxt/kit'
+import { defu } from 'defu'
 
-  Path to the destination file. If `dst` is not provided, it will be generated from the `filename` path and nuxt `buildDir` option.
+export default defineNuxtModule({
+  setup(options, nuxt) {
+    const globalMeta = defu(nuxt.options.app.head, {
+      charset: options.charset,
+      viewport: options.viewport
+    })
 
-- `options` (optional)
+    addTemplate({
+      filename: 'meta.config.mjs',
+      getContents: () => 'export default ' + JSON.stringify({ globalMeta, mixinKey: 'setup' })
+    })
+  }
+})
+```
 
-  **Type**: `Options`
+### Type
 
-  Options to pass to the template.
+```ts twoslash
+// @errors: 2391
+import type { NuxtTemplate, ResolvedNuxtTemplate } from '@nuxt/schema'
+// ---cut---
+function addTemplate (template: NuxtTemplate | string): ResolvedNuxtTemplate
+```
 
-- `getContents` (optional)
+### Parameters
 
-  **Type**: `(data: Options) => string | Promise<string>`
+**template**: A template object or a string with the path to the template. If a string is provided, it will be converted to a template object with `src` set to the string value. If a template object is provided, it must have the following properties:
 
-  A function that will be called with the `options` object. It should return a string or a promise that resolves to a string. If `src` is provided, this function will be ignored.
+| Property   | Type                                                                 | Required | Description                                                                                                     |
+| ---------- | -------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
+| `src`      | `string`                                                             | `false`  | Path to the template. If `src` is not provided, `getContents` must be provided instead.                         |
+| `filename` | `string`                                                             | `false`  | Filename of the template. If `filename` is not provided, it will be generated from the `src` path. In this case, the `src` option is required. |
+| `dst`      | `string`                                                             | `false`  | Path to the destination file. If `dst` is not provided, it will be generated from the `filename` path and nuxt `buildDir` option. |
+| `options`  | `Options`                                                           | `false`  | Options to pass to the template.                                                                                |
+| `getContents` | `(data: Options) => string \| Promise<string>`{lang="ts"} | `false`  | A function that will be called with the `options` object. It should return a string or a promise that resolves to a string. If `src` is provided, this function will be ignored. |
+| `write`    | `boolean`                                                            | `false`  | If set to `true`, the template will be written to the destination file. Otherwise, the template will be used only in virtual filesystem. |
 
-- `write` (optional)
-  
-  **Type**: `boolean`
+### Examples
 
-  If set to `true`, the template will be written to the destination file. Otherwise, the template will be used only in virtual filesystem.
+#### Creating a Virtual File for Runtime Plugin
 
-### Examples
+In this example, we merge an object inside a module and consume the result in a runtime plugin.
 
-::code-group
-  
-```ts [module.ts]
-// https://github.com/nuxt/bridge
+```ts twoslash [module.ts]
 import { addTemplate, defineNuxtModule } from '@nuxt/kit'
 import { defu } from 'defu'
 
 export default defineNuxtModule({
-  setup(options, nuxt) {
+  setup (options, nuxt) {
     const globalMeta = defu(nuxt.options.app.head, {
       charset: options.charset,
-      viewport: options.viewport
+      viewport: options.viewport,
     })
 
     addTemplate({
       filename: 'meta.config.mjs',
-      getContents: () => 'export default ' + JSON.stringify({ globalMeta, mixinKey: 'setup' })
+      getContents: () => 'export default ' + JSON.stringify({ globalMeta, mixinKey: 'setup' }),
     })
-  }
+  },
 })
 ```
 
-```ts [plugin.ts]
+In the module above, we generate a virtual file named `meta.config.mjs`. In the runtime plugin, we can import it using the `#build` alias:
+
+```ts [runtime/plugin.ts]
 import { createHead as createServerHead } from '@unhead/vue/server'
 import { createHead as createClientHead } from '@unhead/vue/client'
 import { defineNuxtPlugin } from '#imports'
@@ -126,147 +100,183 @@ export default defineNuxtPlugin((nuxtApp) => {
 })
 ```
 
-::
-
 ## `addTypeTemplate`
 
 Renders given template during build into the project buildDir, then registers it as types.
 
+### Usage
+
+```ts twoslash
+import { addTypeTemplate, defineNuxtModule } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup () {
+    addTypeTemplate({
+      filename: 'types/markdown.d.ts',
+      getContents: () => `declare module '*.md' {
+  import type { ComponentOptions } from 'vue'
+  const Component: ComponentOptions
+  export default Component
+}`,
+    })
+  },
+})
+```
+
 ### Type
 
 ```ts
-function addTypeTemplate (template: NuxtTypeTemplate | string): ResolvedNuxtTemplate
-
-interface NuxtTemplate {
-  src?: string
-  filename?: string
-  dst?: string
-  options?: Record<string, any>
-  getContents?: (data: Record<string, any>) => string | Promise<string>
-}
-
-interface ResolvedNuxtTemplate {
-  src: string
-  filename: string
-  dst: string
-  options: Record<string, any>
-  getContents: (data: Record<string, any>) => string | Promise<string>
-  write: boolean
-  filename: string
-  dst: string
-}
+function addTypeTemplate (template: NuxtTypeTemplate | string, context?: { nitro?: boolean, nuxt?: boolean }): ResolvedNuxtTemplate
 ```
 
 ### Parameters
 
-#### `template`
-
-**Type**: `NuxtTypeTemplate | string`
-
-**Required**: `true`
+**template**: A template object or a string with the path to the template. If a string is provided, it will be converted to a template object with `src` set to the string value. If a template object is provided, it must have the following properties:
 
-A template object or a string with the path to the template. If a string is provided, it will be converted to a template object with `src` set to the string value. If a template object is provided, it must have the following properties:
+| Property   | Type                                                                 | Required | Description                                                                                                     |
+| ---------- | -------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
+| `src`      | `string`                                                             | `false`  | Path to the template. If `src` is not provided, `getContents` must be provided instead.                         |
+| `filename` | `string`                                                             | `false`  | Filename of the template. If `filename` is not provided, it will be generated from the `src` path. In this case, the `src` option is required. |
+| `dst`      | `string`                                                             | `false`  | Path to the destination file. If `dst` is not provided, it will be generated from the `filename` path and nuxt `buildDir` option. |
+| `options`  | `Options`                                                            | `false`  | Options to pass to the template.                                                                                |
+| `getContents` | `(data: Options) => string \| Promise<string>`{lang="ts"} | `false`  | A function that will be called with the `options` object. It should return a string or a promise that resolves to a string. If `src` is provided, this function will be ignored. |
 
-- `src` (optional)
+**context**: An optional context object can be passed to control where the type is added. If omitted, the type will only be added to the Nuxt context. This object supports the following properties:
 
-  **Type**: `string`
+| Property   | Type                                                                 | Required | Description                                                                                                     |
+| ---------- | -------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
+| `nuxt`     | `boolean`                                                            | `false`  | If set to `true`, the type will be added to the Nuxt context.                                                   |
+| `nitro`    | `boolean`                                                            | `false`  | If set to `true`, the type will be added to the Nitro context.                                                  |
 
-  Path to the template. If `src` is not provided, `getContents` must be provided instead.
+### Examples
 
-- `filename` (optional)
+#### Adding Type Templates to the Nitro Context
 
-  **Type**: `string`
+By default, －－ only adds the type declarations to the Nuxt context. To also add them to the Nitro context, set nitro to true.
 
-  Filename of the template. If `filename` is not provided, it will be generated from the `src` path. In this case, the `src` option is required.
+```ts twoslash
+import { addTypeTemplate, defineNuxtModule } from '@nuxt/kit'
 
-- `dst` (optional)
+export default defineNuxtModule({
+  setup () {
+    addTypeTemplate({
+      filename: 'types/auth.d.ts',
+      getContents: () => `declare module '#auth-utils' {
+  interface User {
+    id: string;
+    name: string;
+  }
 
-  **Type**: `string`
+}`,
+    }, {
+      nitro: true,
+    })
+  },
+})
+```
 
-  Path to the destination file. If `dst` is not provided, it will be generated from the `filename` path and nuxt `buildDir` option.
+This allows the `#auth-utils` module to be used within the Nitro context.
 
-- `options` (optional)
+```ts [server/api/auth.ts]
+import type { User } from '#auth-utils'
 
-  **Type**: `Options`
+export default eventHandler(() => {
+  const user: User = {
+    id: '123',
+    name: 'John Doe',
+  }
 
-  Options to pass to the template.
+  // do something with the user
 
-- `getContents` (optional)
+  return user
+})
+```
 
-  **Type**: `(data: Options) => string | Promise<string>`
+## `addServerTemplate`
 
-  A function that will be called with the `options` object. It should return a string or a promise that resolves to a string. If `src` is provided, this function will be ignored.
+Adds a virtual file that can be used within the Nuxt Nitro server build.
 
-### Examples
+### Usage
 
-```ts
-// https://github.com/Hebilicious/nuxtpress
-import { addTypeTemplate, defineNuxtModule } from "@nuxt/kit"
+```ts twoslash
+import { addServerTemplate, defineNuxtModule } from '@nuxt/kit'
 
 export default defineNuxtModule({
-  setup() {
-    addTypeTemplate({
-      filename: "types/markdown.d.ts",
-      getContents: () => /* ts */`
-      declare module '*.md' {
-        import type { ComponentOptions } from 'vue'
-        const Component: ComponentOptions
-        export default Component
-      }`
+  setup () {
+    addServerTemplate({
+      filename: '#my-module/test.mjs',
+      getContents () {
+        return 'export const test = 123'
+      },
     })
-  }
-}
+  },
+})
 ```
 
-## `updateTemplates`
-
-Regenerate templates that match the filter. If no filter is provided, all templates will be regenerated.
-
 ### Type
 
-```ts
-async function updateTemplates (options: UpdateTemplatesOptions): void
-
-interface UpdateTemplatesOptions {
-  filter?: (template: ResolvedNuxtTemplate) => boolean
-}
-
-interface ResolvedNuxtTemplate {
-  src: string
-  filename: string
-  dst: string
-  options: Record<string, any>
-  getContents: (data: Record<string, any>) => string | Promise<string>
-  write: boolean
-  filename: string
-  dst: string
-}
+```ts twoslash
+// @errors: 2391
+import type { NuxtServerTemplate } from '@nuxt/schema'
+// ---cut---
+function addServerTemplate (template: NuxtServerTemplate): NuxtServerTemplate
 ```
 
 ### Parameters
 
-#### `options`
+**template**: A template object. It must have the following properties:
 
-**Type**: `UpdateTemplatesOptions`
+| Property      | Type                                         | Required | Description                                                                                                     |
+| ------------- | ---------------------------------------------| -------- | --------------------------------------------------------------------------------------------------------------- |
+| `filename`    | `string`                                     | `true`   | Filename of the template.                                                                                       |
+| `getContents` | `() => string \| Promise<string>`{lang="ts"} | `true`   | A function that will be called with the `options` object. It should return a string or a promise that resolves to a string. |
 
-**Default**: `{}`
+### Examples
+
+### Creating a Virtual File for Nitro
 
-Options to pass to the template. This object can have the following property:
+In this example, we create a virtual file that can be used within the Nuxt Nitro server build.
 
-- `filter` (optional)
+```ts twoslash
+import { addServerTemplate, defineNuxtModule } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup () {
+    addServerTemplate({
+      filename: '#my-module/test.mjs',
+      getContents () {
+        return 'export const test = 123'
+      },
+    })
+  },
+})
+```
 
-  **Type**: `(template: ResolvedNuxtTemplate) => boolean`
+And then in a runtime file
+
+```ts [server/api/test.ts]
+import { test } from '#my-module/test.js'
+
+export default eventHandler(() => {
+  return test
+})
+```
+
+## `updateTemplates`
 
-  A function that will be called with the `template` object. It should return a boolean indicating whether the template should be regenerated. If `filter` is not provided, all templates will be regenerated.
+Regenerate templates that match the filter. If no filter is provided, all templates will be regenerated.
 
-### Example
+### Usage
 
 ```ts
-// https://github.com/nuxt/nuxt
 import { defineNuxtModule, updateTemplates } from '@nuxt/kit'
+import { resolve } from 'pathe'
 
 export default defineNuxtModule({
-  setup(options, nuxt) {
+  setup (options, nuxt) {
+    const updateTemplatePaths = [
+      resolve(nuxt.options.srcDir, 'pages'),
+    ]
     // watch and rebuild routes template list when one of the pages changes
     nuxt.hook('builder:watch', async (event, relativePath) => {
       if (event === 'change') { return }
@@ -274,10 +284,24 @@ export default defineNuxtModule({
       const path = resolve(nuxt.options.srcDir, relativePath)
       if (updateTemplatePaths.some(dir => path.startsWith(dir))) {
         await updateTemplates({
-          filter: template => template.filename === 'routes.mjs'
+          filter: template => template.filename === 'routes.mjs',
         })
       }
     })
-  }
+  },
 })
 ```
+
+### Type
+
+```ts
+async function updateTemplates (options: UpdateTemplatesOptions): void
+```
+
+### Parameters
+
+**options**: Options to pass to the template. This object can have the following property:
+
+| Property   | Type                                                                 | Required | Description                                                                                                     |
+| ---------- | -------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
+| `filter`    | `(template: ResolvedNuxtTemplate) => boolean`{lang="ts"} | `false`  | A function that will be called with the `template` object. It should return a boolean indicating whether the template should be regenerated. If `filter` is not provided, all templates will be regenerated. |