설정

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

Nuxt 설정

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

최소한의 설정 파일은 구성 객체를 포함하는 defineNuxtConfig 함수를 내보냅니다. defineNuxtConfig 헬퍼는 import 없이 전역적으로 사용할 수 있습니다.

export default defineNuxtConfig({
  // 내 Nuxt 설정
})

이 파일은 문서에서 자주 언급되며, 예를 들어 커스텀 스크립트 추가, 모듈 등록 또는 렌더링 모드 변경 등에 사용됩니다.

환경별 오버라이드

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.config.ts 파일은 소스 디렉터리(기본적으로 프로젝트의 루트)에 위치하며, 빌드 시점에 결정될 수 있는 공개 변수를 노출하는 데 사용됩니다. runtimeConfig 옵션과 달리, 이 값들은 환경 변수를 사용하여 오버라이드할 수 없습니다.

최소한의 설정 파일은 구성 객체를 포함하는 defineAppConfig 함수를 내보냅니다. 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 파일에서 할 수 있습니다.

• vite.vue는 @vitejs/plugin-vue용입니다. 사용 가능한 옵션을 확인하세요.
• vite.vueJsx는 @vitejs/plugin-vue-jsx용입니다. 사용 가능한 옵션을 확인하세요.

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로 이동되었으며, Nuxt 통합이 제공됩니다.