Nuxt 설정

nuxt.config.ts 파일에서 사용할 수 있는 모든 옵션을 확인하세요.

이 페이지는 Nuxt 소스 코드로 자동 생성되는 문서를 v3.17 (2025-06-29) 기준으로 수동 번역하였습니다. (nuxt 업데이트 여부에 따라 구성값이 다를 수 있습니다.)

alias

JavaScript 및 CSS 내에서 커스텀 디렉토리에 접근할 수 있도록 추가 별칭을 정의하여 DX(개발자 경험)를 향상시킬 수 있습니다.

타입: object
기본값

{
  "~": "/<srcDir>",
  "@": "/<srcDir>",
  "~~": "/<rootDir>",
  "@@": "/<rootDir>",
  "#shared": "/<rootDir>/shared",
  "assets": "/<srcDir>/assets",
  "public": "/<srcDir>/public",
  "#build": "/<rootDir>/.nuxt",
  "#internal/nuxt/paths": "/<rootDir>/.nuxt/paths.mjs"
}

참고: webpack 컨텍스트(이미지 소스, CSS - JavaScript는 제외) 내에서는 별칭 앞에 ~를 붙여서 접근해야 합니다.

참고: 이 별칭들은 자동으로 생성된 .nuxt/tsconfig.json에 추가되어 전체 타입 지원과 경로 자동 완성을 제공합니다. 만약 ./.nuxt/tsconfig.json에서 제공하는 옵션을 더 확장해야 한다면, 여기나 nuxt.config의 typescript.tsConfig 속성 내에 추가하세요.

예시:

export default {
  alias: {
    'images': fileURLToPath(new URL('./assets/images', import.meta.url)),
    'style': fileURLToPath(new URL('./assets/style', import.meta.url)),
    'data': fileURLToPath(new URL('./assets/other/data', import.meta.url))
  }
}

analyzeDir

nuxt analyze를 실행할 때 Nuxt가 생성된 파일을 저장할 디렉토리입니다.

상대 경로를 지정하면 rootDir을 기준으로 합니다.

타입: string
기본값: "/<rootDir>/.nuxt/analyze"

app

Nuxt 앱 설정.

`baseURL`

Nuxt 애플리케이션의 기본 경로입니다.

예시:

타입: string
기본값: "/"

예시:

export default defineNuxtConfig({
  app: {
    baseURL: '/prefix/'
  }
})

예시:

NUXT_APP_BASE_URL=/prefix/ node .output/server/index.mjs

`buildAssetsDir`

빌드된 사이트 에셋의 폴더 이름입니다. baseURL(또는 설정된 경우 cdnURL)을 기준으로 상대 경로입니다. 이 값은 빌드 시에만 설정되며 런타임에 커스터마이즈해서는 안 됩니다.

타입: string
기본값: "/_nuxt/"

`cdnURL`

public 폴더를 제공할 절대 URL(프로덕션 전용)입니다.

예시:

타입: string
기본값: ""

예시:

export default defineNuxtConfig({
  app: {
    cdnURL: 'https://mycdn.org/'
  }
})

예시:

NUXT_APP_CDN_URL=https://mycdn.org/ node .output/server/index.mjs

`head`

모든 페이지의 <head>에 대한 기본 설정을 지정합니다.

타입: object
기본값

{
  "meta": [
    {
      "name": "viewport",
      "content": "width=device-width, initial-scale=1"
    },
    {
      "charset": "utf-8"
    }
  ],
  "link": [],
  "style": [],
  "script": [],
  "noscript": []
}

예시:

app: {
  head: {
    meta: [
      // <meta name="viewport" content="width=device-width, initial-scale=1">
      { name: 'viewport', content: 'width=device-width, initial-scale=1' }
    ],
    script: [
      // <script src="https://myawesome-lib.js"></script>
      { src: 'https://awesome-lib.js' }
    ],
    link: [
      // <link rel="stylesheet" href="https://myawesome-lib.css">
      { rel: 'stylesheet', href: 'https://awesome-lib.css' }
    ],
    // 이 영역은 변경될 가능성이 있습니다
    style: [
      // <style>:root { color: red }</style>
      { textContent: ':root { color: red }' }
    ],
    noscript: [
      // <noscript>JavaScript is required</noscript>
      { textContent: 'JavaScript is required' }
    ]
  }
}

`keepalive`

페이지 간 KeepAlive 설정의 기본값입니다.

개별 페이지에서 definePageMeta로 덮어쓸 수 있습니다. JSON 직렬화 가능한 값만 허용됩니다.

타입: boolean
기본값: false

참고: Vue KeepAlive

`layoutTransition`

레이아웃 전환의 기본값입니다.

개별 페이지에서 definePageMeta로 덮어쓸 수 있습니다. JSON 직렬화 가능한 값만 허용됩니다.

타입: boolean
기본값: false

참고: Vue 전환 문서

`pageTransition`

페이지 전환의 기본값입니다.

개별 페이지에서 definePageMeta로 덮어쓸 수 있습니다. JSON 직렬화 가능한 값만 허용됩니다.

타입: boolean
기본값: false

참고: Vue 전환 문서

`rootAttrs`

Nuxt 루트 요소의 id를 커스터마이즈합니다.

타입: object
기본값

{
  "id": "__nuxt"
}

`rootId`

Nuxt 루트 요소의 id를 커스터마이즈합니다.

타입: string
기본값: "__nuxt"

`rootTag`

Nuxt 루트 요소의 태그를 커스터마이즈합니다.

타입: string
기본값: "div"

`spaLoaderAttrs`

Nuxt SpaLoader 요소의 속성을 커스터마이즈합니다.

`spaLoaderTag`

Nuxt SpaLoader 요소의 태그를 커스터마이즈합니다.

타입: string
기본값: "div"

`teleportAttrs`

Nuxt Teleport 요소의 속성을 커스터마이즈합니다.

타입: object
기본값

{
  "id": "teleports"
}

`teleportId`

Nuxt Teleport 요소의 id를 커스터마이즈합니다.

타입: string
기본값: "teleports"

`teleportTag`

Nuxt Teleport 요소의 태그를 커스터마이즈합니다.

타입: string
기본값: "div"

`viewTransition`

뷰 전환의 기본값입니다.

이 옵션은 실험적인 View Transitions 지원이 nuxt.config 파일에서 활성화된 경우에만 효과가 있습니다. 개별 페이지에서 definePageMeta로 덮어쓸 수 있습니다.

타입: boolean
기본값: false

참고: Nuxt View Transition API 문서

appConfig

추가 앱 설정

프로그래밍 방식 사용 및 타입 지원을 위해 이 옵션으로 앱 설정을 직접 제공할 수 있습니다. 기본값으로 app.config 파일과 병합됩니다.

appId

멀티 앱 프로젝트의 경우 Nuxt 애플리케이션의 고유 id입니다.

기본값은 nuxt-app입니다.

타입: string
기본값: "nuxt-app"

build

공유 빌드 설정.

`analyze`

Nuxt는 번들을 시각화하고 최적화 방법을 제공합니다.

true로 설정하면 번들 분석이 활성화되며, 옵션 객체를 전달할 수도 있습니다: webpack용 옵션 또는 vite용 옵션.

타입: object
기본값

{
  "template": "treemap",
  "projectRoot": "/<rootDir>",
  "filename": "/<rootDir>/.nuxt/analyze/{name}.html"
}

예시:

analyze: {
  analyzerMode: 'static'
}

`templates`

이 옵션 대신 @nuxt/kit의 addTemplate 사용을 권장합니다.

타입: array

예시:

templates: [
  {
    src: '~/modules/support/plugin.js', // `src`는 절대 또는 상대 경로 모두 가능
    dst: 'support.js', // `dst`는 프로젝트 `.nuxt` 디렉토리 기준 상대 경로
  }
]

`transpile`

특정 의존성을 Babel로 트랜스파일하려면 여기에 추가할 수 있습니다. transpile의 각 항목은 패키지 이름, 함수, 문자열 또는 의존성 파일 이름과 일치하는 정규식 객체일 수 있습니다.

함수를 사용하여 조건부로 트랜스파일할 수도 있습니다. 함수는 객체({ isDev, isServer, isClient, isModern, isLegacy })를 인자로 받습니다.

