Turbopack

Turbopackは、Rustで記述され、Next.jsに組み込まれたJavaScriptとTypeScriptに最適化されたインクリメンタルバンドラーです。Pages RouterとApp Routerの両方でTurbopackを使用することで、はるかに高速なローカル開発体験を実現できます。

Turbopackを選ぶ理由

Next.jsのパフォーマンスを向上させるためにTurbopackを構築しました。その特徴は以下の通りです。

統一されたグラフ: Next.jsは複数の出力環境（例：クライアントとサーバー）をサポートしています。複数のコンパイラを管理し、バンドルを結合するのは面倒です。Turbopackは、すべての環境に対して単一の統一されたグラフを使用します。
バンドル vs. ネイティブESM: 一部のツールは開発時にバンドルをスキップし、ブラウザのネイティブESMに依存します。これは小規模なアプリではうまく機能しますが、過剰なネットワークリクエストのために大規模なアプリでは速度が低下する可能性があります。Turbopackは開発時にバンドルを行いますが、大規模なアプリを高速に保つために最適化された方法で行います。
インクリメンタル計算: Turbopackはコア間で作業を並列化し、結果を関数レベルまでキャッシュします。一度完了した作業は、Turbopackが繰り返すことはありません。
遅延バンドル: Turbopackは開発サーバーによって実際に要求されたものだけをバンドルします。この遅延アプローチにより、初期コンパイル時間とメモリ使用量を削減できます。

はじめに

Next.jsプロジェクトでTurbopackを有効にするには、package.jsonファイルのdev、build、startスクリプトに--turbopackフラグを追加します。

package.json

{
  "scripts": {
    "dev": "next dev --turbopack",
    "build": "next build --turbopack",
    "start": "next start --turbopack"
  }
}

現在、dev向けのTurbopackは安定していますが、buildはアルファ版です。Turbopackが安定に近づくにつれて、本番サポートに積極的に取り組んでいます。

対応機能

Next.jsのTurbopackは、一般的なユースケースではゼロコンフィギュレーションで動作します。以下は、すぐに使えるサポートの概要と、必要に応じてTurbopackをさらに設定する方法への参照です。

言語機能

機能	ステータス	メモ
JavaScript & TypeScript	対応済み	内部でSWCを使用します。型チェックはTurbopackでは行われません（型チェックには`tsc --watch`を実行するか、IDEに依存してください）。
ECMAScript (ESNext)	対応済み	Turbopackは、SWCの対応範囲と一致する最新のECMAScript機能をサポートしています。
CommonJS	対応済み	`require()`構文はすぐに処理されます。
ESM	対応済み	静的および動的な`import`は完全にサポートされています。
Babel	一部未対応	TurbopackにはデフォルトでBabelは含まれていません。ただし、Turbopack設定を通じて`babel-loader`を構成できます。

フレームワークとReact機能

機能	ステータス	メモ
JSX / TSX	対応済み	SWCがJSX/TSXのコンパイルを処理します。
高速リフレッシュ	対応済み	設定不要です。
React Server Components (RSC)	対応済み	Next.js App Router用。Turbopackは正しいサーバー/クライアントバンドルを保証します。
ルートレイアウトの作成	未対応	App Routerでのルートレイアウトの自動作成はサポートされていません。Turbopackは手動で作成するよう指示します。

CSSとスタイリング

機能	ステータス	メモ
グローバルCSS	対応済み	アプリケーションで`.css`ファイルを直接インポートできます。
CSS Modules	対応済み	`.module.css`ファイルはネイティブで動作します（Lightning CSS）。
CSSネスト	対応済み	Lightning CSSは最新のCSSネストをサポートしています。
@import構文	対応済み	複数のCSSファイルを結合します。
PostCSS	対応済み	Node.jsワーカープールで`postcss.config.js`を自動的に処理します。Tailwind、Autoprefixerなどに便利です。
Sass / SCSS	対応済み (Next.js)	Next.jsでは、Sassはすぐにサポートされています。将来的には、Turbopackスタンドアロンの使用にはローダー設定が必要になる可能性があります。
Less	プラグイン経由で計画中	デフォルトではまだサポートされていません。カスタムローダーが安定すれば、ローダー設定が必要になる可能性が高いです。
Lightning CSS	使用中	CSS変換を処理します。一部の低使用CSSモジュール機能（独立した擬似クラスとしての`:local/:global`など）はまだサポートされていません。詳細については以下を参照してください。

アセット

