Nuxt에는 설정 파일에서 활성화할 수 있는 실험적 기능들이 포함되어 있습니다.
내부적으로 Nuxt는 @nuxt/schema를 사용하여 이러한 실험적 기능을 정의합니다. 더 자세한 내용은 API 문서나 소스 코드를 참고하세요.
키가 변경될 때, immediate: false로 설정되어 있고 아직 한 번도 트리거되지 않았더라도 useFetch를 실행할지 여부입니다.
useFetch와 useAsyncData는 immediate: true이거나 이미 한 번 트리거된 경우, 키가 변경될 때 항상 실행됩니다.
이 플래그는 기본적으로 비활성화되어 있지만, 다음과 같이 활성화할 수 있습니다:
export default defineNuxtConfig({
experimental: {
alwaysRunFetchOnKeyChange: true,
},
})
클라이언트 측에서 라우트 규칙을 준수하기 위해 앱 매니페스트를 사용합니다.
이 플래그는 기본적으로 활성화되어 있지만, 다음과 같이 비활성화할 수 있습니다:
export default defineNuxtConfig({
experimental: {
appManifest: false,
},
})
Nuxt와 Nitro에서 중첩된 컴포저블이 네이티브 async 컨텍스트에 접근할 수 있도록 활성화합니다. 이를 통해 async 컴포저블 내부에서 다른 컴포저블을 사용할 수 있게 되고, Nuxt instance is unavailable 오류가 발생할 가능성을 줄여줍니다.
export default defineNuxtConfig({
experimental: {
asyncContext: true,
},
})
Vue 번들을 위한 비동기 엔트리 포인트 생성을 활성화하여 모듈 페더레이션 지원에 도움을 줍니다.
export default defineNuxtConfig({
experimental: {
asyncEntry: true,
},
})
빌드 시 vue, @vue/*, vue-router를 외부 의존성으로 처리합니다.
이 플래그는 기본적으로 활성화되어 있지만, 다음과 같이 비활성화할 수 있습니다:
export default defineNuxtConfig({
experimental: {
externalVue: false,
},
})
코드 분할 및 캐싱 효율을 개선하기 위해 useAsyncData와 useLazyAsyncData 호출에서 핸들러 함수를 추출하여 별도의 청크로 분리합니다.
export default defineNuxtConfig({
experimental: {
extractAsyncDataHandlers: true,
},
})
이 기능은 인라인 핸들러 함수를 동적으로 임포트되는 청크로 변환합니다:
<!-- Before -->
<script setup>
const { data } = await useAsyncData('user', async () => {
return await $fetch('/api/user')
})
</script>
<!-- After transformation -->
<script setup>
const { data } = await useAsyncData('user', () =>
import('/generated-chunk.js').then(r => r.default()),
)
</script>
이 변환의 이점은 데이터 가져오기 로직을 분리할 수 있으면서도, 필요할 경우 해당 코드를 로드할 수 있다는 점입니다.
vite/webpack 청크 로딩 중 오류가 발생했을 때 app:chunkError 훅을 발생시킵니다. 기본 동작은 새 라우트로 네비게이션할 때 청크 로딩에 실패하면 해당 새 라우트를 다시 로드하는 것입니다.
기본적으로 Nuxt는 새 라우트로 이동하는 동안 청크 로딩에 실패하면 (automatic) 새 라우트를 다시 로드합니다.
automatic-immediate로 설정하면, 네비게이션을 기다리지 않고 청크 로딩에 실패하는 즉시 현재 라우트를 다시 로드합니다. 이는 네비게이션에 의해 트리거되지 않는 청크 오류(예: Nuxt 앱이 지연 컴포넌트를 로드하지 못하는 경우)에 유용합니다. 이 동작의 잠재적인 단점은, 앱이 실제로는 오류를 일으킨 청크를 필요로 하지 않는 경우에도 원치 않는 리로드가 발생할 수 있다는 점입니다.
이 기능을 false로 설정하여 자동 처리를 비활성화하거나, manual로 설정하여 청크 오류를 수동으로 처리할 수 있습니다.
export default defineNuxtConfig({
experimental: {
emitRouteChunkError: 'automatic', // 또는 'automatic-immediate', 'manual', false
},
})
Nuxt 모듈이 호환되지 않는 경우 Nuxt가 오류를 발생시키고(로드 실패) 중단할지 여부입니다.
이 기능은 기본적으로 비활성화되어 있습니다.
export default defineNuxtConfig({
experimental: {
enforceModuleCompatibility: true,
},
})
청크 오류 이후 페이지를 새로 고치거나 수동으로 reloadNuxtApp()을 호출했을 때, sessionStorage에서 Nuxt 앱 상태를 복원할 수 있도록 합니다.
하이드레이션 오류를 방지하기 위해, Vue 앱이 마운트된 이후에만 적용되며, 이로 인해 초기 로드 시 화면이 깜빡일 수 있습니다.
useState에 명시적인 키를 제공하는 것을 고려하세요.export default defineNuxtConfig({
experimental: {
restoreState: true,
},
})
defineRouteRules를 사용하여 페이지 레벨에서 라우트 규칙을 정의합니다.
export default defineNuxtConfig({
experimental: {
inlineRouteRules: true,
},
})
페이지의 path를 기반으로 일치하는 라우트 규칙이 생성됩니다.
복잡한 타입을 복원(revivify)하는 것을 지원하는 JSON 페이로드 렌더링을 허용합니다.
이 플래그는 기본적으로 활성화되어 있지만, 다음과 같이 비활성화할 수 있습니다:
export default defineNuxtConfig({
experimental: {
renderJsonPayloads: false,
},
})
Nitro 내에서 Vue 서버 렌더러 엔드포인트를 비활성화합니다.
export default defineNuxtConfig({
experimental: {
noVueServer: true,
},
})
서버 오류 페이지를 렌더링할 때 error.data를 파싱할지 여부입니다.
이 플래그는 기본적으로 활성화되어 있지만, 다음과 같이 비활성화할 수 있습니다:
export default defineNuxtConfig({
experimental: {
parseErrorData: false,
},
})
nuxt generate로 생성된 페이지의 페이로드 추출을 활성화합니다.
export default defineNuxtConfig({
experimental: {
payloadExtraction: true,
},
})
SSR에서 오류가 발생했을 때 클라이언트에서 콘텐츠를 렌더링하기 위한 실험적 컴포넌트 <NuxtClientFallback>을 활성화합니다.
export default defineNuxtConfig({
experimental: {
clientFallback: true,
},
})
Speculation Rules API를 사용한 교차 출처 프리페치를 활성화합니다.
export default defineNuxtConfig({
experimental: {
crossOriginPrefetch: true,
},
})
클라이언트 사이드 라우터와 View Transition API 통합을 활성화합니다.
export default defineNuxtConfig({
experimental: {
viewTransition: true,
},
})
Node 서버를 사용할 때 Early Hints 전송을 활성화합니다.
export default defineNuxtConfig({
experimental: {
writeEarlyHints: true,
},
})
<NuxtIsland>와 .island.vue 파일을 사용한 실험적 컴포넌트 아일랜드 지원을 활성화합니다.
export default defineNuxtConfig({
experimental: {
componentIslands: true, // false 또는 'local+remote'
},
})
레이어 내에 위치한 ~, ~~, @, @@ 별칭을 해당 레이어의 소스 및 루트 디렉터리를 기준으로 해석합니다.
이 플래그는 기본적으로 활성화되어 있지만, 다음과 같이 비활성화할 수 있습니다:
export default defineNuxtConfig({
experimental: {
localLayerAliases: false,
},
})
unplugin-vue-router를 사용한 새로운 실험적 타입 지원 라우터를 활성화합니다.
export default defineNuxtConfig({
experimental: {
typedPages: true,
},
})
기본적으로 navigateTo, <NuxtLink>, router.push() 등에서 타입 지원을 사용할 수 있게 됩니다.
또한 페이지 내에서 const route = useRoute('route-name')을 사용하여 타입이 지정된 params를 얻을 수도 있습니다.
pnpm을 shamefully-hoist=true 없이 사용하는 경우, 이 기능이 동작하려면 unplugin-vue-router를 devDependency로 설치해야 합니다.Nuxt에서 감시 서비스로 사용할 대체 watcher를 설정합니다.
Nuxt는 기본적으로 chokidar-granular를 사용하며, 감시에서 제외된 최상위 디렉터리
(예: node_modules, .git)를 무시합니다.
대신 parcel로 설정하여 @parcel/watcher를 사용할 수 있으며,
이는 대규모 프로젝트나 Windows 플랫폼에서 성능을 향상시킬 수 있습니다.
또한 chokidar로 설정하여 소스 디렉터리의 모든 파일을 감시할 수도 있습니다.
export default defineNuxtConfig({
experimental: {
watcher: 'chokidar-granular', // 'chokidar' 또는 'parcel'도 선택 가능
},
})
Nuxt는 사전 렌더링된 페이지 간에 페이로드 데이터를 자동으로 공유합니다. 이는 useAsyncData나 useFetch를 사용하고 서로 다른 페이지에서 동일한 데이터를 가져오는 사이트를 사전 렌더링할 때 상당한 성능 향상을 가져올 수 있습니다.
필요하다면 이 기능을 비활성화할 수 있습니다.
export default defineNuxtConfig({
experimental: {
sharedPrerenderData: false,
},
})
이 기능을 활성화할 때는 데이터의 모든 고유 키가 항상 동일한 데이터로 해석될 수 있도록 하는 것이 특히 중요합니다. 예를 들어, 특정 페이지와 관련된 데이터를 가져오기 위해 useAsyncData를 사용하는 경우, 해당 데이터를 고유하게 식별하는 키를 제공해야 합니다. (useFetch는 이를 자동으로 처리해 줍니다.)
// 동적 페이지(예: `[slug].vue`)에서 이 코드는 안전하지 않습니다. 라우트 slug가
// 가져오는 데이터에 영향을 주지만, 키에 반영되지 않기 때문에 Nuxt는 이를 알 수 없습니다.
const route = useRoute()
const { data } = await useAsyncData(async (_nuxtApp, { signal }) => {
return await $fetch(`/api/my-page/${route.params.slug}`, { signal })
})
// 대신, 가져온 데이터를 고유하게 식별하는 키를 사용해야 합니다.
const { data } = await useAsyncData(route.params.slug, async (_nuxtApp, { signal }) => {
return await $fetch(`/api/my-page/${route.params.slug}`, { signal })
})
이 기능을 사용하면 Nuxt는 클라이언트 빌드에서 Node.js 임포트를 unenv를 사용해 자동으로 폴리필합니다.
Buffer와 같은 전역 객체를 사용하려면 수동으로 주입해야 합니다.import { Buffer } from 'node:buffer'
globalThis.Buffer ||= Buffer
Nuxt는 definePageMeta에 정의된 일부 라우트 메타데이터(alias, name, path, redirect, props, middleware)를 빌드 타임에 모듈에 노출합니다.
이는 변수나 조건부 할당이 아닌, 정적 값 또는 문자열/배열에 대해서만 동작합니다. 더 많은 정보와 맥락은 원 이슈를 참고하세요.
기본적으로 페이지 메타데이터는 pages:extend에서 모든 라우트가 등록된 이후에만 스캔됩니다. 그 후 pages:resolved라는 또 다른 훅이 호출됩니다.
프로젝트에서 문제가 발생한다면 이 기능을 비활성화할 수 있습니다.
export default defineNuxtConfig({
experimental: {
scanPageMeta: false,
},
})
브라우저에서 지원되는 경우 CookieStore를 활성화하여 쿠키 업데이트를 감지하고 useCookie ref 값을 새로 고칩니다.
이 플래그는 기본적으로 활성화되어 있지만, 다음과 같이 비활성화할 수 있습니다:
export default defineNuxtConfig({
experimental: {
cookieStore: false,
},
})
설정 및 소스 파일의 해시를 기반으로 Nuxt 빌드 아티팩트를 캐시합니다.
이는 앱의 Vue/Nitro 부분에 대해 srcDir 및 serverDir 내의 소스 파일에만 동작합니다.
이 플래그는 기본적으로 비활성화되어 있지만, 다음과 같이 활성화할 수 있습니다:
export default defineNuxtConfig({
experimental: {
buildCache: true,
},
})
활성화된 경우, 다음 파일의 변경은 전체 리빌드를 트리거합니다:
.nuxtrc
.npmrc
package.json
package-lock.json
yarn.lock
pnpm-lock.yaml
tsconfig.json
bun.lock
bun.lockb
추가로, srcDir 내 파일의 변경은 Vue 클라이언트/서버 번들의 리빌드를 트리거합니다. Nitro는 항상 다시 빌드되지만(캐시 가능한 아티팩트와 그 해시를 Nitro가 알릴 수 있도록 하는 작업이 진행 중입니다).
새 빌드를 확인하는 시간 간격(ms)을 설정합니다. experimental.appManifest가 false인 경우 비활성화됩니다.
비활성화하려면 false로 설정하세요.
export default defineNuxtConfig({
experimental: {
checkOutdatedBuildInterval: 3600000, // 1시간, 또는 false로 비활성화
},
})
definePageMeta() 매크로는 페이지에 대한 빌드 타임 메타데이터를 수집하는 데 유용한 방법입니다. Nuxt 자체는 리다이렉트, 페이지 별칭, 커스텀 경로와 같은 내부 기능을 지원하기 위해 사용되는 지원 키 목록을 제공합니다.
이 옵션은 scanPageMeta를 사용할 때 페이지 메타데이터에서 추가로 추출할 키를 전달할 수 있게 해줍니다.
<script lang="ts" setup>
definePageMeta({
foo: 'bar',
})
</script>
export default defineNuxtConfig({
experimental: {
extraPageMetaExtractionKeys: ['foo'],
},
hooks: {
'pages:resolved' (ctx) {
// ✅ foo를 사용할 수 있습니다
},
},
})
이를 통해 모듈은 빌드 컨텍스트에서 페이지 메타데이터의 추가 메타데이터에 접근할 수 있습니다. 모듈 내에서 이를 사용하는 경우, 사용자 정의 메타데이터 키로 NuxtPage 타입을 보강하는 것을 권장합니다.
네비게이션 전에 한 번의 애니메이션 프레임을 기다려, 브라우저가 사용자 상호작용을 인지하고 리페인트할 수 있는 기회를 제공합니다.
이는 사전 렌더링된 라우트에서 네비게이션 시 INP를 줄이는 데 도움이 될 수 있습니다.
이 플래그는 기본적으로 활성화되어 있지만, 다음과 같이 비활성화할 수 있습니다:
export default defineNuxtConfig({
experimental: {
navigationRepaint: false,
},
})
Nuxt는 자동 생성된 Vue 컴포넌트 이름을, 해당 컴포넌트를 자동 임포트할 때 사용하는 전체 컴포넌트 이름과 일치하도록 업데이트합니다.
문제가 발생하는 경우 이 기능을 비활성화할 수 있습니다.
export default defineNuxtConfig({
experimental: {
normalizeComponentNames: false,
},
})
기본적으로, 수동으로 설정하지 않은 경우 Vue는 컴포넌트 파일 이름과 일치하는 컴포넌트 이름을 할당합니다.
├─ components/
├─── SomeFolder/
├───── MyComponent.vue
이 경우 Vue 입장에서 컴포넌트 이름은 MyComponent가 됩니다. <KeepAlive>와 함께 사용하거나 Vue DevTools에서 식별하려면 이 컴포넌트 이름을 사용해야 합니다.
하지만 자동 임포트를 사용하려면 SomeFolderMyComponent를 사용해야 합니다.
experimental.normalizeComponentNames를 설정하면 이 두 값이 일치하게 되고, Vue는 Nuxt의 컴포넌트 네이밍 패턴과 일치하는 컴포넌트 이름을 생성합니다.
클라이언트 전용 페이지(ssr: false)를 렌더링할 때, 선택적으로 로딩 화면(~/spa-loading-template.html)을 렌더링합니다.
이를 within으로 설정하면 다음과 같이 렌더링됩니다:
<div id="__nuxt">
<!-- spa loading template -->
</div>
또는 body로 설정하여 Nuxt 앱 루트와 나란히 템플릿을 렌더링할 수 있습니다:
<div id="__nuxt"></div>
<!-- spa loading template -->
이는 클라이언트 전용 페이지를 하이드레이션할 때 발생하는 흰 화면 깜빡임을 방지합니다.
브라우저 개발자 도구에서 Nuxt 훅에 대한 퍼포먼스 마커를 활성화합니다. 이는 Chromium 기반 브라우저의 Performance 탭에서 추적할 수 있는 퍼포먼스 마커를 추가하며, 디버깅 및 성능 최적화에 유용합니다.
이 기능은 개발 모드에서 기본적으로 활성화됩니다. 필요하다면 다음과 같이 비활성화할 수 있습니다:
export default defineNuxtConfig({
experimental: {
browserDevtoolsTiming: false,
},
})
Nuxt 초기화 단계 동안 모듈이 수행한 설정 변경을 디버깅할 수 있도록, 모듈 컨텍스트에서 nuxt.options에 대한 변경 사항을 기록합니다.
이 기능은 debug 모드가 활성화된 경우 기본적으로 활성화됩니다. 필요하다면 비활성화할 수 있습니다:
명시적으로 활성화하려면:
export default defineNuxtConfig({
experimental: {
debugModuleMutation: true,
},
})
<Lazy> 컴포넌트에 대한 하이드레이션 전략을 활성화하여, 컴포넌트가 실제로 필요할 때까지 하이드레이션을 지연시켜 성능을 향상시킵니다.
지연 하이드레이션은 기본적으로 활성화되어 있지만, 다음과 같이 비활성화할 수 있습니다:
export default defineNuxtConfig({
experimental: {
lazyHydration: false,
},
})
템플릿을 추가한 모듈의 경로를 기준으로 Nuxt 템플릿 내 임포트를 해석하는 동작을 비활성화합니다.
기본적으로 Nuxt는 템플릿 내 임포트를, 해당 템플릿을 추가한 모듈을 기준으로 해석하려고 시도합니다. 이를 false로 설정하면 이 동작이 비활성화되며, 특정 환경에서 발생할 수 있는 해석 충돌 문제를 해결하는 데 유용할 수 있습니다.
이 플래그는 기본적으로 활성화되어 있지만, 다음과 같이 비활성화할 수 있습니다:
export default defineNuxtConfig({
experimental: {
templateImportResolution: false,
},
})
기본적으로 자동 임포트된 useRoute() 컴포저블이 반환하는 라우트 객체는 <NuxtPage>에서 현재 표시 중인 페이지와 동기화 상태로 유지됩니다. 그러나 vue-router에서 export된 useRoute나 Vue 템플릿에서 사용할 수 있는 기본 $route 객체에는 이 동작이 적용되지 않습니다.
이 옵션을 활성화하면, Nuxt가 관리하는 useRoute()와 $route 템플릿 객체를 동기화하기 위한 믹스인이 주입됩니다.
이 플래그는 기본적으로 활성화되어 있지만, 다음과 같이 비활성화할 수 있습니다:
export default defineNuxtConfig({
experimental: {
templateRouteInjection: false,
},
})
이 옵션은 esbuild를 기반으로 Nuxt/Nitro 앱 전체에서 데코레이터 문법을 사용할 수 있도록 활성화합니다.
오랫동안 TypeScript는 compilerOptions.experimentalDecorators를 통해 데코레이터를 지원해 왔습니다. 이 구현은 TC39 표준화 프로세스 이전의 것이었습니다. 이제 데코레이터는 Stage 3 제안 단계에 있으며, TS 5.0+에서는 별도의 설정 없이 지원됩니다(https://github.com/microsoft/TypeScript/pull/52582 및 https://devblogs.microsoft.com/typescript/announcing-typescript-5-0-beta/#decorators 참고).
experimental.decorators를 활성화하면 TypeScript의 기존 compilerOptions.experimentalDecorators 구현이 아닌, TC39 제안에 대한 지원이 활성화됩니다.
export default defineNuxtConfig({
experimental: {
decorators: true,
},
})
function something (_method: () => unknown) {
return () => 'decorated'
}
class SomeClass {
@something
public someMethod () {
return 'initial'
}
}
const value = new SomeClass().someMethod()
// 이 값은 'decorated'를 반환합니다
핵심 Nuxt 컴포넌트와 컴포저블에 대한 기본 옵션을 지정할 수 있습니다.
이 옵션들은 향후 app.config나 app/ 디렉터리 등 다른 위치로 옮겨질 가능성이 있습니다.
export default defineNuxtConfig({
experimental: {
defaults: {
nuxtLink: {
componentName: 'NuxtLink',
prefetch: true,
prefetchOn: {
visibility: true,
},
},
useAsyncData: {
deep: true,
},
},
},
})
라우트 네비게이션 시 Nuxt의 static 및 asyncData 캐시를 정리할지 여부입니다.
Nuxt는 useAsyncData와 nuxtApp.static.data에서 캐시된 데이터를 자동으로 정리합니다. 이는 메모리 누수를 방지하고 필요할 때 최신 데이터를 로드하는 데 도움이 되지만, 비활성화할 수도 있습니다.
이 플래그는 기본적으로 활성화되어 있지만, 다음과 같이 비활성화할 수 있습니다:
export default defineNuxtConfig({
experimental: {
purgeCachedData: false,
},
})
useAsyncData와 useFetch의 데이터를 새로 고칠 때(watch, refreshNuxtData(), 수동 refresh() 호출 등), getCachedData를 호출하고 그 결과를 사용할지 여부입니다.
이 플래그는 기본적으로 활성화되어 있지만, 다음과 같이 비활성화할 수 있습니다:
export default defineNuxtConfig({
experimental: {
granularCachedData: false,
},
})
다음과 같은 head 최적화를 사용합니다:
이 플래그는 기본적으로 활성화되어 있지만, 다음과 같이 비활성화할 수 있습니다:
export default defineNuxtConfig({
experimental: {
headNext: false,
},
})
useAsyncData와 useFetch에서, 데이터 가져오기가 아직 시작되지 않았을 때 pending을 true로 둘지 여부입니다.
이 플래그는 기본적으로 비활성화되어 있지만, 다음과 같이 활성화할 수 있습니다:
export default defineNuxtConfig({
experimental: {
pendingWhenIdle: true,
},
})
기본적으로 Nuxt는 번들의 엔트리 청크를 해석하기 위해 import map을 사용하여 청크 안정성을 향상시킵니다.
이는 <head> 태그 상단에 import map을 주입합니다:
<script type="importmap">{"imports":{"#entry":"/_nuxt/DC5HVSK5.js"}}</script>
Vite가 생성한 스크립트 청크 내에서 임포트는 #entry에서 이루어집니다. 이는 엔트리에 변경이 있더라도, 그렇지 않으면 변경되지 않은 청크가 무효화되지 않도록 해줍니다.
vite.build.target에 import map을 지원하지 않는 브라우저를 포함했거나, vite.build.rollupOptions.output.entryFileNames를 [hash]를 포함하지 않는 값으로 설정한 경우 이 기능을 자동으로 비활성화합니다.이 기능을 비활성화해야 하는 경우 다음과 같이 할 수 있습니다:
export default defineNuxtConfig({
experimental: {
entryImportMap: false,
},
// 또는, 더 나은 방법으로, nuxt가 존중할
// 원하는 vite target을 명시적으로 지정하세요
vite: {
build: {
target: 'safari13',
},
},
})
@dxup/nuxt 모듈을 사용하여 향상된 TypeScript 개발자 경험을 활성화합니다.
이 실험적 플러그인은 Nuxt 애플리케이션에서 TypeScript로 작업할 때 더 나은 DX를 제공하기 위해 개선된 TypeScript 통합 및 개발 도구를 제공합니다.
이 플래그는 기본적으로 비활성화되어 있지만, 다음과 같이 활성화할 수 있습니다:
export default defineNuxtConfig({
experimental: {
typescriptPlugin: true,
},
})
typescript를 의존성으로 설치해야 합니다.향상된 빌드 설정 및 플러그인 아키텍처를 위해 Vite 6의 새로운 Environment API를 활성화합니다.
future.compatibilityVersion을 5로 설정하면 이 기능이 기본적으로 활성화됩니다. 테스트 목적으로 명시적으로 활성화할 수도 있습니다:
export default defineNuxtConfig({
experimental: {
viteEnvironmentApi: true,
},
})
Vite Environment API는 개발 및 프로덕션 빌드 간의 일관성을 개선하고, 환경별 설정에 대한 더 세밀한 제어와 향상된 성능을 제공합니다.