Nuxtの実験的機能は、Nuxtの設定ファイルで有効にすることができます。

内部的には、Nuxtは@nuxt/schemaを使用してこれらの実験的機能を定義しています。詳細については、APIドキュメントまたはソースコードを参照してください。

asyncContext

ネイティブの非同期コンテキストを有効にして、NuxtおよびNitroでネストされたコンポーザブルにアクセスできるようにします。これにより、非同期コンポーザブル内でコンポーザブルを使用する可能性が開かれ、Nuxt instance is unavailableエラーが発生する可能性を減らします。

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アプリが遅延コンポーネントの読み込みに失敗した場合です。この動作の潜在的な欠点は、エラーを引き起こしたチャンクがアプリに必要ない場合などに、望ましくないリロードが発生することです。

自動処理を無効にするには、これを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のインポートを自動的にポリフィルします。これは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

ブラウザがサポートしている場合、Cookieの更新をリッスンし、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.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を設定すると、これらの2つの値が一致し、VueはNuxtのコンポーネント命名パターンに一致するコンポーネント名を生成します。

spaLoadingTemplateLocation

クライアント専用ページ（ssr: false）をレンダリングする際に、オプションでローディング画面（app/spa-loading-template.htmlから）をレンダリングします。

withinに設定すると、次のようにレンダリングされます：

<div id="__nuxt">
  <!-- spa loading template -->
</div>

または、bodyに設定してNuxtアプリのルートと並行してテンプレートをレンダリングすることもできます：

<div id="__nuxt"></div>
<!-- spa loading template -->

これにより、クライアント専用ページをハイドレートする際の白いフラッシュを回避します。

browserDevtoolsTiming

ブラウザのdevtoolsで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テンプレート内のインポートの解決方法を制御します。デフォルトでは、Nuxtはテンプレート内のインポートをそれを追加したモジュールに相対的に解決しようとします。

これはデフォルトで有効になっているため、特定の環境で解決の競合が発生している場合は、この動作を無効にすることができます：

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
  }
})