Nuxt 실험적 기능은 Nuxt 구성 파일에서 활성화할 수 있습니다.

내부적으로, Nuxt는 @nuxt/schema를 사용하여 이러한 실험적 기능을 정의합니다. 더 많은 정보는 API 문서나 소스 코드를 참조하세요.

asyncContext

Nuxt와 Nitro에서 중첩된 composable에 접근할 수 있도록 네이티브 비동기 컨텍스트를 활성화합니다. 이는 비동기 composable 내부에서 composable을 사용할 수 있는 가능성을 열어주며, 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

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

기본적으로 활성화되어 있습니다.

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() 호출 후 sessionStorage에서 Nuxt 앱 상태를 복원할 수 있습니다.

하이드레이션 오류를 피하기 위해 Vue 앱이 마운트된 후에만 적용되며, 초기 로드 시 깜빡임이 발생할 수 있습니다.

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

노드 서버를 사용할 때 초기 힌트를 작성하는 기능을 활성화합니다.

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')를 사용하여 페이지 내에서 타입 파라미터를 얻을 수도 있습니다.

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가 클라이언트 빌드에서 Node.js import를 자동으로 폴리필합니다. unenv를 사용합니다.

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 참조 값을 새로 고치는 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.lock
bun.lockb

또한, srcDir 내의 파일 변경은 Vue 클라이언트/서버 번들의 재빌드를 트리거합니다. Nitro는 항상 재빌드되지만, Nitro가 캐시 가능한 아티팩트와 그 해시를 발표할 수 있도록 작업이 진행 중입니다.

extraPageMetaExtractionKeys

definePageMeta() 매크로는 페이지에 대한 빌드 시점 메타를 수집하는 유용한 방법입니다. Nuxt 자체는 리다이렉트, 페이지 별칭 및 사용자 정의 경로와 같은 내부 기능을 지원하는 키 목록을 제공합니다.

이 옵션은 scanPageMeta를 사용할 때 페이지 메타데이터에서 추가 키를 추출할 수 있도록 허용합니다.

definePageMeta({
  foo: 'bar'
})

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 기반 브라우저의 성능 탭에서 추적할 수 있는 성능 마커를 추가하여 디버깅 및 성능 최적화에 유용합니다.

개발 모드에서는 기본적으로 활성화되어 있습니다. 이 기능을 비활성화해야 하는 경우, 다음과 같이 설정할 수 있습니다:

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가 대기 중일 때만 true인 계산된 속성이 됩니다.

이는 immediate: false가 전달될 때, 첫 번째 요청이 이루어질 때까지 pending이 false가 됨을 의미합니다.

export default defineNuxtConfig({
  experimental: {
    pendingWhenIdle: false
  }
})