실험적 기능
Nuxt의 실험적 기능은 Nuxt 설정 파일에서 활성화할 수 있습니다.
내부적으로 Nuxt는 @nuxt/schema를 사용하여 이러한 실험적 기능을 정의합니다. 자세한 내용은 API 문서 또는 소스 코드를 참고하세요.
asyncContext
Nuxt와 Nitro에서 중첩된 컴포저블에서 네이티브 async context에 접근할 수 있도록 활성화합니다. 이를 통해 async 컴포저블 내부에서 컴포저블을 사용할 수 있고, Nuxt 인스턴스를 사용할 수 없습니다 오류가 발생할 가능성을 줄일 수 있습니다.
export default defineNuxtConfig({
experimental: {
asyncContext: true
}
})
asyncEntry
Vue 번들을 위한 비동기 엔트리 포인트 생성을 활성화하여 모듈 페더레이션 지원에 도움을 줍니다.
export default defineNuxtConfig({
experimental: {
asyncEntry: true
}
})
externalVue
빌드 시 vue, @vue/*, vue-router를 외부화합니다.
기본적으로 활성화되어 있습니다.
export default defineNuxtConfig({
experimental: {
externalVue: true
}
})
treeshakeClientOnly
서버 번들에서 client-only 컴포넌트의 내용을 트리 셰이킹합니다.
기본적으로 활성화되어 있습니다.
export default defineNuxtConfig({
experimental: {
treeshakeClientOnly: true
}
})
emitRouteChunkError
vite/webpack 청크를 로드하는 중 오류가 발생하면 app:chunkError 훅을 발생시킵니다. 기본 동작은 청크 로드 실패 시 새 라우트로 이동할 때 새 라우트를 리로드합니다.
이 값을 'automatic-immediate'로 설정하면 Nuxt가 네비게이션을 기다리지 않고 현재 라우트를 즉시 리로드합니다. 이는 네비게이션이 아닌 경우(예: Nuxt 앱이 지연 컴포넌트 로드에 실패할 때) 청크 오류에 유용합니다. 이 동작의 잠재적 단점은 앱이 오류를 일으킨 청크를 필요로 하지 않을 때 원치 않는 리로드가 발생할 수 있다는 점입니다.
이 기능을 false로 설정하여 자동 처리를 비활성화하거나, manual로 설정하여 청크 오류를 수동으로 처리할 수 있습니다.
export default defineNuxtConfig({
experimental: {
emitRouteChunkError: 'automatic' // 또는 'automatic-immediate', 'manual', false
}
})
restoreState
청크 오류나 수동 reloadNuxtApp() 호출 후 페이지를 새로고침할 때 Nuxt 앱 상태를 sessionStorage에서 복원할 수 있습니다.
하이드레이션 오류를 방지하기 위해, Vue 앱이 마운트된 후에만 적용되므로 초기 로드 시 깜빡임이 발생할 수 있습니다.
useState에 명시적인 키를 제공하는 것이 좋습니다. 자동 생성된 키는 빌드마다 일치하지 않을 수 있습니다.export default defineNuxtConfig({
experimental: {
restoreState: true
}
})
inlineRouteRules
defineRouteRules를 사용하여 페이지 레벨에서 라우트 규칙을 정의할 수 있습니다.
export default defineNuxtConfig({
experimental: {
inlineRouteRules: true
}
})
일치하는 라우트 규칙은 페이지의 path를 기반으로 생성됩니다.
renderJsonPayloads
복잡한 타입의 복원을 지원하는 JSON 페이로드 렌더링을 허용합니다.
기본적으로 활성화되어 있습니다.
export default defineNuxtConfig({
experimental: {
renderJsonPayloads: true
}
})
noVueServer
Nitro 내에서 Vue 서버 렌더러 엔드포인트를 비활성화합니다.
export default defineNuxtConfig({
experimental: {
noVueServer: true
}
})
payloadExtraction
nuxt generate로 생성된 페이지의 페이로드 추출을 활성화합니다.
export default defineNuxtConfig({
experimental: {
payloadExtraction: true
}
})
clientFallback
SSR에서 오류가 발생할 경우 클라이언트에서 콘텐츠를 렌더링하는 실험적 <NuxtClientFallback> 컴포넌트를 활성화합니다.
export default defineNuxtConfig({
experimental: {
clientFallback: true
}
})
crossOriginPrefetch
Speculation Rules API를 사용한 교차 출처 프리페치를 활성화합니다.
export default defineNuxtConfig({
experimental: {
crossOriginPrefetch: true
}
})
viewTransition
클라이언트 사이드 라우터와 View Transition API 통합을 활성화합니다.
export default defineNuxtConfig({
experimental: {
viewTransition: true
}
})
writeEarlyHints
노드 서버 사용 시 Early Hints를 기록하는 기능을 활성화합니다.
export default defineNuxtConfig({
experimental: {
writeEarlyHints: true
}
})
componentIslands
<NuxtIsland> 및 .island.vue 파일을 사용한 실험적 컴포넌트 아일랜드 지원을 활성화합니다.
export default defineNuxtConfig({
experimental: {
componentIslands: true // false 또는 'local+remote'
}
})
configSchema
설정 스키마 지원을 활성화합니다.
기본적으로 활성화되어 있습니다.
export default defineNuxtConfig({
experimental: {
configSchema: true
}
})
polyfillVueUseHead
이전 @vueuse/head API에 의존하는 모듈, 플러그인 또는 사용자 코드를 위한 호환성 계층을 추가합니다.
export default defineNuxtConfig({
experimental: {
polyfillVueUseHead: false
}
})
respectNoSSRHeader
x-nuxt-no-ssr 헤더를 설정하여 Nuxt SSR 응답을 비활성화할 수 있도록 허용합니다.
export default defineNuxtConfig({
experimental: {
respectNoSSRHeader: false
}
})
localLayerAliases
레이어 내에 위치한 ~, ~~, @, @@ 별칭을 해당 레이어의 소스 및 루트 디렉터리를 기준으로 해석합니다.
기본적으로 활성화되어 있습니다.
export default defineNuxtConfig({
experimental: {
localLayerAliases: true
}
})
typedPages
unplugin-vue-router를 사용한 새로운 실험적 타입드 라우터를 활성화합니다.
export default defineNuxtConfig({
experimental: {
typedPages: true
}
})
기본적으로 navigateTo, <NuxtLink>, router.push() 등에서 타입드 사용이 가능합니다.
페이지 내에서 const route = useRoute('route-name')을 사용하여 타입드 파라미터도 얻을 수 있습니다.
pnpm을 shamefully-hoist=true 없이 사용하는 경우, 이 기능이 동작하려면 unplugin-vue-router를 devDependency로 설치해야 합니다.watcher
Nuxt의 감시 서비스로 사용할 대체 감시자를 설정합니다.
Nuxt는 기본적으로 chokidar-granular를 사용하며,
이는 감시에서 제외된 최상위 디렉터리(예: node_modules, .git)를 무시합니다.
대신 parcel로 설정하면 @parcel/watcher를 사용하여
대형 프로젝트나 Windows 환경에서 성능이 향상될 수 있습니다.
또는 chokidar로 설정하여 소스 디렉터리의 모든 파일을 감시할 수도 있습니다.
export default defineNuxtConfig({
experimental: {
watcher: 'chokidar-granular' // 'chokidar' 또는 'parcel'도 선택 가능
}
})
sharedPrerenderData
이 기능을 활성화하면 프리렌더링된 페이지 간에 페이로드 데이터가 자동으로 공유됩니다.
이는 useAsyncData 또는 useFetch를 사용하고 여러 페이지에서
동일한 데이터를 가져오는 사이트를 프리렌더링할 때 성능이 크게 향상될 수 있습니다.
export default defineNuxtConfig({
experimental: {
sharedPrerenderData: true
}
})
이 기능을 활성화할 때는 데이터의 고유 키가 항상 동일한 데이터를 가리키도록 하는 것이 특히 중요합니다.
예를 들어, 특정 페이지와 관련된 데이터를 가져오기 위해 useAsyncData를 사용하는 경우,
해당 데이터를 고유하게 식별하는 키를 제공해야 합니다.
(useFetch는 이를 자동으로 처리합니다.)
// 동적 페이지(예: `[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}`)
})
clientNodeCompat
이 기능을 사용하면 Nuxt가 unenv를 사용하여 클라이언트 빌드에서 Node.js import를 자동으로 폴리필합니다.
Buffer와 같은 글로벌을 동작시키려면 수동으로 주입해야 합니다.import { Buffer } from 'node:buffer'
globalThis.Buffer = globalThis.Buffer || Buffer
scanPageMeta
이 옵션을 사용하면 definePageMeta에 정의된 일부 라우트 메타데이터(alias, name, path, redirect, props, middleware)를 빌드 타임에 모듈에 노출할 수 있습니다.
이 기능은 변수나 조건부 할당이 아닌 정적 값 또는 문자열/배열에만 동작합니다. 자세한 내용과 맥락은 원본 이슈를 참고하세요.
또한 모든 라우트가 pages:extend에서 등록된 후에만 페이지 메타데이터를 스캔하도록 설정할 수도 있습니다. 이 경우 pages:resolved라는 또 다른 훅이 호출됩니다. 이 동작을 활성화하려면 scanPageMeta: 'after-resolve'로 설정하세요.
프로젝트에서 문제가 발생하면 이 기능을 비활성화할 수 있습니다.
export default defineNuxtConfig({
experimental: {
scanPageMeta: false
}
})
cookieStore
브라우저가 지원하는 경우 쿠키 업데이트를 감지하고 useCookie ref 값을 새로고침할 수 있도록 CookieStore 지원을 활성화합니다.
export default defineNuxtConfig({
experimental: {
cookieStore: true
}
})
buildCache
설정 및 소스 파일의 해시를 기반으로 Nuxt 빌드 산출물을 캐싱합니다.
export default defineNuxtConfig({
experimental: {
buildCache: true
}
})
활성화 시, 다음 파일이 변경되면 전체 리빌드가 트리거됩니다:
.nuxtrc
.npmrc
package.json
package-lock.json
yarn.lock
pnpm-lock.yaml
tsconfig.json
bun.lockb
또한, srcDir 내 파일이 변경되면 Vue 클라이언트/서버 번들이 리빌드됩니다. Nitro는 항상 리빌드되지만(향후 Nitro가 캐시 가능한 산출물과 해시를 알릴 수 있도록 작업 중입니다).
extraPageMetaExtractionKeys
definePageMeta() 매크로는 페이지에 대한 빌드 타임 메타를 수집하는 데 유용합니다. Nuxt 자체는 리다이렉트, 페이지 별칭, 커스텀 경로 등 일부 내부 기능을 지원하는 키 목록을 제공합니다.
이 옵션을 사용하면 scanPageMeta 사용 시 페이지 메타데이터에서 추가 키를 추출할 수 있습니다.
<script lang="ts" setup>
definePageMeta({
foo: 'bar'
})
</script>
export default defineNuxtConfig({
experimental: {
extraPageMetaExtractionKeys: ['foo'],
},
hooks: {
'pages:resolved' (ctx) {
// ✅ foo를 사용할 수 있습니다
},
},
})
이렇게 하면 모듈이 빌드 컨텍스트에서 페이지 메타데이터의 추가 메타데이터에 접근할 수 있습니다. 모듈 내에서 사용하는 경우, NuxtPage 타입에 키를 확장하는 것도 권장합니다.
normalizeComponentNames
자동 생성된 Vue 컴포넌트 이름이 컴포넌트 자동 임포트 시 사용하는 전체 컴포넌트 이름과 일치하도록 보장합니다.
export default defineNuxtConfig({
experimental: {
normalizeComponentNames: true
}
})
기본적으로 수동으로 설정하지 않은 경우, Vue는 컴포넌트 파일 이름과 일치하는 컴포넌트 이름을 할당합니다.
├─ components/
├─── SomeFolder/
├───── MyComponent.vue
이 경우, Vue 입장에서는 컴포넌트 이름이 MyComponent가 됩니다. <KeepAlive>와 함께 사용하거나 Vue DevTools에서 식별하려면 이 컴포넌트를 사용해야 합니다.
하지만 자동 임포트하려면 SomeFolderMyComponent를 사용해야 합니다.
experimental.normalizeComponentNames를 설정하면 이 두 값이 일치하게 되어, Vue가 Nuxt의 컴포넌트 네이밍 패턴에 맞는 컴포넌트 이름을 생성합니다.
spaLoadingTemplateLocation
클라이언트 전용 페이지(ssr: false)를 렌더링할 때, 로딩 화면(app/spa-loading-template.html에서)을 선택적으로 렌더링합니다.
within으로 설정하면 다음과 같이 렌더링됩니다:
<div id="__nuxt">
<!-- spa 로딩 템플릿 -->
</div>
또는, body로 설정하면 Nuxt 앱 루트와 함께 템플릿을 렌더링할 수 있습니다:
<div id="__nuxt"></div>
<!-- spa 로딩 템플릿 -->
이렇게 하면 클라이언트 전용 페이지 하이드레이션 시 흰색 플래시를 방지할 수 있습니다.
browserDevtoolsTiming
브라우저 개발자 도구에서 Nuxt 훅의 성능 마커를 활성화합니다. 이는 Chromium 기반 브라우저의 Performance 탭에서 추적할 수 있는 성능 마커를 추가하여 디버깅 및 성능 최적화에 유용합니다.
개발 모드에서는 기본적으로 활성화되어 있습니다. 이 기능을 비활성화해야 하는 경우 다음과 같이 설정할 수 있습니다:
export default defineNuxtConfig({
experimental: {
browserDevtoolsTiming: false
}
})
debugModuleMutation
모듈 컨텍스트에서 nuxt.options의 변경 사항을 기록하여 Nuxt 초기화 단계에서 모듈이 수행한 설정 변경을 디버깅하는 데 도움을 줍니다.
debug 모드가 활성화된 경우 기본적으로 활성화되어 있습니다. 이 기능을 비활성화해야 하는 경우 다음과 같이 설정할 수 있습니다:
명시적으로 활성화하려면:
export default defineNuxtConfig({
experimental: {
debugModuleMutation: true
}
})
lazyHydration
<Lazy> 컴포넌트에 대한 하이드레이션 전략을 활성화하여, 컴포넌트가 필요할 때까지 하이드레이션을 지연시켜 성능을 향상시킵니다.
지연 하이드레이션은 기본적으로 활성화되어 있지만, 다음과 같이 비활성화할 수 있습니다:
export default defineNuxtConfig({
experimental: {
lazyHydration: false
}
})
templateImportResolution
Nuxt 템플릿에서 import가 어떻게 해석되는지 제어합니다. 기본적으로 Nuxt는 템플릿의 import를 해당 모듈 기준으로 해석하려고 시도합니다.
이 기능은 기본적으로 활성화되어 있으므로, 특정 환경에서 해석 충돌이 발생한다면 다음과 같이 비활성화할 수 있습니다:
export default defineNuxtConfig({
experimental: {
templateImportResolution: false
}
})
decorators
이 옵션은 esbuild 기반으로 Nuxt/Nitro 앱 전체에서 데코레이터 문법을 활성화합니다.
오랫동안 TypeScript는 compilerOptions.experimentalDecorators를 통해 데코레이터를 지원해왔습니다. 이 구현은 TC39 표준화 이전의 것이었습니다. 이제 데코레이터는 Stage 3 Proposal 단계에 있으며, TS 5.0+에서는 별도 설정 없이 지원됩니다(https://github.com/microsoft/TypeScript/pull/52582 및 https://devblogs.microsoft.com/typescript/announcing-typescript-5-0-beta/#decorators 참고).
experimental.decorators를 활성화하면 TC39 제안에 대한 지원이 활성화되며, TypeScript의 이전 compilerOptions.experimentalDecorators 구현에 대한 지원은 아닙니다.
사용법
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'를 반환합니다
purgeCachedData
Nuxt는 useAsyncData와 nuxtApp.static.data의 캐시된 데이터를 자동으로 정리합니다.
이는 메모리 누수를 방지하고 필요할 때 신선한 데이터를 로드하는 데 도움이 되지만, 다음과 같이 비활성화할 수 있습니다:
export default defineNuxtConfig({
experimental: {
purgeCachedData: false
}
})
granularCachedData
useAsyncData와 useFetch의 데이터를 새로고침할 때(watch, refreshNuxtData(), 수동 refresh() 호출 등) getCachedData의 결과를 호출하고 사용할지 여부를 제어합니다.
export default defineNuxtConfig({
experimental: {
granularCachedData: true
}
})
pendingWhenIdle
false로 설정하면, useAsyncData, useFetch, useLazyAsyncData, useLazyFetch에서 반환되는 pending 객체는 status가 pending일 때만 true인 계산 속성이 됩니다.
즉, immediate: false가 전달되면 첫 번째 요청이 이루어질 때까지 pending은 false가 됩니다.
export default defineNuxtConfig({
experimental: {
pendingWhenIdle: false
}
})