コンテンツにスキップ
設定next.config.js オプションturbopack

turbopack

この機能は現在実験的であり、変更される可能性があります。本番環境での使用は推奨されません。お試しいただき、GitHubでフィードバックをお寄せください。

turbopack オプションを使用すると、Turbopack をカスタマイズして、さまざまなファイルを変換したり、モジュールの解決方法を変更したりできます。

知っておくと良いこと: turbopack オプションは、以前は Next.js バージョン 13.0.0 から 15.2.x まで experimental.turbo という名前でした。experimental.turbo オプションは Next.js 16 で削除される予定です。

古いバージョンの Next.js を使用している場合は、npx @next/codemod@latest next-experimental-turbo-to-turbopack . を実行して、設定を自動的に移行してください。

next.config.ts
import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  turbopack: {
    // ...
  },
}
 
export default nextConfig

知っておくと良いこと:

  • Next.js 用の Turbopack は、組み込み機能のためにローダーやローダー設定を必要としません。Turbopack は CSS および最新 JavaScript のコンパイルを組み込みでサポートしているため、@babel/preset-env を使用している場合は css-loader、postcss-loader、または babel-loader は必要ありません。

リファレンス

オプション

turbopack 設定で利用可能なオプションは次のとおりです。

オプション説明
rootアプリケーションのルートディレクトリを設定します。絶対パスである必要があります。
rulesTurbopack で実行するときに適用される、サポートされている webpack ローダーのリスト。
resolveAliasエイリアスされたインポートを、代わりにロードされるモジュールにマッピングします。
resolveExtensionsファイルをインポートするときに解決される拡張機能のリスト。
debugIdsJavaScript バンドルおよびソースマップで デバッグID の生成を有効にします。

サポートされているローダー

Turbopack の webpack ローダー実装で動作することがテストされたローダーは以下の通りですが、ここにリストされていない他の多くの webpack ローダーも機能するはずです。

Webpackローダー機能の欠如

Turbopack は webpack ローダーを実行するために loader-runner ライブラリを使用しており、標準的なローダー API のほとんどを提供します。ただし、一部の機能はサポートされていません。

モジュールのロード

ファイルシステムと出力

  • fs - 部分的サポート: 現在 fs.readFile のみが実装されています。
  • emitFile - サポートなし

コンテキストプロパティ

ユーティリティ

  • utils - サポートなし
  • resolve - サポートなし (代わりに getResolve を使用してください)

これらの機能のいずれかにクリティカルに依存しているローダーがある場合は、問題を報告してください。

例

ルートディレクトリ

Turbopack はモジュールを解決するためにルートディレクトリを使用します。プロジェクトルート外のファイルは解決されません。

Next.js はプロジェクトのルートディレクトリを自動的に検出します。これは、次のいずれかのファイルを探すことによって行われます。

  • pnpm-lock.yaml
  • package-lock.json
  • yarn.lock
  • bun.lock
  • bun.lockb

異なるプロジェクト構造の場合、たとえばワークスペースを使用しない場合、root オプションをマニュアルで設定できます。

next.config.js
const path = require('path')
module.exports = {
  turbopack: {
    root: path.join(__dirname, '..'),
  },
}

Webpackローダーの設定

組み込み機能以上のローダーサポートが必要な場合、多くの webpack ローダーは既に Turbopack で動作します。現在、いくつかの制限があります。

  • webpack ローダー API のコアサブセットのみが実装されています。現在、いくつかの人気のあるローダーで十分なカバレッジがありますが、API サポートは将来的に拡大していきます。
  • JavaScript コードを返すローダーのみがサポートされています。スタイルシートや画像のようなファイルを変換するローダーは、現在サポートされていません。
  • webpack ローダーに渡されるオプションは、プレーンな JavaScript のプリミティブ、オブジェクト、および配列である必要があります。たとえば、オプションの値として require() プラグインモジュールを渡すことはできません。

ローダーを設定するには、インストールしたローダーの名前とオプションを next.config.js に追加し、ファイル拡張子をローダーのリストにマッピングします。ルールは順番に評価されます。

以下は、.svg ファイルをインポートして React コンポーネントとしてレンダリングできるようにする @svgr/webpack ローダーを使用した例です。

next.config.js
module.exports = {
  turbopack: {
    rules: {
      '*.svg': {
        loaders: ['@svgr/webpack'],
        as: '*.js',
      },
    },
  },
}

知っておくと良いこと: rules オブジェクトで使用されるグロブは、ファイル名に基づいて一致しますが、グロブに / 文字が含まれている場合、それは完全なプロジェクト相対ファイルパスに基づいて一致します。Windows のファイルパスは Unix スタイルの / パス区切り文字を使用するように正規化されます。

Turbopack は、Rust の globset ライブラリ を変更したバージョンを使用しています。

設定オプションが必要なローダーの場合、文字列の代わりにオブジェクト形式を使用できます。

next.config.js
module.exports = {
  turbopack: {
    rules: {
      '*.svg': {
        loaders: [
          {
            loader: '@svgr/webpack',
            options: {
              icon: true,
            },
          },
        ],
        as: '*.js',
      },
    },
  },
}

