템플릿

Source
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가 해당 문자열 값으로 설정된 템플릿 객체로 변환됩니다. 템플릿 객체가 제공되면, 다음 속성을 가져야 합니다:

PropertyTypeRequiredDescription
srcstringfalse템플릿의 경로입니다. src가 제공되지 않으면, 대신 getContents가 제공되어야 합니다.
filenamestringfalse템플릿의 파일 이름입니다. filename이 제공되지 않으면, src 경로로부터 생성됩니다. 이 경우 src 옵션이 필수입니다.
dststringfalse대상 파일의 경로입니다. dst가 제공되지 않으면, filename 경로와 nuxt buildDir 옵션으로부터 생성됩니다.
optionsOptionsfalse템플릿에 전달할 옵션입니다.
getContents(data: Options) => string | Promise<string>falseoptions 객체와 함께 호출될 함수입니다. 문자열 또는 문자열로 resolve되는 프로미스를 반환해야 합니다. src가 제공되면 이 함수는 무시됩니다.
writebooleanfalsetrue로 설정하면 템플릿이 대상 파일에 기록됩니다. 그렇지 않으면 템플릿은 가상 파일 시스템에서만 사용됩니다.

예시

런타임 플러그인을 위한 가상 파일 생성

이 예시에서는 모듈 내부에서 객체를 병합하고, 그 결과를 런타임 플러그인에서 사용합니다.

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 별칭을 사용해 이를 import 할 수 있습니다:

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 - 가상 파일
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가 해당 문자열 값으로 설정된 템플릿 객체로 변환됩니다. 템플릿 객체가 제공되면, 다음 속성을 가져야 합니다:

PropertyTypeRequiredDescription
srcstringfalse템플릿의 경로입니다. src가 제공되지 않으면, 대신 getContents가 제공되어야 합니다.
filenamestringfalse템플릿의 파일 이름입니다. filename이 제공되지 않으면, src 경로로부터 생성됩니다. 이 경우 src 옵션이 필수입니다.
dststringfalse대상 파일의 경로입니다. dst가 제공되지 않으면, filename 경로와 nuxt buildDir 옵션으로부터 생성됩니다.
optionsOptionsfalse템플릿에 전달할 옵션입니다.
getContents(data: Options) => string | Promise<string>falseoptions 객체와 함께 호출될 함수입니다. 문자열 또는 문자열로 resolve되는 프로미스를 반환해야 합니다. src가 제공되면 이 함수는 무시됩니다.

context: 타입이 어디에 추가될지 제어하기 위해 선택적인 컨텍스트 객체를 전달할 수 있습니다. 생략되면 타입은 Nuxt 컨텍스트에만 추가됩니다. 이 객체는 다음 속성을 지원합니다:

PropertyTypeRequiredDescription
nuxtbooleanfalsetrue로 설정하면 타입이 Nuxt 컨텍스트에 추가됩니다.
nitrobooleanfalsetrue로 설정하면 타입이 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',
  }

  // 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: 템플릿 객체입니다. 다음 속성을 가져야 합니다:

PropertyTypeRequiredDescription
filenamestringtrue템플릿의 파일 이름입니다.
getContents() => string | Promise<string>trueoptions 객체와 함께 호출될 함수입니다. 문자열 또는 문자열로 resolve되는 프로미스를 반환해야 합니다.

예시

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'),
    ]
    // 페이지 중 하나가 변경될 때 라우트 템플릿 목록을 감시하고 재빌드합니다
    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: 템플릿에 전달할 옵션입니다. 이 객체는 다음 속성을 가질 수 있습니다:

PropertyTypeRequiredDescription
filter(template: ResolvedNuxtTemplate) => booleanfalsetemplate 객체와 함께 호출될 함수입니다. 템플릿을 다시 생성해야 하는지 여부를 나타내는 boolean을 반환해야 합니다. filter가 제공되지 않으면, 모든 템플릿이 다시 생성됩니다.