설정

기본적으로 Nuxt는 대부분의 사용 사례를 포괄하도록 설정되어 있습니다. nuxt.config.ts 파일은 이 기본 설정을 재정의하거나 확장할 수 있습니다.

Nuxt 설정

nuxt.config.ts 파일은 Nuxt 프로젝트의 루트에 위치하며 애플리케이션의 동작을 재정의하거나 확장할 수 있습니다.

최소 설정 파일은 설정이 포함된 객체를 담고 있는 defineNuxtConfig 함수를 export 합니다. defineNuxtConfig 헬퍼는 import 없이 전역에서 사용할 수 있습니다.

export default defineNuxtConfig({
  // My Nuxt config
})

이 파일은 예를 들어 커스텀 스크립트를 추가하거나, 모듈을 등록하거나, 렌더링 모드를 변경하는 등의 목적으로 문서에서 자주 언급됩니다.

환경별 재정의

nuxt.config에서 완전한 타입 지원을 갖춘 환경별 재정의를 설정할 수 있습니다.

export default defineNuxtConfig({
  $production: {
    routeRules: {
      '/**': { isr: true },
    },
  },
  $development: {
    //
  },
  $env: {
    staging: {
      //
    },
  },
})

Nuxt CLI 명령을 실행할 때 환경을 선택하려면, --envName 플래그에 이름을 전달하면 됩니다. 예: nuxt build --envName staging.

이러한 재정의 뒤에 있는 메커니즘에 대해 더 알아보려면, 환경별 설정에 대한 c12 문서를 참고하세요.

환경 변수와 비공개 토큰

runtimeConfig API는 환경 변수와 같은 값을 애플리케이션의 나머지 부분에 노출합니다. 기본적으로 이 키들은 서버 사이드에서만 사용할 수 있습니다. runtimeConfig.public 및 Nuxt 내부적으로 사용되는 runtimeConfig.app 내의 키는 클라이언트 사이드에서도 사용할 수 있습니다.

이 값들은 nuxt.config에서 정의해야 하며, 환경 변수를 사용해 재정의할 수 있습니다.

export default defineNuxtConfig({
  runtimeConfig: {
    // 서버 사이드에서만 사용할 수 있는 비공개 키
    apiSecret: '123',
    // public 안의 키는 클라이언트 사이드에도 노출됩니다
    public: {
      apiBase: '/api',
    },
  },
})

# 이 값은 apiSecret 값을 재정의합니다
NUXT_API_SECRET=api_secret_token

이 변수들은 useRuntimeConfig() 컴포저블을 사용해 애플리케이션의 나머지 부분에 노출됩니다.

<script setup lang="ts">
const runtimeConfig = useRuntimeConfig()
</script>

앱 설정

기본적으로 소스 디렉터리(app/)에 위치한 app.config.ts 파일은 빌드 시점에 결정될 수 있는 공개 변수를 노출하는 데 사용됩니다. runtimeConfig 옵션과 달리, 이 값들은 환경 변수를 사용해 재정의할 수 없습니다.

최소 설정 파일은 설정이 포함된 객체를 담고 있는 defineAppConfig 함수를 export 합니다. defineAppConfig 헬퍼는 import 없이 전역에서 사용할 수 있습니다.

export default defineAppConfig({
  title: 'Hello Nuxt',
  theme: {
    dark: true,
    colors: {
      primary: '#ff0000',
    },
  },
})

이 변수들은 useAppConfig 컴포저블을 사용해 애플리케이션의 나머지 부분에 노출됩니다.

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

runtimeConfig vs. app.config

앞에서 언급했듯이, runtimeConfig와 app.config는 모두 애플리케이션의 나머지 부분에 변수를 노출하는 데 사용됩니다. 어느 것을 사용해야 할지 결정하기 위한 가이드라인은 다음과 같습니다:

• runtimeConfig: 빌드 이후 환경 변수를 사용해 지정해야 하는 비공개 또는 공개 토큰.
• app.config: 빌드 시점에 결정되는 공개 토큰, 테마 종류, 제목 및 민감하지 않은 기타 프로젝트 설정과 같은 웹사이트 설정.

외부 설정 파일

Nuxt는 설정에 대한 단일 진실 공급원으로 nuxt.config.ts 파일을 사용하며, 외부 설정 파일을 읽는 것을 건너뜁니다. 프로젝트를 빌드하는 과정에서 이러한 파일을 설정해야 할 필요가 있을 수 있습니다. 아래 표는 일반적인 설정과, 해당되는 경우 Nuxt에서 이를 설정하는 방법을 보여줍니다.

다음은 다른 일반적인 설정 파일 목록입니다:

Vue 설정

Vite 사용 시

@vitejs/plugin-vue 또는 @vitejs/plugin-vue-jsx에 옵션을 전달해야 하는 경우, nuxt.config 파일에서 이를 설정할 수 있습니다.

• @vitejs/plugin-vue의 경우 vite.vue. 사용 가능한 옵션을 확인하세요.
• @vitejs/plugin-vue-jsx의 경우 vite.vueJsx. 사용 가능한 옵션을 확인하세요.

export default defineNuxtConfig({
  vite: {
    vue: {
      customElement: true,
    },
    vueJsx: {
      mergeProps: true,
    },
  },
})

webpack 사용 시

webpack을 사용하고 vue-loader를 설정해야 하는 경우, nuxt.config 파일 안에서 webpack.loaders.vue 키를 사용해 설정할 수 있습니다. 사용 가능한 옵션은 여기에 정의되어 있습니다.

export default defineNuxtConfig({
  webpack: {
    loaders: {
      vue: {
        hotReload: true,
      },
    },
  },
})

실험적인 Vue 기능 활성화

propsDestructure와 같은 Vue의 실험적인 기능을 활성화해야 할 수 있습니다. Nuxt는 사용 중인 빌더와 관계없이 nuxt.config.ts에서 이를 쉽게 활성화할 수 있는 방법을 제공합니다:

export default defineNuxtConfig({
  vue: {
    propsDestructure: true,
  },
})

Vue 3.4 및 Nuxt 3.9에서의 실험적 reactivityTransform 마이그레이션

Nuxt 3.9와 Vue 3.4부터 reactivityTransform은 Vue에서 Vue Macros로 이동되었으며, Vue Macros는 Nuxt 통합을 제공합니다.