Шаблоны

Исходники
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. Объект может содержать:

СвойствоТипОбязательныйОписание
srcstringнетПуть к шаблону. Если не задан — нужен getContents.
filenamestringнетИмя файла. По умолчанию из src (тогда src обязателен).
dststringнетПуть к целевому файлу. По умолчанию из filename и buildDir.
optionsOptionsнетДанные для шаблона.
getContents(data: Options) => string | Promise<string>нетФункция, возвращающая содержимое. При заданном src не используется.
writebooleanнет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 - 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

Отображает заданный шаблон во время сборки в 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. У объекта могут быть следующие свойства:

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

context: опциональный объект — куда добавить типы. По умолчанию только в контекст Nuxt.

СвойствоТипОбязательныйОписание
nuxtbooleanнетtrue — добавить типы в контекст Nuxt.
nitrobooleanнетtrue — добавить типы в контекст Nitro.

Примеры

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

По умолчанию типы добавляются только в контекст 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: 'John Doe',
  }

  // do something with the user

  return user
})

addServerTemplate

Добавляет виртуальный файл для использования в серверной сборке Nuxt (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 — объект с полями:

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

Примеры

Виртуальный файл для 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

Перегенерирует шаблоны, проходящие фильтр. Без фильтра перегенерируются все шаблоны.

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

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) => booleanнетФункция: возвращает true для шаблонов, которые нужно перегенерировать. Без filter перегенерируются все.