Nuxt/docs/3.api/4.kit/10.templates.md

title	description
Templates	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.

Templates

source code

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

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

// 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' })
    })
  }
})

import { createHead as createClientHead, createServerHead } from '@unhead/vue'
import { defineNuxtPlugin } from '#app'
// @ts-ignore
import metaConfig from '#build/meta.config.mjs'

export default defineNuxtPlugin((nuxtApp) => {
  const createHead = process.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

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

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

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

// 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'
        })
      }
    })
  }
})