実験的な機能

Nuxt には、設定ファイルで有効にできる実験的機能が含まれています。

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

alwaysRunFetchOnKeyChange

キーが変更されたときに useFetch を実行するかどうか。immediate: false に設定されていて、まだトリガーされていない場合でも実行されます。

immediate: true であるか、すでにトリガーされている場合、useFetch と useAsyncData はキーが変更されるたびに常に実行されます。

このフラグはデフォルトで無効になっていますが、この機能を有効にすることができます。

export default defineNuxtConfig({
  experimental: {
    alwaysRunFetchOnKeyChange: true,
  },
})

appManifest

クライアント側でルートルールを尊重するためにアプリマニフェストを使用します。

このフラグはデフォルトで有効になっていますが、この機能を無効にすることができます。

export default defineNuxtConfig({
  experimental: {
    appManifest: false,
  },
})

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: false,
  },
})

extractAsyncDataHandlers

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>

この変換の利点は、データフェッチロジックを分割できることです。必要に応じてコードをロードすることも可能です。

emitRouteChunkError

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

デフォルトでは、Nuxt は新しいルートへのナビゲーション時にチャンクのロードに失敗した場合 (automatic) も新しいルートをリロードします。

automatic-immediate を設定すると、Nuxt はチャンクのロードに失敗した直後に現在のルートをリロードします (ナビゲーションを待つことなく)。これは、ナビゲーションによってトリガーされないチャンクエラー、たとえば Nuxt アプリが遅延コンポーネントのロードに失敗した場合などに役立ちます。この動作の潜在的な欠点は、意図しないリロードです。たとえば、アプリがエラーの原因となったチャンクを必要としない場合などです。

これを false に設定することで自動処理を無効にしたり、manual に設定することでチャンクエラーを手動で処理したりできます。

export default defineNuxtConfig({
  experimental: {
    emitRouteChunkError: 'automatic', // or 'automatic-immediate', 'manual' or false
  },
})

enforceModuleCompatibility

Nuxt モジュールが互換性がない場合に、Nuxt がエラーをスロー (およびロードに失敗) するかどうか。

この機能はデフォルトで無効になっています。

export default defineNuxtConfig({
  experimental: {
    enforceModuleCompatibility: true,
  },
})

restoreState

チャンクエラーまたは手動の reloadNuxtApp() 呼び出し後にページをリロードしたときに、Nuxt アプリの状態を sessionStorage から復元できるようにします。

ハイドレーションエラーを避けるため、Vue アプリがマウントされた後にのみ適用されます。つまり、最初のロード時にちらつきが発生する可能性があります。

export default defineNuxtConfig({
  experimental: {
    restoreState: true,
  },
})

inlineRouteRules

defineRouteRules を使用して、ページレベルでルートルールを定義します。

export default defineNuxtConfig({
  experimental: {
    inlineRouteRules: true,
  },
})

ページの path に基づいて、一致するルートルールが作成されます。

renderJsonPayloads

複雑な型の復元をサポートする JSON ペイロードのレンダリングを可能にします。

このフラグはデフォルトで有効になっていますが、この機能を無効にすることができます。

export default defineNuxtConfig({
  experimental: {
    renderJsonPayloads: false,
  },
})

noVueServer

Nitro 内の Vue サーバーレンダラーエンドポイントを無効にします。

export default defineNuxtConfig({
  experimental: {
    noVueServer: true,
  },
})

parseErrorData

サーバーエラーページをレンダリングするときに error.data をパースするかどうか。

このフラグはデフォルトで有効になっていますが、この機能を無効にすることができます。

export default defineNuxtConfig({
  experimental: {
    parseErrorData: false,
  },
})

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

node サーバーを使用している場合に、早期ヒントの書き込みを有効にします。

export default defineNuxtConfig({
  experimental: {
    writeEarlyHints: true,
  },
})

componentIslands

<NuxtIsland> および .island.vue ファイルを使用した実験的なコンポーネントアイランドのサポートを有効にします。

export default defineNuxtConfig({
  experimental: {
    componentIslands: true, // false or 'local+remote'
  },
})

localLayerAliases