知っておくと良いこと: Next.js バージョン 13.4.4 より前では、turbopack.rules は turbo.loaders という名前で、*.mdx の代わりに .mdx のようなファイル拡張子のみを受け入れていました。

高度なWebpackローダー条件

高度な condition 構文を使用して、ローダーが実行される場所をさらに制限できます。

next.config.js
module.exports = {
  turbopack: {
    rules: {
      // '*' will match all file paths, but we restrict where our
      // rule runs with a condition.
      '*': {
        condition: {
          all: [
            // 'foreign' is a built-in condition.
            { not: 'foreign' },
            // 'path' can be a RegExp or a glob string. A RegExp matches
            // anywhere in the full project-relative file path.
            { path: /^img\/[0-9]{3}\// },
            {
              any: [
                { path: '*.svg' },
                // 'content' is always a RegExp, and can match
                // anywhere in the file.
                { content: /\<svg\W/ },
              ],
            },
          ],
        },
        loaders: ['@svgr/webpack'],
        as: '*.js',
      },
    },
  },
}
  • サポートされているブール演算子は {all: [...]}、{any: [...]}、および {not: ...} です。
  • サポートされているカスタマイズ可能な演算子は {path: string | RegExp} および {content: RegExp} です。path と content が同じオブジェクトに指定されている場合、暗黙的な and として機能します。

さらに、いくつかの組み込み条件がサポートされています。

  • browser: クライアントで実行されるコードに一致します。サーバーコードは {not: 'browser'} を使用して一致させることができます。
  • foreign: node_modules 内のコード、および一部の Next.js 内部ファイルに一致します。通常、ローダーを {not: 'foreign'} に制限したい場合が多いです。これにより、ローダーが呼び出されるファイル数を減らすことでパフォーマンスが向上する可能性があります。
  • development: next dev を使用している場合に一致します。
  • production: next build を使用している場合に一致します。
  • node: デフォルトの Node.js ランタイムで実行されるコードに一致します。
  • edge-light: Edge ランタイムで実行されるコードに一致します。

ルールはオブジェクトまたはオブジェクトの配列にすることができます。配列は、不連続な条件をモデリングするのに役立つことがよくあります。

next.config.js
module.exports = {
  turbopack: {
    rules: {
      '*.svg': [
        {
          condition: 'browser',
          loaders: ['@svgr/webpack'],
          as: '*.js',
        },
        {
          condition: { not: 'browser' },
          loaders: [require.resolve('./custom-svg-loader.js')],
          as: '*.js',
        },
      ],
    },
  },
}

知っておくと良いこと: すべての一致するルールは順番に実行されます。

エイリアスの解決

Turbopack は、webpack の resolve.alias 設定と同様に、エイリアスを通じてモジュール解決を変更するように設定できます。

解決エイリアスを設定するには、next.config.js でインポートパターンを新しい宛先にマッピングします。

next.config.js
module.exports = {
  turbopack: {
    resolveAlias: {
      underscore: 'lodash',
      mocha: { browser: 'mocha/browser-entry.js' },
    },
  },
}

これにより、underscore パッケージのインポートが lodash パッケージにエイリアスされます。つまり、import underscore from 'underscore' は、underscore の代わりに lodash モジュールをロードします。

Turbopack は、Node.js の 条件付きエクスポート と同様に、このフィールドを通じて条件付きエイリアスもサポートしています。現時点では browser 条件のみがサポートされています。上記の例では、Turbopack がブラウザ環境をターゲットとする場合、mocha モジュールのインポートは mocha/browser-entry.js にエイリアスされます。

カスタム拡張機能の解決

Turbopack は、webpack の resolve.extensions 設定と同様に、カスタム拡張機能でモジュールを解決するように設定できます。

解決拡張機能を設定するには、next.config.js で resolveExtensions フィールドを使用します。

next.config.js
module.exports = {
  turbopack: {
    resolveExtensions: ['.mdx', '.tsx', '.ts', '.jsx', '.js', '.mjs', '.json'],
  },
}

これにより、元の解決拡張機能は提供されたリストで上書きされます。デフォルトの拡張機能を含めるようにしてください。

webpack から Turbopack へのアプリの移行方法に関する詳細情報やガイダンスについては、webpack 互換性に関する Turbopack のドキュメント を参照してください。

デバッグID

Turbopack は、JavaScript バンドルおよびソースマップで デバッグID を生成するように設定できます。

デバッグIDを設定するには、next.config.js で debugIds フィールドを使用します。

next.config.js
module.exports = {
  turbopack: {
    debugIds: true,
  },
}

このオプションは、互換性を確保するために JavaScript バンドルにデバッグIDのポリフィルを自動的に追加します。デバッグIDは globalThis._debugIds グローバル変数で利用できます。

バージョン履歴

バージョン変更履歴
16.0.0turbopack.debugIds が追加されました。
16.0.0turbopack.rules.*.condition が追加されました。
15.3.0experimental.turbo は turbopack に変更されました。
13.0.0experimental.turbo が導入されました。