타입: array

예시:

transpile: [({ isLegacy }) => isLegacy && 'ky']

buildDir

빌드된 Nuxt 파일이 저장될 디렉토리를 정의합니다.

많은 도구들이 .nuxt가 숨김 디렉토리(점으로 시작하기 때문에)라고 가정합니다. 문제가 된다면 이 옵션을 사용하여 방지할 수 있습니다.

타입: string
기본값: "/<rootDir>/.nuxt"

예시:

export default {
  buildDir: 'nuxt-build'
}

buildId

빌드와 일치하는 고유 식별자입니다. 현재 프로젝트 상태의 해시가 포함될 수 있습니다.

타입: string
기본값: "f2edd0e7-2595-424c-bd97-c91196e3f2d2"

builder

애플리케이션의 Vue 부분을 번들링할 때 사용할 빌더입니다.

타입: string
기본값: "@nuxt/vite-builder"

compatibilityDate

앱의 호환성 날짜를 지정합니다.

이 옵션은 Nitro, Nuxt Image 및 기타 모듈에서 프리셋 동작을 제어하는 데 사용됩니다. 향후 이 기능에 대한 도구를 개선할 예정입니다.

css

글로벌로 설정할 CSS 파일/모듈/라이브러리를 정의할 수 있습니다(모든 페이지에 포함됨).

Nuxt는 확장자를 통해 파일 타입을 자동으로 추측하고 적절한 전처리기를 사용합니다. 필요하다면 해당 로더를 직접 설치해야 합니다.

타입: array

예시:

css: [
  // Node.js 모듈을 직접 로드(여기서는 Sass 파일)
  'bulma',
  // 프로젝트 내 CSS 파일
  '~/assets/css/main.css',
  // 프로젝트 내 SCSS 파일
  '~/assets/css/main.scss'
]

debug

true로 설정하면 디버그 모드가 활성화됩니다.

현재는 서버에서 훅 이름과 타이밍을 출력하고, 브라우저에서는 훅 인자도 로그로 남깁니다. 특정 디버그 옵션만 활성화하려면 객체로 설정할 수도 있습니다.

타입: boolean
기본값: false

dev

Nuxt가 개발 모드로 실행 중인지 여부입니다.

일반적으로 이 값을 설정할 필요는 없습니다.

타입: boolean
기본값: false

devServer

`cors`

개발 서버의 CORS 옵션 설정

`origin`

타입: array
기본값

[
  {}
]

`https`

HTTPS 활성화 여부.

타입: boolean
기본값: false

예시:

export default defineNuxtConfig({
  devServer: {
    https: {
      key: './server.key',
      cert: './server.crt'
    }
  }
})

`port`

개발 서버가 리스닝할 포트

타입: number
기본값: 3000

`url`

개발 서버의 리스닝 URL.

이 값은 직접 설정하지 않아야 하며, 항상 개발 서버에 의해 전체 URL로 덮어써집니다(모듈 및 내부 용도).

타입: string
기본값: "http://localhost:3000"

devServerHandlers

Nitro 개발 전용 서버 핸들러.

타입: array

참고: Nitro 서버 라우트 문서

devtools

개발을 위한 Nuxt DevTools 활성화.

devtools의 주요 변경 사항은 Nuxt 버전에 반영되지 않을 수 있습니다.

참고: Nuxt DevTools에서 자세한 정보를 확인하세요.

dir

Nuxt에서 사용하는 기본 디렉토리 구조를 커스터마이즈합니다.

필요하지 않다면 기본값을 사용하는 것이 좋습니다.

`assets`

에셋 디렉토리(~assets로 별칭 처리됨).

타입: string
기본값: "assets"

`layouts`

레이아웃 디렉토리. 각 파일이 Nuxt 레이아웃으로 자동 등록됩니다.

타입: string
기본값: "layouts"

`middleware`

미들웨어 디렉토리. 각 파일이 Nuxt 미들웨어로 자동 등록됩니다.

타입: string
기본값: "middleware"

`modules`

모듈 디렉토리. 각 파일이 Nuxt 모듈로 자동 등록됩니다.

타입: string
기본값: "modules"

`pages`

애플리케이션 페이지 라우트를 자동 생성할 디렉토리입니다.

타입: string
기본값: "pages"

`plugins`

플러그인 디렉토리. 각 파일이 Nuxt 플러그인으로 자동 등록됩니다.

타입: string
기본값: "plugins"

`public`

정적 파일이 포함된 디렉토리. Nuxt 서버를 통해 직접 접근 가능하며, 앱이 생성될 때 dist 폴더로 복사됩니다.

타입: string
기본값: "public"

`shared`

공유 디렉토리. 이 디렉토리는 앱과 서버 간에 공유됩니다.

타입: string
기본값: "shared"

esbuild

`options`

Nuxt 내에서 사용되고 Vite 또는 Webpack과 같은 다른 빌더에 전달되는 esbuild 옵션을 설정합니다.

experimental

`alwaysRunFetchOnKeyChange`

키가 변경될 때 useFetch를 실행할지 여부입니다. immediate: false로 설정되어 있고 아직 트리거되지 않은 경우에도 실행됩니다.

immediate: true이거나 이미 트리거된 경우, 키가 변경되면 useFetch와 useAsyncData는 항상 실행됩니다.

타입: boolean
기본값: true

`appManifest`

클라이언트 측에서 라우트 규칙을 준수하기 위해 앱 매니페스트를 사용합니다.

타입: boolean
기본값: true

`asyncContext`

중첩된 컴포저블에서 네이티브 async context에 접근할 수 있도록 활성화합니다.

타입: boolean
기본값: false

참고: Nuxt PR #20918

`asyncEntry`

Vue 번들을 위한 async entry point를 생성하려면 true로 설정하세요(모듈 연합 지원용).

타입: boolean
기본값: false

`browserDevtoolsTiming`

Chromium 기반 브라우저의 성능 패널에서 Nuxt 애플리케이션 훅의 타이밍을 활성화합니다.

이 기능은 Nuxt 훅에 대한 성능 마커를 추가하여 브라우저의 Performance 탭에서 실행 시간을 추적할 수 있게 해줍니다. 성능 문제를 디버깅할 때 특히 유용합니다.

타입: boolean
기본값: false

예시:

// nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    // 브라우저 devtools에서 Nuxt 훅의 성능 마커 활성화
    browserDevtoolsTiming: true
  }
})

참고: PR #29922

참고: Chrome DevTools Performance API

`buildCache`

설정 및 소스 파일의 해시를 기반으로 Nuxt/Nitro 빌드 아티팩트를 캐시합니다.

이 기능은 앱의 Vue/Nitro 부분에 대해 srcDir 및 serverDir 내의 소스 파일에만 작동합니다.

타입: boolean
기본값: false

`checkOutdatedBuildInterval`

새 빌드를 확인하는 시간 간격(ms 단위)을 설정합니다. experimental.appManifest가 false일 때는 비활성화됩니다.

false로 설정하면 비활성화됩니다.

타입: number
기본값: 3600000

`clientFallback`

SSR에서 오류가 발생할 경우 클라이언트에서 콘텐츠를 렌더링하는 실험적 <NuxtClientFallback> 컴포넌트 활성화 여부입니다.

타입: boolean
기본값: false

`clientNodeCompat`

클라이언트 빌드에서 unenv를 사용하여 Node.js import를 자동으로 폴리필합니다.

타입: boolean
기본값: false

참고: unenv

`compileTemplate`

Nuxt 템플릿을 컴파일할 때 lodash.template을 사용할지 여부입니다.

이 플래그는 v4 릴리스와 함께 제거될 예정이며, Nuxt v3.12+ 또는 nightly 릴리스 채널에서 고급 테스트용으로만 존재합니다.

타입: boolean
기본값: true

`componentIslands`

<NuxtIsland> 및 .island.vue 파일을 통한 실험적 컴포넌트 아일랜드 지원.

기본값은 'auto'로, 앱에 아일랜드, 서버 컴포넌트 또는 서버 페이지가 있을 때만 활성화됩니다.

타입: string
기본값: "auto"

`configSchema`

설정 스키마 지원

타입: boolean
기본값: true

