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 .を実行して、設定を自動的に移行してください。

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設定に使用可能なオプションは以下の通りです：

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

以下のローダーは Turbopack の webpack ローダー実装で動作することが確認されていますが、ここにリストされていなくても、多くの他の webpack ローダーも動作するはずです：

• babel-loader （Babel 設定ファイルが見つかった場合は自動的に設定されます）
• @svgr/webpack
• svg-inline-loader
• yaml-loader
• string-replace-loader
• raw-loader
• sass-loader （自動的に設定されます）
• graphql-tag/loader

サポートされていない Webpack ローダー機能

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

モジュールロード：

• importModule - サポートなし
• loadModule - サポートなし

ファイルシステムと出力：

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

コンテキストプロパティ：

• version - サポートなし
• mode - サポートなし
• target - サポートなし

ユーティリティ：

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

これらの機能のいずれかに大きく依存しているローダーがある場合は、issue をファイルしてください。

例

ルートディレクトリ

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

Next.js はプロジェクトのルートディレクトリを自動的に検出します。これは以下のファイルの 1 つを探すことで行われます：

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

異なるプロジェクト構造（例えば、ワークスペースを使用しない場合）の場合、rootオプションを手動で設定できます：

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

webpack ローダーの設定

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

• webpack ローダー API のコア部分のみが実装されています。現在、一部の一般的なローダーにはカバレッジが十分ですが、今後 API サポートを拡張する予定です。
• JavaScript コードを返すローダーのみがサポートされています。スタイルシートや画像などのファイルを変換するローダーは現在サポートされていません。
• webpack ローダーに渡されるオプションは、プレーン JavaScript のプリミティブ、オブジェクト、配列である必要があります。例えば、require()プラグインモジュールをオプション値として渡すことはできません。

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

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

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

補足：rulesオブジェクト内で使用されているグロブはファイル名に基づいてマッチングされます。ただし、グロブに/文字が含まれている場合は、完全なプロジェクト相対ファイルパスに基づいてマッチングされます。Windows ファイルパスは Unix 形式の/パス区切り文字に正規化されます。

Turbopack はRust globsetライブラリの修正版を使用しています。

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

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構文を使用してローダーがどこで実行されるかをさらに制限できます：

module.exports = {
  turbopack: {
    rules: {
      // '*'はすべてのファイルパスにマッチしますが、条件で
      // ローダーが実行される場所を制限します。
      '*': {
        condition: {
          all: [
            // 'foreign'は組み込み条件です。
            { not: 'foreign' },
            // 'path'は RegExp またはグロブ文字列です。RegExp は
            // 完全なプロジェクト相対ファイルパスのどこにでもマッチします。
            { path: /^img\/[0-9]{3}\// },
            {
              any: [
                { path: '*.svg' },
                // 'content'は常に RegExp で、ファイル内の
                // どこにでもマッチします。
                { 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 ランタイムで実行されるコードにマッチします。

ルールはオブジェクトまたはオブジェクトの配列にできます。配列は、互いに異なる条件をモデル化するのに役立つことが多いです：

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の新しい宛先にマッピングします：

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フィールドを使用します：

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

これは元の解決エクステンションを提供されたリストで上書きします。デフォルトのエクステンションを含めることを忘れないでください。

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

デバッグ ID

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

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

module.exports = {
  turbopack: {
    debugIds: true,
  },
}

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

バージョン履歴