Nuxt 설정 runtimeConfig vs app.config 완전 정복

Nuxt 3는 유연한 설정 구조를 가지고 있습니다. 프로젝트 전역 설정을 정의할 때 가장 많이 쓰이는 두 가지는 다음과 같습니다:

• ✅ runtimeConfig: 런타임 동적 설정
• ✅ app.config: 빌드 타임 정적 설정

이 두 설정은 비슷해 보이지만 목적, 생명 주기, 적용 대상이 분명히 다릅니다.
이번 글에서는 이 둘의 차이를 개념부터 실전까지 정리하고, 현업에서의 활용 예시와 실수를 방지하는 팁까지 총망라합니다.

1. runtimeConfig란?

runtimeConfig는 Nuxt에서 환경 변수 및 비밀값을 런타임에 안전하게 처리할 수 있는 방법입니다. 서버 전용 또는 클라이언트 공유 값으로 구분할 수 있으며, .env 파일과 연동해 환경별 설정을 유연하게 처리할 수 있습니다.

🔧 기본 설정 예시

// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      apiBase: '/api',
      darkMode: false // 클라이언트에서도 접근 가능
    },
    secretKey: '123abc', // 서버에서만 접근 가능
  }
})

📌 접근 방식

const config = useRuntimeConfig()

console.log(config.public.apiBase) // ✅ 클라이언트 접근 가능
console.log(config.secretKey)      // ✅ 서버에서만 접근 가능

✅ 활용 예시 (실무 기준)

⚠️ 주의사항

• runtimeConfig는 서버 재시작 없이 변경할 수 없습니다 (즉, 재배포 필요).
• process.env가 아닌 **useRuntimeConfig()**를 꼭 사용해야 합니다.
• 클라이언트에서 접근할 값은 반드시 public 하위로 지정해야 합니다.

2. app.config.ts란?

app.config.ts는 Nuxt 3에서 정적인 앱 전역 설정을 정의하기 위한 공식 방법입니다. 이 설정은 빌드 시점에 결정되며, 타입 추론이 가능하고 Nuxt 전체에서 공유됩니다.

🔧 설정 예시

// app.config.ts
export default defineAppConfig({
  darkMode: true,
  siteName: 'My Nuxt Blog',
  layoutMode: 'boxed',
  theme: {
    primaryColor: '#1e40af'
  }
})

📌 접근 방식

const config = useAppConfig()

console.log(config.darkMode) // true

✅ 활용 예시

⚠️ 주의사항

• 설정값 변경 시 빌드 다시 해야 반영됩니다 (정적 설정이기 때문).
• .env 값을 가져와 app.config.ts에 쓸 수는 없습니다.
• 컴포넌트나 훅 안에서 useAppConfig()로 접근해야 합니다.

3. 비교 요약: 언제 무엇을 써야 할까?

4. 다크모드 전역 설정 적용 예시

다크모드를 전역 설정으로 넣고, 이를 전 컴포넌트에서 반영하려면 app.config.ts가 적합합니다.

📄 app.config.ts

export default defineAppConfig({
  darkMode: true,
  theme: {
    primary: '#1e293b',
    darkBackground: '#0f172a',
  }
})

🎨 TailwindCSS와 연동 예시 (다크 모드 적용)

<script setup>
const config = useAppConfig()
</script>

<template>
  <div :class="{ 'dark': config.darkMode }" class="bg-white dark:bg-gray-900 text-black dark:text-white">
    <h1>Hello Dark Mode</h1>
  </div>
</template>

✅ 추가 실전 팁

• Tailwind에서는 darkMode: 'class'로 설정해야 위 예시가 정상 작동합니다.
• app.config.ts를 활용하면 레이아웃, 색상 시스템, 버튼 스타일 등을 한 곳에서 컨트롤할 수 있어 디자인 시스템과 궁합이 좋습니다.

5. 실무 기준으로 구성된 설정 예시

// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      apiBase: process.env.NUXT_PUBLIC_API_BASE || '/api',
      version: process.env.NUXT_PUBLIC_APP_VERSION || '1.0.0',
    },
    secretKey: process.env.NUXT_SECRET_KEY
  }
})

// app.config.ts
export default defineAppConfig({
  darkMode: true,
  language: 'ko',
  ui: {
    layout: 'sidebar',
    theme: {
      color: '#06b6d4',
      fontFamily: 'Inter, sans-serif'
    }
  }
})

6. 고급 활용: app.config 타입 확장하기

Nuxt는 app.config에 자동으로 타입을 추론하지만, 직접 타입 선언을 확장할 수 있습니다.

// types/app.config.d.ts
declare module 'nuxt/schema' {
  interface AppConfigInput {
    ui?: {
      layout?: 'full' | 'sidebar'
      theme?: {
        color?: string
        fontFamily?: string
      }
    }
  }
}

// nuxt.config.ts
import { defineNuxtConfig } from 'nuxt/config'

export default defineNuxtConfig({
  // config...
})

이렇게 하면 VS Code에서 app.config.ts의 값도 완전하게 타입 추론됩니다.

✅ 마무리 정리

• runtimeConfig: 외부 API 주소, 보안 키, 환경 구분 설정 등에 사용
• app.config: UI 테마, 전역 설정, 디자인 시스템 구성 등 고정된 설정값에 사용
• 유동적인 값은 runtimeConfig, 고정 전역 값은 app.config

💡 실무에서의 설정 전략 팁

1. 다크모드, 언어, 테마, 레이아웃 등은 app.config에 넣어야 유지보수가 편함
2. 외부와 연결되는 값은 무조건 runtimeConfig에 정의하고 .env에서 관리
3. app.config.ts는 전역 설정만. 로컬 페이지/컴포넌트 전용 값은 피함
4. 모든 설정은 타입 기반으로 관리 → DX, 자동 완성, 오류 방지에 큰 도움

🔚 참고 문서

• Nuxt 3 공식 문서 – Runtime Config
• Nuxt 3 공식 문서 – App Config