참고: Nuxt 이슈 #15592

`cookieStore`

브라우저에서 지원하는 경우 쿠키 업데이트를 감지하고 useCookie ref 값을 새로고침하기 위해 CookieStore 지원을 활성화합니다.

타입: boolean
기본값: true

참고: CookieStore

`crossOriginPrefetch`

Speculation Rules API를 사용하여 교차 출처 prefetch를 활성화합니다.

타입: boolean
기본값: false

`decorators`

Nuxt 및 Nitro에서 실험적 데코레이터 사용을 활성화합니다.

타입: boolean
기본값: false

참고: https://github.com/tc39/proposal-decorators

`defaults`

핵심 Nuxt 컴포넌트 및 컴포저블의 기본 옵션을 지정할 수 있습니다.

이 옵션들은 향후 app.config 또는 app/ 디렉토리로 이동될 가능성이 높습니다.

`nuxtLink`

`useAsyncData`

useAsyncData(따라서 useFetch에도 적용) 옵션

`emitRouteChunkError`

vite/webpack 청크 로딩 오류가 발생할 때 app:chunkError 훅을 발생시킵니다.

기본적으로 Nuxt는 새 라우트로 이동할 때 청크 로딩에 실패하면 새 라우트를 리로드합니다(automatic). automatic-immediate로 설정하면 청크 로딩에 실패하자마자 현재 라우트를 즉시 리로드합니다(이동을 기다리지 않음). 자동 처리를 비활성화하려면 false로, 수동으로 청크 오류를 처리하려면 manual로 설정하세요.

타입: string
기본값: "automatic"

참고: Nuxt PR #19038

`enforceModuleCompatibility`

Nuxt 모듈이 호환되지 않을 경우 Nuxt가 중단할지 여부입니다.

타입: boolean
기본값: false

`externalVue`

