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

emitRouteChunkError

vite/webpackチャンクの読み込みエラーが発生したときにapp:chunkErrorフックを発行します。デフォルトの動作は、チャンクの読み込みに失敗したときに新しいルートへのナビゲーションでルートをリロードすることです。

これを'automatic-immediate'に設定すると、ナビゲーションを待たずに現在のルートを即座にリロードします。これは、ナビゲーションによってトリガーされないチャンクエラー、例えば遅延コンポーネントの読み込みに失敗した場合に便利です。この動作の潜在的な欠点は、エラーを引き起こしたチャンクがアプリに必要ない場合でも、望ましくないリロードが発生することです。

自動処理を無効にするには、これを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'
  }
})

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

Nuxtは、プリレンダリングされたページ間でペイロードデータを自動的に共有します。これは、useAsyncDataやuseFetchを使用して異なるページで同じデータをフェッチするサイトをプリレンダリングする際に、パフォーマンスの大幅な向上をもたらすことがあります。

必要に応じて、この機能を無効にすることができます。

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

この機能を有効にする際には、データの一意のキーが常に同じデータに解決可能であることを確認することが特に重要です。例えば、特定のページに関連するデータをフェッチするために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

Nuxtは、ビルド時にモジュールにdefinePageMetaで定義された一部のルートメタデータ（具体的にはalias、name、path、redirect、props、middleware）を公開します。

これは、変数や条件付き代入ではなく、静的または文字列/配列でのみ動作します。詳細とコンテキストについては元の問題を参照してください。

デフォルトでは、ページメタデータはすべてのルートがpages:extendで登録された後にのみスキャンされます。その後、別のフックpages:resolvedが呼び出されます。

プロジェクトで問題が発生する場合、この機能を無効にすることができます。

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

Nuxtは、自動生成されたVueコンポーネント名を、コンポーネントを自動インポートするために使用する完全なコンポーネント名に一致させるように更新します。

問題が発生した場合、この機能を無効にすることができます。

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

デフォルトでは、手動で設定していない場合、Vueはコンポーネントのファイル名に一致するコンポーネント名を割り当てます。

├─ components/
├─── SomeFolder/
├───── MyComponent.vue

この場合、Vueにとってコンポーネント名はMyComponentになります。これを<KeepAlive>で使用したり、Vue DevToolsで識別したりするには、このコンポーネントを使用する必要があります。

しかし、自動インポートするためには、SomeFolderMyComponentを使用する必要があります。

experimental.normalizeComponentNamesを設定すると、これらの2つの値が一致し、VueはNuxtのコンポーネント命名パターンに一致するコンポーネント名を生成します。

spaLoadingTemplateLocation

クライアント専用ページ（ssr: false）をレンダリングする際に、オプションでロード画面（~/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
  }
})

entryImportMap

デフォルトで、Nuxtはインポートマップを使用してバンドルのエントリーチャンクを解決し、チャンクの安定性を向上させます。

これにより、<head>タグの上部にインポートマップが挿入されます：

<script type="importmap">{"imports":{"#entry":"/_nuxt/DC5HVSK5.js"}}</script>

Viteによって発行されたスクリプトチャンク内では、インポートは#entryから行われます。これにより、エントリーチャンクの変更が他に変更されていないチャンクを無効にしないようになります。

この機能を無効にする必要がある場合は、次のように設定できます：

export default defineNuxtConfig({
  experimental: {
    entryImportMap: false
  },
// または、単にviteに希望のターゲットを伝える
  // nuxtが尊重します
  vite: {
    build: {
      target: 'safari13'
    },
  },
})