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에 접근할 수 있습니다.

const appConfig = useAppConfig()

console.log(appConfig.theme)

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

const appConfig = useAppConfig() // { foo: 'bar' }

const newAppConfig = { foo: 'baz' }

updateAppConfig(newAppConfig)

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

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

알려진 제한 사항

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

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

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

Nitro 설정에서 Vite 플러그인을 사용하는 것이 해결책이 될 수 있지만, 이 접근 방식은 권장되지 않습니다:

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

관련 이슈:

• Issue #19858
• Issue #19854