app.config.ts

Nuxt는 app.config 구성 파일을 제공하여 애플리케이션 내에서 반응형 구성을 노출하며, 라이프사이클 내에서 또는 nuxt 플러그인을 사용하여 런타임에 업데이트하고 HMR(핫 모듈 교체)로 편집할 수 있습니다.

app.config.ts 파일을 사용하여 런타임 앱 구성을 쉽게 제공할 수 있습니다. 이 파일은 .ts, .js, 또는 .mjs 확장자를 가질 수 있습니다.

export default defineAppConfig({
  foo: 'bar'
})

사용법

앱의 나머지 부분에 구성 및 환경 변수를 노출하려면, app.config 파일에 구성을 정의해야 합니다.

export default defineAppConfig({
  theme: {
    primaryColor: '#ababab'
  }
})

이제 useAppConfig 컴포저블을 사용하여 서버 렌더링 시와 브라우저 모두에서 theme에 범용적으로 접근할 수 있습니다.

<script setup lang="ts">
const appConfig = useAppConfig()

console.log(appConfig.theme)
</script>

updateAppConfig 유틸리티를 사용하여 런타임에 app.config를 업데이트할 수 있습니다.

<script setup>
const appConfig = useAppConfig() // { foo: 'bar' }

const newAppConfig = { foo: 'baz' }

updateAppConfig(newAppConfig)

console.log(appConfig) // { foo: 'baz' }
</script>

App Config 타입 지정

Nuxt는 제공된 앱 구성에서 TypeScript 인터페이스를 자동으로 생성하려고 시도하므로 직접 타입을 지정할 필요가 없습니다.

하지만 직접 타입을 지정하고 싶은 경우가 있을 수 있습니다. 타입을 지정할 수 있는 두 가지 경우가 있습니다.

App Config 입력

AppConfigInput은 모듈 작성자가 앱 구성 설정 시 유효한 입력 옵션을 선언할 때 사용할 수 있습니다. 이는 useAppConfig()의 타입에는 영향을 주지 않습니다.

declare module 'nuxt/schema' {
  interface AppConfigInput {
    /** 테마 구성 */
    theme?: {
      /** 기본 앱 색상 */
      primaryColor?: string
    }
  }
}

// 타입을 보강할 때는 항상 무언가를 import/export 해야 합니다.
export {}

App Config 출력

useAppConfig() 호출 결과의 타입을 지정하고 싶다면, AppConfig를 확장하면 됩니다.

declare module 'nuxt/schema' {
  interface AppConfig {
    // 기존에 추론된 `theme` 속성을 완전히 대체합니다.
    theme: {
      // 이 값을 Nuxt가 추론할 수 있는 것보다 더 구체적인 타입
      // (예: 문자열 리터럴 타입)으로 지정할 수 있습니다.
      primaryColor?: 'red' | 'blue'
    }
  }
}

// 타입을 보강할 때는 항상 무언가를 import/export 해야 합니다.
export {}

병합 전략

Nuxt는 애플리케이션의 레이어 내에서 AppConfig에 대해 커스텀 병합 전략을 사용합니다.

이 전략은 Function Merger를 사용하여 구현되며, 배열 값을 가진 app.config의 각 키에 대해 커스텀 병합 전략을 정의할 수 있습니다.

다음은 사용 예시입니다:

export default defineAppConfig({
  // 기본 배열 값
  array: ['hello'],
})

export default defineAppConfig({
  // 병합 함수로 기본 배열 값을 덮어쓰기
  array: () => ['bonjour'],
})

알려진 제한 사항

Nuxt v3.3 기준으로, app.config.ts 파일은 Nitro와 공유되며, 다음과 같은 제한 사항이 있습니다:

1. app.config.ts에서 Vue 컴포넌트를 직접 import할 수 없습니다.
2. 일부 자동 import가 Nitro 컨텍스트에서는 사용할 수 없습니다.

이러한 제한은 Nitro가 앱 구성을 전체 Vue 컴포넌트 지원 없이 처리하기 때문에 발생합니다.

우회 방법으로 Nitro 구성에서 Vite 플러그인을 사용하는 것이 가능하지만, 이 방법은 권장되지 않습니다:

export default defineNuxtConfig({
  nitro: {
    vite: {
      plugins: [vue()]
    }
  }
})

관련 이슈:

• 이슈 #19858
• 이슈 #19854