빌드 시 vue, @vue/*, vue-router를 외부화합니다.

타입: boolean
기본값: true

참고: Nuxt 이슈 #13632

`extraPageMetaExtractionKeys`

scanPageMeta 사용 시 페이지 메타데이터에서 추출할 추가 키를 설정합니다.

이 옵션을 통해 모듈이 페이지 메타데이터에서 추가 메타데이터에 접근할 수 있습니다. 자신의 키로 NuxtPage 타입을 확장하는 것이 좋습니다.

타입: array

`granularCachedData`

useAsyncData 및 useFetch의 수동 새로고침 시 getCachedData의 결과를 호출하고 사용할지 여부입니다.

타입: boolean
기본값: false

`headNext`

새로운 실험적 head 최적화 사용:

capo.js head 플러그인을 추가하여 head의 태그를 더 효율적으로 렌더링합니다. - 초기 하이드레이션을 줄이기 위해 hash hydration 플러그인 사용
타입: boolean
기본값: true

참고: Nuxt Discussion #22632

`inlineRouteRules`

~/pages 디렉토리 내에서 defineRouteRules를 사용하여 routeRules를 직접 정의할 수 있도록 허용합니다.

규칙은(경로를 기준으로) 변환되어 서버 요청에 적용됩니다. 예를 들어, ~/pages/foo/bar.vue에 정의된 규칙은 /foo/bar 요청에 적용됩니다. ~/pages/foo/[id].vue에 정의된 규칙은 /foo/** 요청에 적용됩니다. 페이지의 definePageMeta에서 커스텀 path 또는 alias를 사용하는 등 더 많은 제어가 필요하다면, nuxt.config 내에서 직접 routeRules를 설정하세요.

타입: boolean
기본값: false

`lazyHydration`

<Lazy> 컴포넌트의 하이드레이션 전략을 자동으로 구성하는 기능을 활성화합니다.

이 기능은 Lazy 컴포넌트의 가시성, 유휴 시간 또는 기타 트리거를 기반으로 하이드레이션 시점을 지능적으로 결정하여, 컴포넌트가 필요할 때까지 하이드레이션을 지연시켜 성능을 향상시킵니다.

타입: boolean
기본값: true

예시:

// nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    lazyHydration: true // Lazy 컴포넌트에 대한 스마트 하이드레이션 전략 활성화
  }
})

// Vue 컴포넌트 내에서
<template>
  <Lazy>
    <ExpensiveComponent />
  </Lazy>
</template>

참고: PR #26468

`localLayerAliases`

레이어 내에서 ~, ~~, @, @@ 별칭을 해당 레이어의 소스 및 루트 디렉토리를 기준으로 해석합니다.

타입: boolean
기본값: true

`navigationRepaint`

네비게이션 전에 한 번의 애니메이션 프레임을 대기하여 브라우저가 사용자 상호작용을 인식하고 리페인트할 기회를 제공합니다.

프리렌더된 라우트에서 네비게이션 시 INP를 줄일 수 있습니다.

타입: boolean
기본값: true

`noVueServer`

nitro 내에서 vue 서버 렌더러 엔드포인트를 비활성화합니다.

타입: boolean
기본값: false

`normalizeComponentNames`

자동 생성된 Vue 컴포넌트 이름이 컴포넌트를 자동 import할 때 사용할 전체 컴포넌트 이름과 일치하도록 보장합니다.

타입: boolean
기본값: false

`parseErrorData`

서버 오류 페이지 렌더링 시 error.data를 파싱할지 여부입니다.

타입: boolean
기본값: false

`payloadExtraction`

이 옵션이 활성화(기본값)되면 프리렌더된 페이지의 payload가 추출됩니다.

타입: boolean
기본값: true

`pendingWhenIdle`

useAsyncData 및 useFetch에서 데이터가 아직 가져오기 시작되지 않은 경우 pending이 true가 될지 여부입니다.

타입: boolean
기본값: true

`polyfillVueUseHead`

모듈, 플러그인 또는 사용자 코드가 이전 @vueuse/head API에 의존하는 경우 호환성 계층을 추가할지 여부입니다.

이 옵션은 클라이언트 번들을 약 0.5kb 줄이기 위해 비활성화되어 있습니다.

타입: boolean
기본값: false

`purgeCachedData`

라우트 네비게이션 시 Nuxt static 및 asyncData 캐시를 정리할지 여부입니다.

Nuxt는 useAsyncData 및 nuxtApp.static.data의 캐시 데이터를 자동으로 정리합니다. 이는 메모리 누수를 방지하고 필요한 경우 신선한 데이터를 로드하는 데 도움이 되지만, 비활성화할 수도 있습니다.

타입: boolean
기본값: true

예시:

// nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    // 자동 캐시 정리 비활성화(기본값은 true)
    purgeCachedData: false
  }
})

참고: PR #31379

`relativeWatchPaths`

builder:watch 훅에서 상대 경로를 제공할지 여부입니다.

이 플래그는 v4 릴리스와 함께 제거될 예정이며, Nuxt v3.12+ 또는 nightly 릴리스 채널에서 고급 테스트용으로만 존재합니다.

타입: boolean
기본값: true

`renderJsonPayloads`

복잡한 타입의 복원을 지원하는 JSON payload 렌더링.

타입: boolean
기본값: true

`resetAsyncDataToUndefined`

clear 및 clearNuxtData가 async data를 기본값으로 재설정할지, 아니면 null/undefined로 업데이트할지 여부입니다.

타입: boolean
기본값: true

`respectNoSSRHeader`

x-nuxt-no-ssr 헤더를 설정하여 Nuxt SSR 응답을 비활성화할 수 있도록 허용합니다.

타입: boolean
기본값: false

`restoreState`

청크 오류 또는 수동 reloadNuxtApp() 호출 후 페이지를 새로고침할 때 Nuxt 앱 상태를 sessionStorage에서 복원할지 여부입니다.

하이드레이션 오류를 방지하기 위해 Vue 앱이 마운트된 후에만 적용되므로 초기 로드 시 깜빡임이 있을 수 있습니다. 예상치 못한 동작을 유발할 수 있으므로 신중히 활성화하세요. 또한 자동 생성된 키가 빌드마다 일치하지 않을 수 있으므로 useState에 명시적 키를 제공하는 것이 좋습니다.

타입: boolean
기본값: false

`scanPageMeta`

빌드 시 definePageMeta에 정의된 일부 라우트 메타데이터(alias, name, path, redirect, props, middleware)를 모듈에 노출할 수 있도록 허용합니다.

이 기능은 변수나 조건부 할당이 아닌 정적 값 또는 문자열/배열에만 작동합니다.

타입: boolean
기본값: true

참고: Nuxt 이슈 #24770

`sharedPrerenderData`

프리렌더된 페이지 간에 payload data를 자동으로 공유합니다. 이는 여러 페이지에서 동일한 데이터를 가져오는 useAsyncData 또는 useFetch를 사용하는 사이트를 프리렌더링할 때 성능을 크게 향상시킬 수 있습니다.

이 기능을 활성화할 때는 데이터의 고유 키가 항상 동일한 데이터를 참조할 수 있도록 하는 것이 특히 중요합니다. 예를 들어, 특정 페이지와 관련된 데이터를 가져오기 위해 useAsyncData를 사용하는 경우, 해당 데이터를 고유하게 식별하는 키를 제공해야 합니다. (useFetch는 이를 자동으로 처리합니다.)

타입: boolean
기본값: false

예시:

// 동적 페이지(예: `[slug].vue`)에서 이 코드는 안전하지 않습니다.
// 라우트 슬러그에 따라 가져오는 데이터가 달라지지만, Nuxt는 키에 반영되지 않아 이를 알 수 없습니다.
const route = useRoute()
const { data } = await useAsyncData(async () => {
  return await $fetch(`/api/my-page/${route.params.slug}`)
})
// 대신, 가져오는 데이터를 고유하게 식별하는 키를 사용해야 합니다.
const { data } = await useAsyncData(route.params.slug, async () => {
  return await $fetch(`/api/my-page/${route.params.slug}`)
})

`spaLoadingTemplateLocation`

suspense:resolve까지 spa-loading-template을 계속 표시합니다.

타입: string
기본값: "within"

참고: Nuxt 이슈 #24770

`templateImportResolution`

Nuxt 템플릿 내 import를 템플릿을 추가한 모듈의 경로에서 해석하는 기능을 비활성화합니다.

기본적으로 Nuxt는 템플릿 내 import를 해당 템플릿을 추가한 모듈 기준으로 해석합니다. 이 옵션을 false로 설정하면 이 동작이 비활성화되며, 특정 환경에서 해석 충돌이 발생할 때 유용할 수 있습니다.

타입: boolean
기본값: true

예시:

// nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    // 모듈 경로에서 템플릿 import 해석 비활성화
    templateImportResolution: false
  }
})

참고: PR #31175

`templateRouteInjection`

기본적으로 자동 import된 useRoute() 컴포저블이 반환하는 라우트 객체는 <NuxtPage>에서 현재 페이지와 동기화됩니다. 이는 vue-router에서 export된 useRoute나 Vue 템플릿에서 사용할 수 있는 기본 $route 객체에는 해당되지 않습니다.

이 옵션을 활성화하면 믹스인이 주입되어 Nuxt가 관리하는 useRoute()와 Nuxt의 $route 템플릿 객체를 동기화합니다.

타입: boolean
기본값: true

`templateUtils`

Nuxt 템플릿을 컴파일할 때 레거시 templateUtils 객체(serialize, importName, importSources 포함)를 제공할지 여부입니다.

이 플래그는 v4 릴리스와 함께 제거될 예정이며, Nuxt v3.12+ 또는 nightly 릴리스 채널에서 고급 테스트용으로만 존재합니다.

타입: boolean
기본값: true

`treeshakeClientOnly`

클라이언트 전용 컴포넌트의 내용을 서버 번들에서 트리쉐이킹합니다.

타입: boolean
기본값: true

참고: Nuxt PR #5750

`typedPages`

unplugin-vue-router를 사용한 새로운 실험적 타입드 라우터를 활성화합니다.

타입: boolean
기본값: false

`viewTransition`

클라이언트 사이드 라우터와 View Transition API 통합을 활성화합니다.

타입: boolean
기본값: false

참고: View Transitions API

`watcher`

Nuxt의 감시 서비스로 사용할 대체 watcher를 설정합니다.

소스 디렉토리가 루트 디렉토리와 동일한 경우 Nuxt는 'chokidar-granular'를 사용합니다. 이 경우 node_modules 및 .git과 같은 최상위 디렉토리를 감시에서 제외합니다. 대신 parcel로 설정하면 @parcel/watcher를 사용하여 대규모 프로젝트나 Windows 환경에서 성능이 향상될 수 있습니다. 또는 chokidar로 설정하면 소스 디렉토리의 모든 파일을 감시합니다.

타입: string
기본값: "chokidar"

참고: chokidar

참고: @parcel/watcher

`writeEarlyHints`

노드 서버 사용 시 early hints를 작성합니다.

타입: boolean
기본값: false

참고: nginx는 현재 버전에서 103 Early hints를 지원하지 않습니다.

extends

여러 로컬 또는 원격 소스에서 프로젝트를 확장합니다.

값은 소스 디렉토리 또는 현재 설정 기준의 설정 경로를 가리키는 문자열 또는 문자열 배열이어야 합니다. github:, gh:, gitlab:, bitbucket:을 사용할 수 있습니다.

참고: c12 설정 레이어 확장 문서

참고: giget 문서

extensions

Nuxt 리졸버가 해석해야 하는 확장자입니다.

타입: array
기본값

[
  ".js",
  ".jsx",
  ".mjs",
  ".ts",
  ".tsx",
  ".vue"
]

features

Nuxt의 일부 기능은 선택적으로 활성화하거나 필요에 따라 비활성화할 수 있습니다.

`devLogs`

개발 중 서버 로그를 클라이언트로 스트리밍합니다. 이 로그는 dev:ssr-logs 훅에서 처리할 수 있습니다.

silent로 설정하면 로그가 브라우저 콘솔에 출력되지 않습니다.

타입: boolean
기본값: false

`inlineStyles`

HTML 렌더링 시 스타일을 인라인 처리합니다(현재는 vite만 지원).

Vue 컴포넌트의 경로를 인자로 받아 해당 컴포넌트의 스타일을 인라인할지 여부를 반환하는 함수를 전달할 수도 있습니다.

타입: boolean
기본값: true

`noScripts`

Nuxt 스크립트 및 JS 리소스 힌트 렌더링을 끕니다. routeRules 내에서 더 세밀하게 스크립트를 비활성화할 수도 있습니다.

'production' 또는 true로 설정하면 프로덕션 모드에서만 JS가 비활성화됩니다.

타입: boolean
기본값: false

future

future는 향후(주로 메이저) 프레임워크 버전에서 기본값이 될 새로운 기능을 미리 활성화하기 위한 옵션입니다.

`compatibilityVersion`

Nuxt v4 기능 또는 플래그에 대한 조기 접근을 활성화합니다.

compatibilityVersion을 4로 설정하면 Nuxt 설정 전반에 걸쳐 기본값이 변경되지만, 테스트 시 Nuxt v3 동작을 세밀하게 다시 활성화할 수 있습니다(예시 참조). 이 경우 이슈를 등록해주시면 Nuxt 또는 에코시스템에서 해결하겠습니다.

타입: number
기본값: 3

예시:

export default defineNuxtConfig({
  future: {
    compatibilityVersion: 4,
  },
  // _모든_ Nuxt v3 동작을 다시 활성화하려면 다음 옵션을 설정하세요:
  srcDir: '.',
  dir: {
    app: 'app'
  },
  experimental: {
    compileTemplate: true,
    templateUtils: true,
    relativeWatchPaths: true,
    resetAsyncDataToUndefined: true,
    defaults: {
      useAsyncData: {
        deep: true
      }
    }
  },
  unhead: {
    renderSSRHeadOptions: {
      omitLineBreaks: false
    }
  }
})

`multiApp`

실험적 멀티 앱 지원에 대한 조기 접근을 활성화합니다.

타입: boolean
기본값: false

참고: Nuxt 이슈 #21635

`typescriptBundlerResolution`

TypeScript의 'Bundler' 모듈 해석 모드를 활성화합니다. Nuxt 및 Vite와 같은 프레임워크에 권장되는 설정입니다.

exports를 사용하는 최신 라이브러리 사용 시 타입 지원이 향상됩니다. 기존 TypeScript의 'Node' 모드를 사용하려면 false로 설정하세요(기본값).

타입: boolean
기본값: true

참고: TypeScript PR - bundler 모듈 해석

generate

`exclude`

이 옵션은 더 이상 사용되지 않습니다. 대신 nitro.prerender.ignore를 사용하세요.

타입: array

`routes`

생성할 라우트입니다.

크롤러를 사용하는 경우, 이 값은 라우트 생성의 시작점일 뿐입니다. 동적 라우트를 사용할 때 자주 필요합니다. nitro.prerender.routes 사용을 권장합니다.

타입: array

예시:

routes: ['/users/1', '/users/2', '/users/3']

hooks

훅은 Nuxt 이벤트의 리스너로, 일반적으로 모듈에서 사용되지만 nuxt.config에서도 사용할 수 있습니다.

내부적으로 훅은 콜론(:)을 사용하는 네이밍 패턴을 따릅니다(예: build:done). 설정의 편의를 위해, 아래와 같이 nuxt.config에서 계층적 객체로도 구성할 수 있습니다.

예시:

import fs from 'node:fs'
import path from 'node:path'
export default {
  hooks: {
    build: {
      done(builder) {
        const extraFilePath = path.join(
          builder.nuxt.options.buildDir,
          'extra-file'
        )
        fs.writeFileSync(extraFilePath, 'Something extra')
      }
    }
  }
}

ignore

ignorePrefix보다 더 커스터마이즈가 가능합니다: ignore 배열에 지정된 glob 패턴과 일치하는 모든 파일은 빌드 시 무시됩니다.

타입: array
기본값

[
  "**/*.stories.{js,cts,mts,ts,jsx,tsx}",
  "**/*.{spec,test}.{js,cts,mts,ts,jsx,tsx}",
  "**/*.d.{cts,mts,ts}",
  "**/.{pnpm-store,vercel,netlify,output,git,cache,data}",
  "**/*.sock",
  ".nuxt/analyze",
  ".nuxt",
  "**/-*.*"
]

