Templates

Templates allow you 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 virtual file system, and optionally to disk in the project buildDir

Usage#

```ts twoslash 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' }),
})

}, })

### Type

```ts twoslash
// @errors: 2391
import type { NuxtTemplate, ResolvedNuxtTemplate } from '@nuxt/schema'
// ---cut---
function addTemplate (template: NuxtTemplate | string): ResolvedNuxtTemplate

Parameters#

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:

Example#

Creating a Virtual File for Runtime Plugin#

In this example, we merge an object inside a module and consume the result in a runtime plugin.

```ts twoslash [module.ts] 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' }),
})

}, })

#### Skipping Regeneration in Development

By default, Nuxt recompiles a template on every watched file event because it cannot know what
the template reads. If your template is built only from configuration and from which files exist,
declare that so Nuxt can leave it alone when a file is edited:

```ts twoslash [module.ts]
import { addTemplate, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options, nuxt) {
    addTemplate({
      filename: 'my-module/config.mjs',
      dependsOn: [],
      getContents: () => 'export default ' + JSON.stringify(options),
    })
  },
})

If the template reads well-known sources, declare them by key:

addTemplate({
  filename: 'my-module/routes.mjs',
  dependsOn: ['pages'],
  getContents: ({ app }) => generateRoutes(app.pages),
})

And if it reads files Nuxt doesn't know about, say a set of YAML files you scan yourself, pass a function instead:

addTemplate({
  filename: 'my-module/content.mjs',
  dependsOn: ({ path }) => path.endsWith('.yaml'),
  getContents: () => generateContents(),
})

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' // @ts-expect-error - virtual file 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.

### 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#

function addTypeTemplate (template: NuxtTypeTemplate | string, context?: { nitro?: boolean, nuxt?: boolean }): ResolvedNuxtTemplate

Parameters#

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:

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:

Example#

Adding Type Templates to the Nitro Context#

By default, －－ only adds the type declarations to the Nuxt context. To also add them to the Nitro context, set nitro to true.

```ts twoslash import { addTypeTemplate, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({ setup () { addTypeTemplate({ filename: 'types/auth.d.ts', getContents: () => `declare module '#auth-utils' { interface User { id: string; name: string; }

}`, }, { nitro: true, }) }, })

This allows the `#auth-utils` module to be used within the Nitro context.

```ts [server/api/auth.ts]
import type { User } from '#auth-utils'

export default eventHandler(() => {
  const user: User = {
    id: '123',
    name: 'John Doe',
  }

  // do something with the user

  return user
})

addServerTemplate#

Adds a virtual file that can be used within the Nuxt Nitro server build.

Usage#

```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

```ts twoslash
// @errors: 2391
import type { NuxtServerTemplate } from '@nuxt/schema'
// ---cut---
function addServerTemplate (template: NuxtServerTemplate): NuxtServerTemplate

Parameters#

template: A template object. It must have the following properties:

Example#

Creating a Virtual File for Nitro#

In this example, we create a virtual file that can be used within the Nuxt Nitro server build.

```ts twoslash import { addServerTemplate, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({ setup () { addServerTemplate({ filename: '#my-module/test.mjs', getContents () { return 'export const test = 123' }, }) }, })

And then in a runtime file

```ts [server/api/test.ts]
import { test } from '#my-module/test.js'

export default eventHandler(() => {
  return test
})

updateTemplates#

Regenerate templates that match the filter. If no filter is provided, all templates will be regenerated.

Usage#

import { defineNuxtModule, updateTemplates } from '@nuxt/kit'
import { resolve } from 'pathe'

export default defineNuxtModule({
  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
      }

      const path = resolve(nuxt.options.srcDir, relativePath)
      if (updateTemplatePaths.some(dir => path.startsWith(dir))) {
        await updateTemplates({
          filter: template => template.filename === 'routes.mjs',
        })
      }
    })
  },
})

Type#

async function updateTemplates (options: UpdateTemplatesOptions): void

Parameters#

options: Options to pass to the template. This object can have the following property: