Templates · Nuxt Kit

Nuxt Kit
Templates
Source

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 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
module.ts
plugin.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' })

    })

  }

})

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'

        })

      }

    })

  }

})


Plugins

Nuxt Kit provides a set of utilities to help you create and use plugins. You can add plugins or plugin templates to your module using these functions.

Nitro

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.