템플릿

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`	`string`	`false`	템플릿의 경로입니다. `src`가 제공되지 않으면, 대신 `getContents`가 제공되어야 합니다.
`filename`	`string`	`false`	템플릿의 파일명입니다. `filename`이 제공되지 않으면, `src` 경로에서 생성됩니다. 이 경우 `src` 옵션이 필요합니다.
`dst`	`string`	`false`	대상 파일의 경로입니다. `dst`가 제공되지 않으면, `filename` 경로와 nuxt `buildDir` 옵션에서 생성됩니다.
`options`	`Options`	`false`	템플릿에 전달할 옵션입니다.
`getContents`	`(data: Options) => string \| Promise<string>`	`false`	`options` 객체와 함께 호출되는 함수입니다. 문자열 또는 문자열로 resolve되는 promise를 반환해야 합니다. `src`가 제공되면 이 함수는 무시됩니다.
`write`	`boolean`	`false`	`true`로 설정하면 템플릿이 대상 파일에 기록됩니다. 그렇지 않으면 템플릿은 가상 파일 시스템에서만 사용됩니다.

예시

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

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

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-ignore
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

파라미터

속성	타입	필수	설명
`src`	`string`	`false`	템플릿의 경로입니다. `src`가 제공되지 않으면, 대신 `getContents`가 제공되어야 합니다.
`filename`	`string`	`false`	템플릿의 파일명입니다. `filename`이 제공되지 않으면, `src` 경로에서 생성됩니다. 이 경우 `src` 옵션이 필요합니다.
`dst`	`string`	`false`	대상 파일의 경로입니다. `dst`가 제공되지 않으면, `filename` 경로와 nuxt `buildDir` 옵션에서 생성됩니다.
`options`	`Options`	`false`	템플릿에 전달할 옵션입니다.
`getContents`	`(data: Options) => string \| Promise<string>`	`false`	`options` 객체와 함께 호출되는 함수입니다. 문자열 또는 문자열로 resolve되는 promise를 반환해야 합니다. `src`가 제공되면 이 함수는 무시됩니다.

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

속성	타입	필수	설명
`nuxt`	`boolean`	`false`	`true`로 설정하면 타입이 Nuxt 컨텍스트에 추가됩니다.
`nitro`	`boolean`	`false`	`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',
  }

  // 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`	`string`	`true`	템플릿의 파일명입니다.
`getContents`	`() => string \| Promise<string>`	`true`	`options` 객체와 함께 호출되는 함수입니다. 문자열 또는 문자열로 resolve되는 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'),
    ]
    // 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`	`false`	`template` 객체와 함께 호출되는 함수입니다. 템플릿을 다시 생성할지 여부를 나타내는 boolean을 반환해야 합니다. `filter`가 제공되지 않으면 모든 템플릿이 다시 생성됩니다.