ignoreOptions

Nuxt가 파일을 무시할 때 사용하는 node-ignore에 옵션을 직접 전달합니다.

참고: node-ignore

예시:

ignoreOptions: {
  ignorecase: false
}

ignorePrefix

pages/, layouts/, middleware/, public/ 디렉토리 내의 파일 이름이 ignorePrefix로 시작하면 빌드 과정에서 무시됩니다. 이는 특정 파일이 빌드된 애플리케이션에서 처리되거나 제공되지 않도록 하기 위함입니다. 기본적으로 ignorePrefix는 '-'로 설정되어, '-'로 시작하는 모든 파일을 무시합니다.

타입: string
기본값: "-"

imports

Nuxt가 컴포저블을 애플리케이션에 자동 import하는 방식을 설정합니다.

참고: Nuxt 문서

`dirs`

자동 import할 커스텀 디렉토리 배열입니다. 이 옵션은 기본 디렉토리(~/composables, ~/utils)를 덮어쓰지 않습니다.

타입: array

예시:

imports: {
  // `~/stores`에 정의된 pinia 스토어 자동 import
  dirs: ['stores']
}

`global`

타입: boolean
기본값: false

`scan`

composables/ 및 utils/ 디렉토리에서 자동 import할 컴포저블을 스캔할지 여부입니다. Nuxt 또는 다른 모듈에 의해 등록된 자동 import(예: vue 또는 nuxt에서 import)는 여전히 활성화됩니다.

타입: boolean
기본값: true

logLevel

로그 빌드 시 로그 레벨입니다.

CI에서 실행하거나 TTY가 없을 때 기본값은 'silent'입니다. 이 옵션은 Vite에서는 'silent', Webpack에서는 'none'으로 사용됩니다.

타입: string
기본값: "info"

modules

모듈은 Nuxt의 기능을 확장하고 다양한 통합을 추가할 수 있는 Nuxt 확장입니다.

각 모듈은 문자열(패키지 이름 또는 파일 경로), 모듈과 옵션 객체를 포함한 튜플, 또는 인라인 모듈 함수일 수 있습니다. Nuxt는 modules 배열의 각 항목을 node require 경로(node_modules 내)로 해석하려 시도한 후, ~ 별칭이 사용된 경우 프로젝트 srcDir에서 해석합니다.

타입: array

참고: 모듈은 순차적으로 실행되므로 순서가 중요합니다. 먼저 nuxt.config.ts에 정의된 모듈이 로드되고, 그 다음 modules/ 디렉토리에서 발견된 모듈이 알파벳 순으로 실행됩니다.

예시:

modules: [
  // 패키지 이름 사용
  '@nuxtjs/axios',
  // 프로젝트 srcDir 기준 상대 경로
  '~/modules/awesome.js',
  // 옵션 제공
  ['@nuxtjs/google-analytics', { ua: 'X1234567' }],
  // 인라인 정의
  function () {}
]

modulesDir

경로 해석(예: webpack의 resolveLoading, nodeExternals, postcss)을 위한 모듈 디렉토리를 설정합니다.

설정 경로는 options.rootDir(기본값은 현재 작업 디렉토리) 기준 상대 경로입니다. 프로젝트가 yarn workspace 스타일의 모노레포로 구성된 경우 이 필드를 설정해야 할 수 있습니다.

타입: array
기본값

[
  "/<rootDir>/node_modules"
]

예시:

export default {
  modulesDir: ['../../node_modules']
}

nitro

Nitro 설정.

참고: Nitro 설정 문서

`routeRules`

타입: object

`runtimeConfig`

타입: object
기본값

{
  "public": {},
  "app": {
    "buildId": "f2edd0e7-2595-424c-bd97-c91196e3f2d2",
    "baseURL": "/",
    "buildAssetsDir": "/_nuxt/",
    "cdnURL": ""
  },
  "nitro": {
    "envPrefix": "NUXT_"
  }
}

optimization

빌드 타임 최적화 설정.

`asyncTransforms`

unctx에서 await 이후 async context를 보존하는 트랜스포머에 직접 전달되는 옵션입니다.

`asyncFunctions`

타입: array
기본값

[
  "defineNuxtPlugin",
  "defineNuxtRouteMiddleware"
]

`objectDefinitions`

`defineNuxtComponent`

타입: array
기본값

[
  "asyncData",
  "setup"
]

`defineNuxtPlugin`

타입: array
기본값

[
  "setup"
]

`definePageMeta`

타입: array
기본값

[
  "middleware",
  "validate"
]

`keyedComposables`

키를 주입할 함수들입니다.

함수에 전달된 인자 수가 argumentLength보다 적으면, 서버와 클라이언트 간 요청을 중복 제거하는 데 사용할 수 있는 추가 매직 문자열이 주입됩니다. 이 추가 키를 처리하기 위한 조치가 필요합니다. 키는 파일 내에서 함수가 호출되는 위치를 기준으로 고유하게 생성됩니다.

타입: array
기본값

[
  {
    "name": "callOnce",
    "argumentLength": 3
  },
  {
    "name": "defineNuxtComponent",
    "argumentLength": 2
  },
  {
    "name": "useState",
    "argumentLength": 2
  },
  {
    "name": "useFetch",
    "argumentLength": 3
  },
  {
    "name": "useAsyncData",
    "argumentLength": 3
  },
  {
    "name": "useLazyAsyncData",
    "argumentLength": 3
  },
  {
    "name": "useLazyFetch",
    "argumentLength": 3
  }
]

`treeShake`

특정 빌드에서 코드를 트리쉐이킹합니다.

`composables`

서버 또는 클라이언트 빌드에서 컴포저블을 트리쉐이킹합니다.

예시:

treeShake: { client: { myPackage: ['useServerOnlyComposable'] } }

`client`

타입: object
기본값

{
  "vue": [
    "onRenderTracked",
    "onRenderTriggered",
    "onServerPrefetch"
  ],
  "#app": [
    "definePayloadReducer",
    "definePageMeta",
    "onPrehydrate"
  ]
}

`server`

타입: object
기본값

