Modules

Source
Nuxt Kit은 모듈을 생성하고 사용하는 데 도움이 되는 유틸리티 세트를 제공합니다. 이 유틸리티를 사용하여 자신만의 모듈을 만들거나 기존 모듈을 재사용할 수 있습니다.

모듈은 Nuxt의 구성 요소입니다. Kit은 모듈을 생성하고 사용하는 데 도움이 되는 유틸리티 세트를 제공합니다. 이 유틸리티를 사용하여 자신만의 모듈을 만들거나 기존 모듈을 재사용할 수 있습니다. 예를 들어, defineNuxtModule 함수를 사용해 모듈을 정의하고 moduleDependencies 옵션을 사용해 의존성을 지정할 수 있습니다.

defineNuxtModule

Nuxt 모듈을 정의하며, 사용자 제공 옵션과 기본값을 자동으로 병합하고, 제공된 훅을 설치하며, 전체 제어를 위한 선택적 setup 함수를 호출합니다.

Usage

import { defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  meta: {
    name: 'my-module',
    configKey: 'myModule',
  },
  defaults: {
    enabled: true,
  },
  setup (options) {
    if (options.enabled) {
      console.log('My Nuxt module is enabled!')
    }
  },
})

Type

export function defineNuxtModule<TOptions extends ModuleOptions> (
  definition?: ModuleDefinition<TOptions, Partial<TOptions>, false> | NuxtModule<TOptions, Partial<TOptions>, false>,
): NuxtModule<TOptions, TOptions, false>

export function defineNuxtModule<TOptions extends ModuleOptions> (): {
  with: <TOptionsDefaults extends Partial<TOptions>> (
    definition: ModuleDefinition<TOptions, TOptionsDefaults, true> | NuxtModule<TOptions, TOptionsDefaults, true>,
  ) => NuxtModule<TOptions, TOptionsDefaults, true>
}

Parameters

definition: 모듈 정의 객체 또는 모듈 함수입니다. 모듈 정의 객체는 다음 속성을 포함해야 합니다:

PropertyTypeRequiredDescription
metaModuleMetafalse모듈의 메타데이터입니다. 모듈 이름, 버전, 설정 키 및 호환성을 정의합니다.
defaultsT | ((nuxt: Nuxt) => T)false모듈의 기본 옵션입니다. 함수가 제공되면 Nuxt 인스턴스를 첫 번째 인자로 하여 호출됩니다.
schemaTfalse모듈 옵션에 대한 스키마입니다. 제공되면 옵션이 스키마에 적용됩니다.
hooksPartial<NuxtHooks>false모듈에 설치할 훅입니다. 제공되면 모듈이 해당 훅을 설치합니다.
moduleDependenciesRecord<string, ModuleDependency> | ((nuxt: Nuxt) => Record<string, ModuleDependency>)false버전 제약 및 설정과 함께 다른 모듈에 대한 의존성입니다. Nuxt 인스턴스를 받는 객체 또는 함수가 될 수 있습니다. 예시를 참고하세요.
onInstall(nuxt: Nuxt) => Awaitable<void>false모듈이 처음 설치될 때 호출되는 라이프사이클 훅입니다. meta.name과 meta.version이 정의되어 있어야 합니다.
onUpgrade(options: T, nuxt: Nuxt, previousVersion: string) => Awaitable<void>false모듈이 더 최신 버전으로 업그레이드될 때 호출되는 라이프사이클 훅입니다. meta.name과 meta.version이 정의되어 있어야 합니다.
setup(this: void, resolvedOptions: T, nuxt: Nuxt) => Awaitable<void | false | ModuleSetupInstallResult>false모듈의 setup 함수입니다. 제공되면 모듈이 이 setup 함수를 호출합니다.

Examples

Using configKey to Make Your Module Configurable

Nuxt 모듈을 정의할 때, configKey를 설정하여 사용자가 nuxt.config에서 모듈을 어떻게 설정해야 하는지 지정할 수 있습니다.

import { defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  meta: {
    name: 'my-module',
    configKey: 'myModule',
  },
  defaults: {
    // Module options
    enabled: true,
  },
  setup (options) {
    if (options.enabled) {
      console.log('My Nuxt module is enabled!')
    }
  },
})

사용자는 nuxt.config에서 해당 키 아래에 이 모듈의 옵션을 제공할 수 있습니다.

export default defineNuxtConfig({
  myModule: {
    enabled: false,
  },
})

Defining Module Compatibility Requirements

Nuxt 모듈을 개발하면서 특정 Nuxt 버전에서만 지원되는 API를 사용하는 경우, compatibility.nuxt를 포함하는 것을 강력히 권장합니다.