機能	ステータス	メモ
静的アセット（画像、フォント）	対応済み	`import img from './img.png'`のようなインポートはすぐに動作します。Next.jsでは、`<Image />`コンポーネント用のオブジェクトを返します。
JSONインポート	対応済み	`.json`ファイルからの名前付きインポートまたはデフォルトインポートがサポートされています。

モジュール解決

機能	ステータス	メモ
パスエイリアス	対応済み	`tsconfig.json`の`paths`と`baseUrl`を読み込み、Next.jsの動作と一致させます。
手動エイリアス	対応済み	`next.config.js`で`resolveAlias`を設定します（`webpack.resolve.alias`に似ています）。
カスタム拡張子	対応済み	`next.config.js`で`resolveExtensions`を設定します。.
AMD	一部対応	基本的な変換は機能しますが、高度なAMDの使用は制限されます。

パフォーマンスと高速リフレッシュ

機能	ステータス	メモ
高速リフレッシュ	対応済み	JavaScript、TypeScript、CSSをフルリフレッシュなしで更新します。
インクリメンタルバンドル	対応済み	Turbopackは開発サーバーによって要求されたものだけを遅延的にビルドし、大規模なアプリを高速化します。

未対応および未計画の機能

一部の機能はまだ実装されていません、または計画されていません

レガシーCSSモジュール機能
- 独立した:localおよび:global疑似クラス（関数バリアント:global(...)のみ対応）。
- @valueルール（CSS変数に置き換えられました）。
- :importおよび:export ICSSルール。
next.config.js内のwebpack()設定 Turbopackはwebpackを置き換えるため、webpack()設定は認識されません。代わりにexperimental.turbo設定を使用してください。
AMP Next.jsでのTurbopackサポートは計画されていません。
Yarn PnP Next.jsでのTurbopackサポートは計画されていません。
experimental.urlImports Turbopackでは計画されていません。
experimental.esmExternals 計画されていません。TurbopackはNext.jsのレガシーなesmExternals設定をサポートしていません。
一部のNext.js実験的フラグ
- experimental.typedRoutes
- experimental.nextScriptWorkers
- experimental.sri.algorithm
- experimental.fallbackNodePolyfills 将来的に実装を予定しています。

各機能フラグとそのステータスの詳細な内訳については、Turbopack APIリファレンスを参照してください。

設定

Turbopackは、next.config.js（またはnext.config.ts）のturbopackキーで設定できます。設定オプションには以下が含まれます。

rules ファイル変換のための追加のwebpackローダーを定義します。
resolveAlias 手動でエイリアスを作成します（webpackのresolve.aliasに似ています）。
resolveExtensions モジュール解決のためのファイル拡張子を変更または拡張します。
moduleIds モジュールIDの生成方法を設定します（'named' vs 'deterministic'）。
treeShaking 開発および将来の本番ビルドでツリーシェイキングを有効または無効にします。
memoryLimit Turbopackのメモリ制限（バイト単位）を設定します。

next.config.js

module.exports = {
  turbopack: {
    // Example: adding an alias and custom file extension
    resolveAlias: {
      underscore: 'lodash',
    },
    resolveExtensions: ['.mdx', '.tsx', '.ts', '.jsx', '.js', '.json'],
  },
}

より詳細な設定例については、Turbopack設定ドキュメントを参照してください。

パフォーマンスデバッグのためのトレースファイルの生成

パフォーマンスやメモリの問題に遭遇し、Next.jsチームの診断を支援したい場合は、開発コマンドにNEXT_TURBOPACK_TRACING=1を追加してトレースファイルを生成できます。

NEXT_TURBOPACK_TRACING=1 next dev --turbopack

これにより、.next/trace-turbopackファイルが生成されます。このファイルをNext.jsリポジトリでGitHub Issueを作成する際に含めていただくと、調査に役立ちます。

概要

Turbopackは、Rustベースのインクリメンタルバンドラーで、特に大規模なアプリケーションにおいてローカル開発とビルドを高速化するように設計されています。Next.jsに統合されており、ゼロコンフィグでCSS、React、TypeScriptをサポートします。

Turbopackの改善と本番ビルドサポートの追加を継続していますので、今後のアップデートにご期待ください。それまでの間、next dev --turbopackで試していただき、フィードバックをお聞かせください。

バージョン変更点

バージョン	変更点
`v15.3.0`	`build`の実験的サポート
`v15.0.0`	`dev`向けTurbopackが安定版に