{
  "vue": [
    "onMounted",
    "onUpdated",
    "onUnmounted",
    "onBeforeMount",
    "onBeforeUpdate",
    "onBeforeUnmount",
    "onRenderTracked",
    "onRenderTriggered",
    "onActivated",
    "onDeactivated"
  ],
  "#app": [
    "definePayloadReviver",
    "definePageMeta"
  ]
}

pages

Nuxt 3에서 vue-router 통합을 사용할지 여부입니다. 값을 제공하지 않으면 소스 폴더에 pages/ 디렉토리가 있을 때 자동으로 활성화됩니다.

또한 glob 패턴 또는 패턴 배열을 제공하여 특정 파일만 페이지로 스캔할 수 있습니다.

예시:

pages: {
  pattern: ['**\/*\/*.vue', '!**\/*.spec.*'],
}

plugins

nuxt 앱 플러그인 배열입니다.

각 플러그인은 문자열(절대 또는 상대 경로의 파일)일 수 있습니다. .client 또는 .server로 끝나면 해당 컨텍스트에서만 자동으로 로드됩니다. 또는 src와 mode 키를 가진 객체일 수도 있습니다.

타입: array

참고: 플러그인은 ~/plugins 디렉토리에서도 자동 등록되며, 이 플러그인들은 nuxt.config에 나열할 필요가 없습니다. 순서를 커스터마이즈해야 할 때만 나열하세요. 모든 플러그인은 src 경로로 중복 제거됩니다.

참고: plugins/ 디렉토리 문서

예시:

plugins: [
  '~/plugins/foo.client.js', // 클라이언트 사이드에서만
  '~/plugins/bar.server.js', // 서버 사이드에서만
  '~/plugins/baz.js', // 클라이언트 & 서버 모두
  { src: '~/plugins/both-sides.js' },
  { src: '~/plugins/client-only.js', mode: 'client' }, // 클라이언트 사이드에서만
  { src: '~/plugins/server-only.js', mode: 'server' } // 서버 사이드에서만
]

postcss

`order`

PostCSS 플러그인 정렬 전략입니다.

타입: function

`plugins`

PostCSS 플러그인 설정 옵션입니다.

참고: PostCSS 문서

`autoprefixer`

CSS를 파싱하고 CSS 규칙에 공급업체 접두사를 추가하는 플러그인입니다.

참고: autoprefixer

`cssnano`

타입: object

참고: cssnano 설정 옵션

rootDir

애플리케이션의 루트 디렉토리를 정의합니다.

이 속성은 덮어쓸 수 있습니다(예: nuxt ./my-app/을 실행하면 현재/작업 디렉토리에서 ./my-app/의 절대 경로로 rootDir이 설정됨). 일반적으로 이 옵션을 설정할 필요는 없습니다.

타입: string
기본값: "/<rootDir>"

routeRules

일치하는 서버 라우트에 적용되는 전역 라우트 옵션입니다.

실험적: 이 기능은 실험적이며 API가 향후 변경될 수 있습니다.

참고: Nitro 라우트 규칙 문서

router

`options`

vue-router에 전달되는 추가 라우터 옵션입니다. vue-router의 옵션 외에도 Nuxt는 라우터를 커스터마이즈할 수 있는 추가 옵션을 제공합니다(아래 참조).

참고: Nuxt 설정에서는 JSON 직렬화 가능한 옵션만 전달해야 합니다. 더 많은 제어가 필요하다면 app/router.options.ts 파일을 사용하세요.

참고: Vue Router 문서.

`hashMode`

