Шаблоны

Исходный код
Утилиты Nuxt Kit для шаблонов и генерации дополнительных файлов в разработке и при сборке.

Шаблоны создают дополнительные файлы в режиме разработки и при сборке: они попадают в виртуальную файловую систему и доступны в плагинах, лейаутах, компонентах и т. п. addTemplate и addTypeTemplate регистрируют шаблоны в приложении Nuxt; updateTemplates пересобирает шаблоны по фильтру (или все сразу).

addTemplate

Рендерит шаблон при сборке в виртуальную файловую систему и при необходимости записывает файл в buildDir проекта.

Использование

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

Тип

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

Параметры

template: объект шаблона или строка с путём к шаблону. Строка превращается в объект с полем src. У объекта шаблона обычно есть поля:

СвойствоТипОбязательноОписание
srcstringfalseПуть к шаблону. Если src не задан, нужно указать getContents.
filenamestringfalseИмя файла шаблона. Если не задано, выводится из src; тогда src обязателен.
dststringfalseПуть к целевому файлу. Если не задан, формируется из filename и опции Nuxt buildDir.
optionsOptionsfalseОпции, передаваемые в шаблон.
getContents(data: Options) => string | Promise<string>falseФункция с объектом options; возвращает строку или промис. Если задан src, игнорируется.
writebooleanfalseПри true шаблон пишется на диск; иначе только в виртуальной файловой системе.

Примеры

Виртуальный файл для runtime-плагина

В примере объект объединяется внутри модуля, а результат используется в runtime-плагине.

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

Модуль создаёт виртуальный файл meta.config.mjs. В runtime-плагине его можно импортировать через алиас #build:

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 Виртуальный модуль собирается Nuxt при сборке.
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

Рендерит шаблон в buildDir и подключает его как объявления типов.

Использование

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

Тип

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

Параметры

template: объект шаблона или строка с путём; строка становится объектом с src. Поля объекта:

СвойствоТипОбязательноОписание
srcstringfalseПуть к шаблону. Если src не задан, нужно указать getContents.
filenamestringfalseИмя файла. Если не задано, выводится из src; тогда src обязателен.
dststringfalseПуть назначения. Если не задан, формируется из filename и buildDir.
optionsOptionsfalseОпции для шаблона.
getContents(data: Options) => string | Promise<string>falseФункция с options; возвращает строку или промис. При заданном src игнорируется.

context — куда добавлять типы. Без него типы попадают только в контекст Nuxt. Поля:

СвойствоТипОбязательноОписание
nuxtbooleanfalseПри true тип добавляется в контекст Nuxt.
nitrobooleanfalseПри true тип добавляется в контекст Nitro.

Примеры

Типы в контексте Nitro

По умолчанию addTypeTemplate добавляет типы только в контекст Nuxt. Чтобы продублировать их в Nitro, укажите nitro: 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,
    })
  },
})

После этого модуль #auth-utils доступен в коде Nitro.

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

export default eventHandler(() => {
  const user: User = {
    id: '123',
    name: 'Иван Иванов',
  }

  // дальнейшая работа с user

  return user
})

addServerTemplate

Добавляет виртуальный файл в серверной сборке Nitro.

Использование

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

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

Тип

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

Параметры

template: объект шаблона с полями:

СвойствоТипОбязательноОписание
filenamestringtrueИмя файла шаблона.
getContents() => string | Promise<string>trueФункция, возвращающая строку или промис со строкой (содержимое шаблона).

Примеры

Виртуальный файл для Nitro

Пример виртуального файла в серверной сборке Nitro.

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

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

Использование в runtime-файле:

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

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

updateTemplates

Пересобирает шаблоны, для которых фильтр возвращает true. Без фильтра — все шаблоны.

Использование

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

export default defineNuxtModule({
  setup (options, nuxt) {
    const updateTemplatePaths = [
      resolve(nuxt.options.srcDir, 'pages'),
    ]
    // при изменении страниц пересобирать шаблоны маршрутов
    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',
        })
      }
    })
  },
})

Тип

async function updateTemplates (options: UpdateTemplatesOptions): void

Параметры

options: объект с полем:

СвойствоТипОбязательноОписание
filter(template: ResolvedNuxtTemplate) => booleanfalseДля каждого template возвращает, пересобирать ли его. Без filter пересобираются все шаблоны.