テンプレート

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

タイプ

function addTemplate (template: NuxtTemplate | string): ResolvedNuxtTemplate

パラメーター

template: テンプレートオブジェクト、またはテンプレートへのパスを含む文字列。文字列が提供された場合、src が文字列値に設定されたテンプレートオブジェクトに変換されます。テンプレートオブジェクトが提供された場合、以下のプロパティが必要です。

プロパティタイプ必須説明
src文字列falseテンプレートへのパス。srcが指定されていない場合は、代わりにgetContentsが指定されている必要があります。
filename文字列falseテンプレートのファイル名。filenameが指定されていない場合、srcパスから生成されます。この場合、srcオプションは必須です。
dst文字列false宛先ファイルへのパス。dstが指定されていない場合、filenameパスとNuxtのbuildDirオプションから生成されます。
optionsオプションfalseテンプレートに渡すオプション。
getContents(data: Options) => string | Promise<string>falseoptionsオブジェクトを引数として呼び出される関数です。文字列、または文字列に解決されるPromiseを返す必要があります。srcが指定されている場合、この関数は無視されます。
writeブール値falsetrueに設定すると、テンプレートは宛先ファイルに書き込まれます。それ以外の場合、テンプレートは仮想ファイルシステムでのみ使用されます。

例

ランタイムプラグイン用の仮想ファイルの作成

この例では、モジュール内のオブジェクトをマージし、その結果をランタイムプラグインで消費します。

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 という名前の仮想ファイルを生成します。ランタイムプラグインでは、#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 が文字列値に設定されたテンプレートオブジェクトに変換されます。テンプレートオブジェクトが提供された場合、以下のプロパティが必要です。

プロパティタイプ必須説明
src文字列falseテンプレートへのパス。srcが指定されていない場合は、代わりにgetContentsが指定されている必要があります。
filename文字列falseテンプレートのファイル名。filenameが指定されていない場合、srcパスから生成されます。この場合、srcオプションは必須です。
dst文字列false宛先ファイルへのパス。dstが指定されていない場合、filenameパスとNuxtのbuildDirオプションから生成されます。
optionsオプションfalseテンプレートに渡すオプション。
getContents(data: Options) => string | Promise<string>falseoptionsオブジェクトを引数として呼び出される関数です。文字列、または文字列に解決されるPromiseを返す必要があります。srcが指定されている場合、この関数は無視されます。

context: 型が追加される場所を制御するために、オプションのコンテキストオブジェクトを渡すことができます。省略された場合、型は Nuxt コンテキストにのみ追加されます。このオブジェクトは以下のプロパティをサポートします。

プロパティタイプ必須説明
nuxtブール値falsetrue に設定すると、型が Nuxt コンテキストに追加されます。
ニトロブール値falsetrue に設定すると、型が 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'
      },
    })
  },
})

タイプ

function addServerTemplate (template: NuxtServerTemplate): NuxtServerTemplate

パラメーター

template: テンプレートオブジェクト。以下のプロパティが必要です。

プロパティタイプ必須説明
filename文字列trueテンプレートのファイル名。
getContents() => string | Promise<string>trueoptions オブジェクトと共に呼び出される関数。文字列、または文字列に解決される Promise を返す必要があります。

例

Nitro 用の仮想ファイルの作成

この例では、Nuxt Nitro サーバービルド内で使用できる仮想ファイルを作成します。

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

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

そして、ランタイムファイルで

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

タイプ

async function updateTemplates (options: UpdateTemplatesOptions): void

パラメーター

options: テンプレートに渡すオプション。このオブジェクトは以下のプロパティを持つことができます。

プロパティタイプ必須説明
filter(template: ResolvedNuxtTemplate) => booleanfalsetemplate オブジェクトと共に呼び出される関数。テンプレートを再生成するかどうかを示すブール値を返す必要があります。filter が提供されない場合、すべてのテンプレートが再生成されます。