レイヤー内の ~、~~、@、@@ エイリアスを、それぞれのレイヤーソースおよびルートディレクトリに関して解決します。

このフラグはデフォルトで有効になっていますが、この機能を無効にすることができます。

export default defineNuxtConfig({
  experimental: {
    localLayerAliases: false,
  },
})

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' or 'parcel' are also options
  },
})

sharedPrerenderData

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

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

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

この機能を有効にする際には、データの固有のキーが常に同じデータに解決されるようにすることが特に重要です。たとえば、特定のページに関連するデータをフェッチするために useAsyncData を使用している場合、そのデータに一意に一致するキーを提供する必要があります。( useFetch はこれを自動的に行うはずです。)

// This would be unsafe in a dynamic page (e.g. `[slug].vue`) because the route slug makes a difference
// to the data fetched, but Nuxt can't know that because it's not reflected in the key.
const route = useRoute()
const { data } = await useAsyncData(async () => {
  return await $fetch(`/api/my-page/${route.params.slug}`)
})
// Instead, you should use a key that uniquely identifies the data fetched.
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 ||= Buffer

scanPageMeta

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

これは、変数や条件付き割り当てではなく、静的または文字列/配列でのみ機能します。詳細については、元の問題を参照してください。

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

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

export default defineNuxtConfig({
  experimental: {
    scanPageMeta: false,
  },
})

cookieStore

Cookie の更新をリッスンし (ブラウザがサポートしている場合)、useCookie の参照値をリフレッシュする CookieStore サポートを有効にします。

このフラグはデフォルトで有効になっていますが、この機能を無効にすることができます。

export default defineNuxtConfig({
  experimental: {
    cookieStore: false,
  },
})

buildCache

設定とソースファイルのハッシュに基づいて 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 がキャッシュ可能なアーティファクトとそのハッシュを通知できるようにするための作業が進行中です)。

checkOutdatedBuildInterval

新しいビルドをチェックする時間間隔 (ミリ秒単位) を設定します。experimental.appManifest が false の場合、無効になります。

無効にするには false に設定します。

export default defineNuxtConfig({
  experimental: {
    checkOutdatedBuildInterval: 3600000, // 1 hour, or false to disable
  },
})

extraPageMetaExtractionKeys

definePageMeta() マクロは、ページに関するビルド時メタデータを収集するための便利な方法です。Nuxt 自体は、リダイレクト、ページエイリアス、カスタムパスなどの内部機能を強化するために使用される、サポートされているキーのセットリストを提供します。

このオプションを使用すると、scanPageMeta を使用する際に、ページメタデータから追加のキーを抽出できます。

<script lang="ts" setup>
definePageMeta({
  foo: 'bar',
})
</script>

export default defineNuxtConfig({
  experimental: {
    extraPageMetaExtractionKeys: ['foo'],
  },
  hooks: {
    'pages:resolved' (ctx) {
      // ✅ foo is available
    },
  },
})

これにより、モジュールはビルドコンテキストでページメタデータから追加のメタデータにアクセスできます。モジュール内でこれを使用する場合、NuxtPage タイプに独自のキーを追加することもお勧めします。

navigationRepaint

ナビゲーションの前に単一のアニメーションフレームを待ち、ブラウザが再描画してユーザーの操作を認識する機会を与えます。

これにより、プリレンダリングされたルートへのナビゲーション時に INP を削減できます。

このフラグはデフォルトで有効になっていますが、この機能を無効にすることができます。

export default defineNuxtConfig({
  experimental: {
    navigationRepaint: false,
  },
})

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

ブラウザの開発者ツールで 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 はテンプレート内のインポートを、テンプレートを追加したモジュールからの相対パスで解決しようとします。これを false に設定すると、この動作が無効になります。特定の環境で解決の競合が発生している場合に役立つことがあります。

このフラグはデフォルトで有効になっていますが、この機能を無効にすることができます。

export default defineNuxtConfig({
  experimental: {
    templateImportResolution: false,
  },
})

templateRouteInjection

デフォルトでは、自動インポートされた useRoute() コンポーザブルが返すルートオブジェクトは、<NuxtPage> で表示中の現在のページと同期しています。vue-router のエクスポートされた useRoute や Vue テンプレートで利用できるデフォルトの $route オブジェクトには当てはまりません。