export default defineNuxtModule({
  meta: {
    name: '@nuxt/icon',
    configKey: 'icon',
    compatibility: {
      // semver 형식의 필수 nuxt 버전.
      nuxt: '>=3.0.0', // 또는 '^3.0.0' 사용
    },
  },
  setup () {
    const resolver = createResolver(import.meta.url)
    // 구현
  },
})

사용자가 호환되지 않는 Nuxt 버전에서 모듈을 사용하려고 하면, 콘솔에 경고가 표시됩니다.

 WARN  Module @nuxt/icon is disabled due to incompatibility issues:
 - [nuxt] Nuxt version ^3.1.0 is required but currently using 3.0.0

Type Safety for Resolved Options with .with()

해결/병합된 모듈 옵션에 대한 타입 안전성이 필요할 때 .with() 메서드를 사용할 수 있습니다. 이를 통해 TypeScript가 모듈의 기본값과 setup 함수가 받는 최종 해결 옵션 간의 관계를 올바르게 추론할 수 있습니다.

import { defineNuxtModule } from '@nuxt/kit'

// 모듈 옵션 인터페이스 정의
interface ModuleOptions {
  apiKey: string
  baseURL: string
  timeout?: number
  retries?: number
}

export default defineNuxtModule<ModuleOptions>().with({
  meta: {
    name: '@nuxtjs/my-api',
    configKey: 'myApi',
  },
  defaults: {
    baseURL: 'https://api.example.com',
    timeout: 5000,
    retries: 3,
  },
  setup (resolvedOptions, nuxt) {
    // resolvedOptions는 다음과 같이 올바르게 타입이 지정됩니다:
    // {
    //   apiKey: string          // 필수, 기본값 없음
    //   baseURL: string         // 필수, 기본값 있음
    //   timeout: number         // 선택적이지만, 기본값 있음
    //   retries: number         // 선택적이지만, 기본값 있음
    // }

    console.log(resolvedOptions.baseURL) // ✅ TypeScript는 항상 정의되어 있음을 인지
    console.log(resolvedOptions.timeout) // ✅ TypeScript는 항상 정의되어 있음을 인지
    console.log(resolvedOptions.retries) // ✅ TypeScript는 항상 정의되어 있음을 인지
  },
})

.with()를 사용하지 않으면, resolvedOptions 매개변수는 원래의 ModuleOptions 인터페이스로 타입이 지정되며, 기본값이 제공되더라도 timeout과 retries는 undefined일 수 있습니다. .with() 메서드는 기본값이 해당 속성을 해결된 옵션에서 필수가 되도록 TypeScript가 이해하게 합니다.

Using Lifecycle Hooks for Module Installation and Upgrade

모듈이 처음 설치되거나 새 버전으로 업그레이드될 때 실행되는 라이프사이클 훅을 정의할 수 있습니다. 이러한 훅은 일회성 설정 작업, 데이터베이스 마이그레이션 또는 정리 작업을 수행하는 데 유용합니다.

라이프사이클 훅이 동작하려면, 모듈 정의에 meta.name과 meta.version을 반드시 모두 제공해야 합니다. 훅은 프로젝트의 .nuxtrc 파일에서 모듈 설치 상태를 추적하기 위해 이 값을 사용합니다.

라이프사이클 훅은 메인 setup 함수보다 먼저 실행되며, 훅에서 오류가 발생하면 로그에 기록되지만 빌드 프로세스를 중단하지는 않습니다.

onInstall 은 모듈이 프로젝트에 처음 추가될 때 한 번만 실행됩니다.

onUpgrade 는 모듈 버전이 증가할 때마다(semver 비교 사용) 실행되지만, 각 버전 상승마다 한 번씩만 실행됩니다.

Example
import { defineNuxtModule } from '@nuxt/kit'
import semver from 'semver'

export default defineNuxtModule({
  meta: {
    name: 'my-awesome-module',
    version: '1.2.0', // 라이프사이클 훅에 필요
    configKey: 'myAwesomeModule',
  },
  defaults: {
    apiKey: '',
    enabled: true,
  },

  onInstall (nuxt) {
    // 모듈이 처음 설치될 때만 실행됩니다
    console.log('Setting up my-awesome-module for the first time!')

    // 다음과 같은 작업을 수행할 수 있습니다:
    // - 초기 설정 파일 생성
    // - 데이터베이스 스키마 설정
    // - 환영 메시지 표시
    // - 초기 데이터 마이그레이션 수행
  },

  onUpgrade (options, nuxt, previousVersion) {
    // 모듈이 더 최신 버전으로 업그레이드될 때 실행됩니다
    console.log(`Upgrading my-awesome-module from ${previousVersion} to 1.2.0`)

    // 다음과 같은 작업을 수행할 수 있습니다:
    // - 설정 파일 마이그레이션
    // - 데이터베이스 스키마 업데이트
    // - 더 이상 사용되지 않는 파일 정리
    // - 업그레이드 노트 표시

    if (semver.lt(previousVersion, '1.1.0')) {
      console.log('⚠️  Breaking changes in 1.1.0 - please check the migration guide')
    }
  },

  setup (options, nuxt) {
    // 일반 setup 로직은 모든 빌드에서 실행됩니다
    if (options.enabled) {
      // 모듈 구성
    }
  },
})

