@nuxt/docs 0.0.0 → 3.17.0

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

@@ -0,0 +1,283 @@
+---
+title: "Templates"
+description: Nuxt Kit provides a set of utilities to help you work with templates. These functions allow you to generate extra files during development and build time.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/kit/src/template.ts
+    size: xs
+---
+
+Templates allows to generate extra files during development and build time. These files will be available in virtual filesystem and can be used in plugins, layouts, components, etc. `addTemplate` and `addTypeTemplate` allow you to add templates to the Nuxt application. `updateTemplates` allows you to regenerate templates that match the filter.
+
+## `addTemplate`
+
+Renders given template during build into 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)
+
+  **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`
+
+  Path to the destination file. If `dst` is not provided, it will be generated from the `filename` path and nuxt `buildDir` option.
+
+- `options` (optional)
+
+  **Type**: `Options`
+
+  Options to pass to the template.
+
+- `getContents` (optional)
+
+  **Type**: `(data: Options) => string | Promise<string>`
+
+  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` (optional)
+  
+  **Type**: `boolean`
+
+  If set to `true`, the template will be written to the destination file. Otherwise, the template will be used only in virtual filesystem.
+
+### Examples
+
+::code-group
+  
+```ts [module.ts]
+// https://github.com/nuxt/bridge
+import { addTemplate, defineNuxtModule } from '@nuxt/kit'
+import { defu } from 'defu'
+
+export default defineNuxtModule({
+  setup(options, nuxt) {
+    const globalMeta = defu(nuxt.options.app.head, {
+      charset: options.charset,
+      viewport: options.viewport
+    })
+
+    addTemplate({
+      filename: 'meta.config.mjs',
+      getContents: () => 'export default ' + JSON.stringify({ globalMeta, mixinKey: 'setup' })
+    })
+  }
+})
+```
+
+```ts [plugin.ts]
+import { createHead as createServerHead } from '@unhead/vue/server'
+import { createHead as createClientHead } from '@unhead/vue/client'
+import { defineNuxtPlugin } from '#imports'
+// @ts-ignore
+import metaConfig from '#build/meta.config.mjs'
+
+export default defineNuxtPlugin((nuxtApp) => {
+  const createHead = import.meta.server ? createServerHead : createClientHead
+  const head = createHead()
+  head.push(metaConfig.globalMeta)
+
+  nuxtApp.vueApp.use(head)
+})
+```
+
+::
+
+## `addTypeTemplate`
+
+Renders given template during build into the project buildDir, then registers it as types.
+
+### 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
+}
+```
+
+### Parameters
+
+#### `template`
+
+**Type**: `NuxtTypeTemplate | 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)
+
+  **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`
+
+  Path to the destination file. If `dst` is not provided, it will be generated from the `filename` path and nuxt `buildDir` option.
+
+- `options` (optional)
+
+  **Type**: `Options`
+
+  Options to pass to the template.
+
+- `getContents` (optional)
+
+  **Type**: `(data: Options) => string | Promise<string>`
+
+  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.
+
+### Examples
+
+```ts
+// https://github.com/Hebilicious/nuxtpress
+import { addTypeTemplate, 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
+      }`
+    })
+  }
+}
+```
+
+## `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
+}
+```
+
+### Parameters
+
+#### `options`
+
+**Type**: `UpdateTemplatesOptions`
+
+**Default**: `{}`
+
+Options to pass to the template. This object can have the following property:
+
+- `filter` (optional)
+
+  **Type**: `(template: ResolvedNuxtTemplate) => boolean`
+
+  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.
+
+### Example
+
+```ts
+// https://github.com/nuxt/nuxt
+import { defineNuxtModule, updateTemplates } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup(options, nuxt) {
+    // watch and rebuild routes template list when one of the pages changes
+    nuxt.hook('builder:watch', async (event, relativePath) => {
+      if (event === 'change') { return }
+
+      const path = resolve(nuxt.options.srcDir, relativePath)
+      if (updateTemplatePaths.some(dir => path.startsWith(dir))) {
+        await updateTemplates({
+          filter: template => template.filename === 'routes.mjs'
+        })
+      }
+    })
+  }
+})
+```

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

@@ -0,0 +1,409 @@
+---
+title: "Nitro"
+description: Nuxt Kit provides a set of utilities to help you work with Nitro. These functions allow you to add server handlers, plugins, and prerender routes.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/kit/src/nitro.ts
+    size: xs
+---
+
+Nitro is an open source TypeScript framework to build ultra-fast web servers. Nuxt uses Nitro as its server engine. You can use `useNitro` to access the Nitro instance, `addServerHandler` to add a server handler, `addDevServerHandler` to add a server handler to be used only in development mode, `addServerPlugin` to add a plugin to extend Nitro's runtime behavior, and `addPrerenderRoutes` to add routes to be prerendered by Nitro.
+
+## `addServerHandler`
+
+Adds a nitro server handler. Use it if you want to create server middleware or custom route.
+
+### 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`
+
+  Path prefix or route. If an empty string used, will be used as a middleware.
+
+- `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`
+
+  Router method matcher. If handler name contains method name, it will be used as a default value.
+
+### Examples
+
+::code-group
+
+```ts [module.ts]
+// https://github.com/nuxt-modules/robots
+import { createResolver, defineNuxtModule, addServerHandler } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup(options) {
+    const resolver = createResolver(import.meta.url)
+
+    addServerHandler({
+      route: '/robots.txt',
+      handler: resolver.resolve('./runtime/robots.get')
+    })
+  }
+})
+```
+
+```ts [runtime/robots.get.ts]
+export default defineEventHandler(() => {
+  return {
+    body: `User-agent: *\nDisallow: /`
+  }
+})
+```
+
+::
+
+## `addDevServerHandler`
+
+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;
+}
+```
+
+### 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.
+
+### Examples
+
+::code-group
+
+```ts [module.ts]
+import { createResolver, defineNuxtModule, addDevServerHandler } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup() {
+    const resolver = createResolver(import.meta.url)
+
+    addDevServerHandler({
+      handler: () => {
+        return {
+          body: `Response generated at ${new Date().toISOString()}`
+        }
+      },
+      route: '/_handler'
+    })
+  }
+})
+```
+
+::
+
+```ts
+// https://github.com/nuxt-modules/tailwindcss
+import { joinURL } from 'ufo'
+import { defineNuxtModule, addDevServerHandler } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  async setup(options) {
+    const route = joinURL(nuxt.options.app?.baseURL, '/_tailwind')
+
+    // @ts-ignore
+    const createServer = await import('tailwind-config-viewer/server/index.js').then(r => r.default || r) as any
+    const viewerDevMiddleware = createServer({ tailwindConfigProvider: () => options, routerPrefix: route }).asMiddleware()
+
+    addDevServerHandler({ route, handler: viewerDevMiddleware })
+  }
+})
+```
+
+## `useNitro`
+
+Returns the Nitro instance.
+
+::warning
+You can call `useNitro()` only after `ready` hook.
+::
+
+::note
+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
+
+```ts
+// https://github.com/nuxt/nuxt/blob/4e05650cde31ca73be4d14b1f0d23c7854008749/packages/nuxt/src/core/nuxt.ts#L404
+import { defineNuxtModule, useNitro, addPlugin, createResolver } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup(options, nuxt) {
+    const resolver = createResolver(import.meta.url)
+
+    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'))
+      }
+    })
+  }
+})
+```
+
+## `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).
+::
+
+### Type
+
+```ts
+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.
+
+### Examples
+
+::code-group
+
+```ts [module.ts]
+import { createResolver, defineNuxtModule, addServerPlugin } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup() {
+    const resolver = createResolver(import.meta.url)
+    addServerPlugin(resolver.resolve('./runtime/plugin.ts'))
+  }
+})
+```
+
+```ts [runtime/plugin.ts]
+export default defineNitroPlugin((nitroApp) => {
+  nitroApp.hooks.hook("request", (event) => {
+    console.log("on request", event.path);
+  });
+
+  nitroApp.hooks.hook("beforeResponse", (event, { body }) => {
+    console.log("on response", event.path, { body });
+  });
+
+  nitroApp.hooks.hook("afterResponse", (event, { body }) => {
+    console.log("on after response", event.path, { body });
+  });
+});
+```
+
+::
+
+## `addPrerenderRoutes`
+
+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
+
+```ts
+import { defineNuxtModule, addPrerenderRoutes } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  meta: {
+    name: 'nuxt-sitemap',
+    configKey: 'sitemap',
+  },
+  defaults: {
+    sitemapUrl: '/sitemap.xml',
+    prerender: true,
+  },
+  setup(options) {
+    if (options.prerender) {
+      addPrerenderRoutes(options.sitemapUrl)
+    }
+  }
+})
+```
+
+## `addServerImportsDir`
+
+Add a directory to be scanned for auto-imports by Nitro.
+
+### Type
+
+```ts
+function addServerImportsDir (dirs: string | string[], opts: { prepend?: boolean }): void
+```
+
+### Parameters
+
+#### `dirs`
+
+**Type**: `string | string[]`
+
+**Required**: `true`
+
+A directory or an array of directories to register to be scanned by Nitro
+
+### Examples
+
+```ts
+import { defineNuxtModule, createResolver, addServerImportsDir } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  meta: {
+    name: 'my-module',
+    configKey: 'myModule',
+  },
+  setup(options) {
+    const resolver = createResolver(import.meta.url)
+    addServerImportsDir(resolver.resolve('./runtime/server/utils'))
+  }
+})
+```
+
+## `addServerScanDir`
+
+Add directories to be scanned by Nitro. It will check for subdirectories, which will be registered
+just like the `~/server` folder is.
+
+### Type
+
+```ts
+function addServerScanDir (dirs: string | string[], opts: { prepend?: boolean }): void
+```
+
+### Parameters
+
+#### `dirs`
+
+**Type**: `string | string[]`
+
+**Required**: `true`
+
+A directory or an array of directories to register to be scanned for by Nitro as server dirs.
+
+### Examples
+
+```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'))
+  }
+})
+```