コンテンツにスキップ
設定next.config.jsturbopack

turbopack

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 のコンパイルに組み込みサポートがあるため、css-loader、postcss-loader、または babel-loader（@babel/preset-env を使用している場合）は不要です。

リファレンス

オプション

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 オブジェクトで使用される glob は、ファイル名に基づいて一致します。ただし、glob に / 文字が含まれている場合は、プロジェクト相対パス全体に基づいて一致します。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,
  },
}

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

バージョン履歴

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