Specifying Module Dependencies

moduleDependencies 옵션을 사용해 다른 모듈에 대한 의존성을 선언할 수 있습니다. 이는 올바른 설정 순서, 버전 호환성 및 설정 관리를 보장하는 강력한 방법을 제공합니다.

moduleDependencies 옵션은 객체이거나 Nuxt 인스턴스를 받는 함수일 수 있습니다:

Example
import { defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  meta: {
    name: 'my-module',
  },
  moduleDependencies: {
    '@nuxtjs/tailwindcss': {
      // 버전 제약 조건 지정 (semver 형식)
      version: '>=6.0.0',
      // 사용자 설정을 덮어쓰는 설정
      overrides: {
        exposeConfig: true,
      },
      // 기본값을 설정하지만 사용자 설정을 존중하는 설정
      defaults: {
        config: {
          darkMode: 'class',
        },
      },
    },
    '@nuxtjs/fontaine': {
      // 선택적 의존성은 설치되지는 않지만,
      // 설치된 경우 옵션을 설정할 수 있도록 보장합니다
      optional: true,
      defaults: {
        fonts: [
          {
            family: 'Roboto',
            fallbacks: ['Impact'],
          },
        ],
      },
    },
  },
  setup (options, nuxt) {

  },
})

또한 함수를 사용해 Nuxt 설정에 따라 동적으로 의존성을 결정할 수도 있습니다:

import { defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  meta: {
    name: 'my-module',
  },
  moduleDependencies (nuxt) {
    const dependencies: Record<string, any> = {
      '@nuxtjs/tailwindcss': {
        version: '>=6.0.0',
      },
    }

    // Nuxt 설정에 따라 조건부로 의존성 추가
    if (nuxt.options.experimental?.someFeature) {
      dependencies['@nuxtjs/fontaine'] = {
        optional: true,
      }
    }

    return dependencies
  },
  setup (options, nuxt) {
    // 모든 의존성이 초기화된 후에 setup 로직이 실행됩니다
  },
})

installModule

Deprecated: 대신 defineNuxtModule의 moduleDependencies 옵션을 사용하세요. installModule 함수는 향후 버전에서 제거되거나(또는 논블로킹이 될 수) 있습니다.

지정된 Nuxt 모듈을 프로그래밍 방식으로 설치합니다. 이는 모듈이 다른 모듈에 의존할 때 유용합니다. 모듈 옵션을 객체로 inlineOptions에 전달할 수 있으며, 이는 모듈의 setup 함수로 전달됩니다.

Usage

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

export default defineNuxtModule({
  async setup () {
    // Roboto 폰트와 Impact 폴백으로 @nuxtjs/fontaine을 설치합니다
    await installModule('@nuxtjs/fontaine', {
      // 모듈 설정
      fonts: [
        {
          family: 'Roboto',
          fallbacks: ['Impact'],
          fallbackName: 'fallback-a',
        },
      ],
    })
  },
})

Type

async function installModule (moduleToInstall: string | NuxtModule, inlineOptions?: any, nuxt?: Nuxt)

Parameters

PropertyTypeRequiredDescription
moduleToInstallstring | NuxtModuletrue설치할 모듈입니다. 모듈 이름이 담긴 문자열이거나 모듈 객체 자체일 수 있습니다.
inlineOptionsanyfalse모듈의 setup 함수로 전달될 모듈 옵션 객체입니다.
nuxtNuxtfalseNuxt 인스턴스입니다. 제공되지 않으면 useNuxt() 호출을 통해 컨텍스트에서 가져옵니다.

Examples

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

export default defineNuxtModule({
  async setup (options, nuxt) {
    // Roboto 폰트와 Impact 폴백으로 @nuxtjs/fontaine을 설치합니다
    await installModule('@nuxtjs/fontaine', {
      // 모듈 설정
      fonts: [
        {
          family: 'Roboto',
          fallbacks: ['Impact'],
          fallbackName: 'fallback-a',
        },
      ],
    })
  },
})