SPA 모드에서 해시 히스토리를 활성화할 수 있습니다. 이 모드에서는 라우터가 실제 URL 앞에 해시 문자(#)를 사용합니다. 활성화하면 URL이 서버로 전송되지 않으며 SSR이 지원되지 않습니다.

타입: boolean
기본값: false

기본값: false

`scrollBehaviorType`

해시 링크의 스크롤 동작을 커스터마이즈합니다.

타입: string
기본값: "auto"

기본값: 'auto'

runtimeConfig

런타임 설정을 통해 Nuxt 앱 컨텍스트에 동적 설정 및 환경 변수를 전달할 수 있습니다.

이 객체의 값은 서버에서만 useRuntimeConfig로 접근할 수 있습니다. 주로 프론트엔드에 노출되지 않는 비공개 설정(예: API 시크릿 토큰 참조)을 저장해야 합니다. public 및 app 아래의 값은 프론트엔드에도 노출됩니다. 런타임에 환경 변수와 일치하는 값으로 자동 대체됩니다. 예를 들어, 환경 변수 NUXT_API_KEY=my-api-key NUXT_PUBLIC_BASE_URL=/foo/를 설정하면 아래 예시의 두 값이 덮어써집니다.

타입: object
기본값

{
  "public": {},
  "app": {
    "buildId": "f2edd0e7-2595-424c-bd97-c91196e3f2d2",
    "baseURL": "/",
    "buildAssetsDir": "/_nuxt/",
    "cdnURL": ""
  }
}

예시:

export default {
 runtimeConfig: {
    apiKey: '', // 기본값은 빈 문자열, 런타임에 process.env.NUXT_API_KEY로 자동 설정
    public: {
       baseURL: '' // 프론트엔드에도 노출됨
    }
  }
}

serverDir

Nuxt 애플리케이션의 서버 디렉토리를 정의합니다. Nitro 라우트, 미들웨어, 플러그인이 이곳에 위치합니다.

상대 경로를 지정하면 rootDir을 기준으로 합니다.

타입: string
기본값: "/<srcDir>/server"

serverHandlers

Nitro 서버 핸들러.

각 핸들러는 다음 옵션을 허용합니다:

handler: 핸들러를 정의하는 파일의 경로 - route: 핸들러가 사용 가능한 라우트. rou3 규칙을 따릅니다. - method: 처리할 HTTP 메서드 - middleware: 미들웨어 핸들러 여부 - lazy: 핸들러를 lazy loading으로 import할지 여부
타입: array

참고: server/ 디렉토리 문서

참고: server/api, server/middleware, server/routes의 파일은 Nuxt에서 자동으로 등록됩니다.

예시:

serverHandlers: [
  { route: '/path/foo/**:name', handler: '~/server/foohandler.ts' }
]

sourcemap

서버 및/또는 클라이언트 번들에 대해 소스맵을 생성할지 여부 및 방식을 설정합니다.

단일 불리언으로 설정하면 서버와 클라이언트 모두에 적용됩니다. 또한 'hidden' 옵션도 서버와 클라이언트 모두에 사용할 수 있습니다. 서버와 클라이언트 모두에 사용할 수 있는 옵션: - true: 소스맵을 생성하고 최종 번들에 소스 참조를 포함합니다. - false: 소스맵을 생성하지 않습니다. - 'hidden': 소스맵을 생성하지만 최종 번들에 참조를 포함하지 않습니다.

타입: object
기본값

{
  "server": true,
  "client": false
}

spaLoadingTemplate

불리언 또는 HTML 파일 경로. 해당 파일의 내용이 ssr: false로 렌더링된 모든 HTML 페이지에 삽입됩니다.

설정하지 않으면, 레이어 중 하나에 ~/app/spa-loading-template.html 파일이 있으면 이를 사용합니다. - false면 SPA 로딩 인디케이터가 로드되지 않습니다. - true면 Nuxt가 레이어 중 하나에서 ~/app/spa-loading-template.html 파일을 찾거나, 기본 Nuxt 이미지를 사용합니다. 스피너의 좋은 소스는 SpinKit 또는 SVG Spinners입니다.
기본값: null

예시: ~/app/spa-loading-template.html

<!-- https://github.com/barelyhuman/snips/blob/dev/pages/css-loader.md -->
<div class="loader"></div>
<style>
.loader {
  display: block;
  position: fixed;
  z-index: 1031;
  top: 50%;
  left: 50%;
  transform: translate(-50%, -50%);
  width: 18px;
  height: 18px;
  box-sizing: border-box;
  border: solid 2px transparent;
  border-top-color: #000;
  border-left-color: #000;
  border-bottom-color: #efefef;
  border-right-color: #efefef;
  border-radius: 50%;
  -webkit-animation: loader 400ms linear infinite;
  animation: loader 400ms linear infinite;
}

@-webkit-keyframes loader {
  0% {
    -webkit-transform: translate(-50%, -50%) rotate(0deg);
  }
  100% {
    -webkit-transform: translate(-50%, -50%) rotate(360deg);
  }
}
@keyframes loader {
  0% {
    transform: translate(-50%, -50%) rotate(0deg);
  }
  100% {
    transform: translate(-50%, -50%) rotate(360deg);
  }
}
</style>

srcDir

Nuxt 애플리케이션의 소스 디렉토리를 정의합니다.

상대 경로를 지정하면 rootDir을 기준으로 합니다.

타입: string
기본값: "/<srcDir>"

예시:

export default {
  srcDir: 'src/'
}

다음과 같은 폴더 구조에서 동작합니다:

-| app/
---| node_modules/
---| nuxt.config.js
---| package.json
---| src/
------| assets/
------| components/
------| layouts/
------| middleware/
------| pages/
------| plugins/
------| public/
------| store/
------| server/
------| app.config.ts
------| app.vue
------| error.vue

ssr

HTML 렌더링을 활성화할지 여부(서버 모드에서 동적으로 또는 generate 시). false로 설정하면 생성된 페이지에 내용이 없습니다.

타입: boolean
기본값: true

telemetry

nuxt telemetry를 수동으로 비활성화합니다.

참고: Nuxt Telemetry에서 자세한 정보를 확인하세요.

test

앱이 단위 테스트 중인지 여부입니다.

타입: boolean
기본값: false

theme

로컬 또는 원격 소스에서 프로젝트를 확장합니다.

값은 소스 디렉토리 또는 현재 설정 기준의 설정 경로를 가리키는 문자열이어야 합니다. github:, gitlab:, bitbucket:, https://를 사용하여 원격 git 저장소에서 확장할 수 있습니다.

타입: string

typescript

Nuxt의 TypeScript 통합 설정.

`builder`

프로젝트에 포함할 빌더 타입입니다.

기본적으로 Nuxt는 builder 옵션을 기반으로 이를 추론합니다(기본값은 'vite'). 직접 빌더 환경 타입을 완전히 관리하려면 false로 끄거나, 'shared' 옵션을 선택할 수 있습니다. 'shared' 옵션은 여러 빌더를 지원해야 하는 모듈 작성자에게 권장됩니다.

기본값: null

`hoist`

compilerOptions.paths 내에서 딥 별칭을 생성할 모듈입니다. 아직 서브패스를 지원하지 않습니다. shamefully-hoist=false인 pnpm 모노레포에서 Nuxt를 사용할 때 필요할 수 있습니다.

타입: array
기본값

[
  "nitropack/types",
  "nitropack/runtime",
  "nitropack",
  "defu",
  "h3",
  "consola",
  "ofetch",
  "@unhead/vue",
  "@nuxt/devtools",
  "vue",
  "@vue/runtime-core",
  "@vue/compiler-sfc",
  "vue-router",
  "vue-router/auto-routes",
  "unplugin-vue-router/client",
  "@nuxt/schema",
  "nuxt"
]

`includeWorkspace`

Nuxt 프로젝트에 상위 워크스페이스를 포함합니다. 주로 테마 및 모듈 작성자에게 유용합니다.

타입: boolean
기본값: false

`shim`

*.vue shim을 생성합니다.

공식 Vue 확장이 컴포넌트에 대한 정확한 타입을 생성하도록 하는 것을 권장합니다. .vue 파일의 타입을 이해하지 못하는 ESLint와 같은 다른 라이브러리를 사용하는 경우에는 이 값을 true로 설정할 수 있습니다.

타입: boolean
기본값: false

`strict`

TypeScript는 프로그램의 안전성과 분석을 높이기 위한 특정 검사를 제공합니다. 코드베이스를 TypeScript로 변환한 후에는 이러한 검사를 활성화하여 더 높은 안전성을 얻을 수 있습니다. 자세히 보기

타입: boolean
기본값: true

`tsConfig`

이 옵션을 사용하여 생성된 .nuxt/tsconfig.json을 확장할 수 있습니다.

`typeCheck`

빌드 타임 타입 체크 활성화.

true로 설정하면 개발 중 타입 체크가 수행됩니다. 빌드 타임 타입 체크만 제한하려면 build로 설정하세요. typescript와 vue-tsc를 devDependencies로 설치해야 합니다.

타입: boolean
기본값: false

참고: Nuxt TypeScript 문서

unhead

unhead nuxt 모듈을 설정할 수 있는 객체입니다.

`legacy`

unhead 모듈의 레거시 호환 모드를 활성화합니다. 이 모드는 다음 변경 사항을 적용합니다: - Capo.js 정렬 비활성화 - DeprecationsPlugin 추가: hid, vmid, children, body 지원 - PromisesPlugin 추가: 입력값으로 promise 지원

타입: boolean
기본값: false

참고: unhead 마이그레이션 문서

예시:

export default defineNuxtConfig({
 unhead: {
  legacy: true
})

`renderSSRHeadOptions`

renderSSRHead에 전달되어 출력을 커스터마이즈할 객체입니다.

타입: object
기본값

{
  "omitLineBreaks": false
}

예시:

export default defineNuxtConfig({
 unhead: {
  renderSSRHeadOptions: {
   omitLineBreaks: true
  }
})

vite

Vite에 직접 전달되는 설정입니다.

참고: Vite 설정 문서에서 자세한 정보를 확인하세요. Nuxt에서 모든 vite 옵션이 지원되는 것은 아닙니다.

`build`

`assetsDir`

타입: string
기본값: "_nuxt/"

`emptyOutDir`

타입: boolean
기본값: false

`cacheDir`

타입: string
기본값: "/<rootDir>/node_modules/.cache/vite"

`clearScreen`

타입: boolean
기본값: true

`define`

타입: object
기본값

{
  "__VUE_PROD_HYDRATION_MISMATCH_DETAILS__": false,
  "process.dev": false,
  "import.meta.dev": false,
  "process.test": false,
  "import.meta.test": false
}

`esbuild`

타입: object
기본값

{
  "target": "esnext",
  "jsxFactory": "h",
  "jsxFragment": "Fragment",
  "tsconfigRaw": {}
}

`mode`

타입: string
기본값: "production"

`optimizeDeps`

`esbuildOptions`

타입: object
기본값

{
  "target": "esnext",
  "jsxFactory": "h",
  "jsxFragment": "Fragment",
  "tsconfigRaw": {}
}

`exclude`

타입: array
기본값

[
  "vue-demi"
]

`publicDir`

`resolve`

`extensions`

타입: array
기본값

[
  ".mjs",
  ".js",
  ".ts",
  ".jsx",
  ".tsx",
  ".json",
  ".vue"
]

`root`

타입: string
기본값: "/<srcDir>"

`server`

`fs`

`allow`

타입: array
기본값

[
  "/<rootDir>/.nuxt",
  "/<srcDir>",
  "/<rootDir>",
  "/<workspaceDir>"
]

`vue`

`features`

`propsDestructure`

타입: boolean
기본값: true

`isProduction`

타입: boolean
기본값: true

`script`

`hoistStatic`

`template`

`compilerOptions`

타입: object

`transformAssetUrls`

타입: object
기본값

{
  "video": [
    "src",
    "poster"
  ],
  "source": [
    "src"
  ],
  "img": [
    "src"
  ],
  "image": [
    "xlink:href",
    "href"
  ],
  "use": [
    "xlink:href",
    "href"
  ]
}

`vueJsx`

타입: object
기본값

{
  "isCustomElement": {
    "$schema": {
      "title": "",
      "description": "",
      "tags": []
    }
  }
}

vue

Vue.js 설정

`compilerOptions`

빌드 시 전달되는 Vue 컴파일러 옵션입니다.

참고: Vue 문서

`config`

Vue 앱을 전역적으로 설정할 수 있습니다. Nuxt 설정에서는 직렬화 가능한 옵션만 설정할 수 있습니다. 그 외의 옵션은 Nuxt 플러그인에서 런타임에 설정하세요.

참고: Vue 앱 설정 문서

`propsDestructure`

defineProps의 반응형 구조 분해 활성화

타입: boolean
기본값: true

`runtimeCompiler`

런타임 번들에 Vue 컴파일러 포함

타입: boolean
기본값: false

`transformAssetUrls`

`image`

타입: array
기본값

[
  "xlink:href",
  "href"
]

`img`

타입: array
기본값

[
  "src"
]

`source`

타입: array
기본값

[
  "src"
]

`use`

타입: array
기본값

[
  "xlink:href",
  "href"
]

`video`

타입: array
기본값

[
  "src",
  "poster"
]

watch

watch 속성을 사용하면 변경 시 Nuxt 개발 서버를 재시작할 패턴을 정의할 수 있습니다.

문자열 또는 정규식의 배열입니다. 문자열은 절대 경로나 srcDir(및 레이어의 srcDir) 기준 상대 경로여야 합니다. 정규식은 프로젝트 srcDir(및 레이어의 srcDir) 기준 경로와 매칭됩니다.

타입: array

watchers

watchers 속성을 사용하면 nuxt.config에서 watchers 설정을 덮어쓸 수 있습니다.

`chokidar`

chokidar에 직접 전달할 옵션입니다.

참고: chokidar

`ignoreInitial`

타입: boolean
기본값: true

`ignorePermissionErrors`

타입: boolean
기본값: true

`rewatchOnRawEvents`

이벤트 유형 배열. 해당 이벤트를 수신하면 watcher가 재시작됩니다.

`webpack`

webpack에 직접 전달할 watchOptions입니다.

참고: webpack@4 watch 옵션.

`aggregateTimeout`

타입: number
기본값: 1000

webpack

`aggressiveCodeRemoval`

typeof process, typeof window, typeof document를 하드하게 대체하여 번들을 트리쉐이킹합니다.

타입: boolean
기본값: false

`analyze`

Nuxt는 webpack-bundle-analyzer를 사용하여 번들을 시각화하고 최적화 방법을 제공합니다.

true로 설정하면 번들 분석이 활성화되며, 옵션 객체를 전달할 수도 있습니다: webpack용 옵션 또는 vite용 옵션.

타입: object
기본값

{
  "template": "treemap",
  "projectRoot": "/<rootDir>",
  "filename": "/<rootDir>/.nuxt/analyze/{name}.html"
}

예시:

analyze: {
  analyzerMode: 'static'
}

`cssSourceMap`

CSS 소스맵 지원 활성화(개발 모드에서는 기본값이 true).

타입: boolean
기본값: false

`devMiddleware`

사용 가능한 옵션은 webpack-dev-middleware 참조.

`stats`

타입: string
기본값: "none"

`experiments`

webpack 실험 기능 설정

`extractCSS`

공통 CSS 추출 활성화.

mini-css-extract-plugin을 내부적으로 사용하여, CSS가 별도의 파일로 추출됩니다(일반적으로 컴포넌트별 1개). 이를 통해 CSS와 JavaScript를 별도로 캐싱할 수 있습니다.

타입: boolean
기본값: true

예시:

export default {
  webpack: {
    extractCSS: true,
    // 또는
    extractCSS: {
      ignoreOrder: true
    }
  }
}

예시:

export default {
  webpack: {
    extractCSS: true,
    optimization: {
      splitChunks: {
        cacheGroups: {
          styles: {
            name: 'styles',
            test: /\.(css|vue)$/,
            chunks: 'all',
            enforce: true
          }
        }
      }
    }
  }
}

`filenames`

번들 파일 이름을 커스터마이즈합니다.

매니페스트 사용에 대해 더 알고 싶다면 webpack 문서를 참고하세요.

참고: 프로덕션에서 해시 기반이 아닌 파일 이름을 사용할 때는 주의하세요. 대부분의 브라우저는 에셋을 캐시하고 첫 로드 시 변경 사항을 감지하지 못할 수 있습니다.

예시:

filenames: {
  chunk: ({ isDev }) => (isDev ? '[name].js' : '[id].[contenthash].js')
}

`app`

타입: function

`chunk`

타입: function

`css`

타입: function

`font`

타입: function

`img`

타입: function

`video`

타입: function

`friendlyErrors`

FriendlyErrorsWebpackPlugin에서 제공하는 오버레이를 비활성화하려면 false로 설정하세요.

타입: boolean
기본값: true

타입: boolean
기본값: false

`importLoaders`

타입: number
기본값: 0

`url`

`filter`

타입: function

`cssModules`

사용 가능한 옵션은 css-loader 참조.

`esModule`

타입: boolean
기본값: false

`importLoaders`

타입: number
기본값: 0

`modules`

`localIdentName`

타입: string
기본값: "[local]_[hash:base64:5]"

`url`

`filter`

타입: function

`esbuild`

타입: object
기본값

{
  "target": "esnext",
  "jsxFactory": "h",
  "jsxFragment": "Fragment",
  "tsconfigRaw": {}
}

참고: esbuild loader

`file`

참고: file-loader 옵션

기본값:

{ esModule: false }

`esModule`

타입: boolean
기본값: false

`limit`

타입: number
기본값: 1000

`fontUrl`

참고: file-loader 옵션

기본값:

{ esModule: false }

`esModule`

타입: boolean
기본값: false

`limit`

타입: number
기본값: 1000

`imgUrl`

참고: file-loader 옵션

기본값:

{ esModule: false }

`esModule`

타입: boolean
기본값: false

`limit`

타입: number
기본값: 1000

`less`

기본값

{
  "sourceMap": false
}

참고: less-loader 옵션

`pugPlain`

참고: pug 옵션

`sass`

참고: sass-loader 옵션

기본값:

{
  sassOptions: {
    indentedSyntax: true
  }
}

`sassOptions`

`indentedSyntax`

타입: boolean
기본값: true

`scss`

기본값

{
  "sourceMap": false
}

참고: sass-loader 옵션

`stylus`

기본값

{
  "sourceMap": false
}

참고: stylus-loader 옵션

`vue`

사용 가능한 옵션은 vue-loader 참조.

`compilerOptions`

타입: object

`propsDestructure`

타입: boolean
기본값: true

`transformAssetUrls`

타입: object
기본값

{
  "video": [
    "src",
    "poster"
  ],
  "source": [
    "src"
  ],
  "img": [
    "src"
  ],
  "image": [
    "xlink:href",
    "href"
  ],
  "use": [
    "xlink:href",
    "href"
  ]
}

`vueStyle`

기본값

{
  "sourceMap": false
}

`optimization`

webpack 최적화 설정.

`minimize`

모든 최소화 도구를 비활성화하려면 minimize를 false로 설정하세요(개발 모드에서는 기본적으로 비활성화).

타입: boolean
기본값: true

`minimizer`

플러그인 배열로 minimizer를 커스터마이즈할 수 있습니다.

`runtimeChunk`

타입: string
기본값: "single"

`splitChunks`

`automaticNameDelimiter`

타입: string
기본값: "/"

`cacheGroups`

`chunks`

타입: string
기본값: "all"

`optimizeCSS`

OptimizeCSSAssets 플러그인 옵션.

extractCSS가 활성화된 경우 기본값은 true입니다.

타입: boolean
기본값: false

참고: css-minimizer-webpack-plugin 문서.

`plugins`

webpack 플러그인 추가.

타입: array

예시:

import webpack from 'webpack'
import { version } from './package.json'
// ...
plugins: [
  new webpack.DefinePlugin({
    'process.VERSION': version
  })
]

타입: object
기본값

{
  "autoprefixer": {},
  "cssnano": {}
}

`profile`

webpackbar에서 프로파일러 활성화.

일반적으로 CLI 인자 --profile로 활성화됩니다.

타입: boolean
기본값: false

참고: webpackbar.

`serverURLPolyfill`

URL 및 URLSearchParams를 제공하기 위해 로드할 폴리필 라이브러리입니다.

기본값은 'url'(패키지 참조)입니다.

타입: string
기본값: "url"

`warningIgnoreFilters`

빌드 경고를 숨길 필터입니다.

타입: array

workspaceDir

애플리케이션의 워크스페이스 디렉토리를 정의합니다.

주로 모노레포 환경에서 사용됩니다. Nuxt는 워크스페이스 디렉토리를 자동으로 감지하려 시도하지만, 여기서 덮어쓸 수 있습니다. 일반적으로 이 옵션을 설정할 필요는 없습니다.

타입: string
기본값: "/<workspaceDir>"