このオプションを有効にすると、mixin が注入され、$route テンプレートオブジェクトが Nuxt が管理する useRoute() と同期するように維持されます。

このフラグはデフォルトで有効になっていますが、この機能を無効にすることができます。

export default defineNuxtConfig({
  experimental: {
    templateRouteInjection: false,
  },
})

decorators

このオプションは、Nuxt/Nitro アプリ全体でデコレータ構文を有効にします。esbuild.

長い間、TypeScript は compilerOptions.experimentalDecorators を介してデコレータをサポートしていました。この実装は TC39 標準化プロセスよりも先行していました。現在、デコレータはステージ 3 提案であり、TS 5.0 以降では特別な設定なしでサポートされています (参照:https://github.com/microsoft/TypeScript/pull/52582GlobalComponentshttps://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()
// this will return 'decorated'

defaults

これにより、コア Nuxt コンポーネントおよびコンポーザブルのデフォルトオプションを指定できます。

これらのオプションは、将来 app.config または app/ ディレクトリに移動される可能性があります。

export default defineNuxtConfig({
  experimental: {
    defaults: {
      nuxtLink: {
        componentName: 'NuxtLink',
        prefetch: true,
        prefetchOn: {
          visibility: true,
        },
      },
      useAsyncData: {
        deep: true,
      },
    },
  },
})

purgeCachedData

ルートナビゲーション時に Nuxt の静的および asyncData キャッシュをクリーンアップするかどうか。

Nuxt は、useAsyncData および nuxtApp.static.data からキャッシュされたデータを自動的にパージします。これにより、メモリリークを防ぎ、必要に応じて新しいデータがロードされることを保証しますが、無効にすることも可能です。

このフラグはデフォルトで有効になっていますが、この機能を無効にすることができます。

export default defineNuxtConfig({
  experimental: {
    purgeCachedData: false,
  },
})

granularCachedData

useAsyncData と useFetch のデータをリフレッシュする際 (watch、refreshNuxtData()、または手動の refresh() 呼び出しのいずれかによって)、getCachedData からの結果を呼び出し、使用するかどうか。

このフラグはデフォルトで有効になっていますが、この機能を無効にすることができます。

export default defineNuxtConfig({
  experimental: {
    granularCachedData: false,
  },
})

headNext

ヘッドの最適化を使用する

• Capo.js ヘッドプラグインを追加して、ヘッド内のタグをよりパフォーマンスの高い方法でレンダリングします。
• ハッシュハイドレーションプラグインを使用して初期ハイドレーションを削減します。

このフラグはデフォルトで有効になっていますが、この機能を無効にすることができます。

export default defineNuxtConfig({
  experimental: {
    headNext: false,
  },
})

pendingWhenIdle

useAsyncData および useFetch について、データがまだフェッチされていないときに pending が true であるべきかどうか。

このフラグはデフォルトで無効になっていますが、この機能を有効にすることができます。

export default defineNuxtConfig({
  experimental: {
    pendingWhenIdle: true,
  },
})

entryImportMap

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

これにより、<head> タグの先頭にインポートマップが注入されます。

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

Vite によって出力されるスクリプトチャンク内では、インポートは #entry から行われます。これは、エントリーへの変更が、それ以外は変更されていないチャンクを無効にしないことを意味します。

この機能を無効にする必要がある場合は、そうすることができます。

export default defineNuxtConfig({
  experimental: {
    entryImportMap: false,
  },
  // or, better, simply tell vite your desired target
  // which nuxt will respect
  vite: {
    build: {
      target: 'safari13',
    },
  },
})

typescriptPlugin

@dxup/nuxt モジュールを使用して、TypeScript 開発者エクスペリエンスを強化します。

この実験的プラグインは、Nuxt アプリケーションで TypeScript を使用する際の DX を向上させるための、改善された TypeScript 統合と開発ツールを提供します。

このフラグはデフォルトで無効になっていますが、この機能を有効にすることができます。

export default defineNuxtConfig({
  experimental: {
    typescriptPlugin: true,
  },
})