Templates

Template utilities to generate extra files during development and build time

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

Renders given template during build into the virtual file system, and optionally to disk in the project buildDir.

Type

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 can 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 not provided, generated from the src path. In this case, src is required.
dst	string	false	Path to the destination file. If not provided, generated from the filename path and nuxt buildDir.
options	Options	false	Options to pass to the template.
getContents	(data: Options) => string | Promise<string>	false	A function that returns template contents. If src is provided, this is ignored.
write	boolean	false	If set to true, the template will be written to disk. Otherwise, used only in virtual filesystem.

Usage

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

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.

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

In the runtime plugin, we can import it using the #build alias:

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.

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. Properties are the same as addTemplate.

context: Optional context object:

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.

Usage

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

Adding Type Templates to the Nitro Context

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

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,
    })
  },
})

addServerTemplate

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

Type

function addServerTemplate(template: NuxtServerTemplate): NuxtServerTemplate

Parameters

template: A template object with the following properties:

Property	Type	Required	Description
filename	string	true	Filename of the template.
getContents	() => string | Promise<string>	true	A function that returns the template contents.

Usage

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

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

Then in a runtime file:

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.

Type

async function updateTemplates(options: UpdateTemplatesOptions): void

Parameters

options: Options object:

Property	Type	Required	Description
filter	(template: ResolvedNuxtTemplate) => boolean	false	A function that returns whether the template should be regenerated. If not 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',
        })
      }
    })
  },
})

Source

View source on GitHub