Turbopack

Turbopackは、JavaScriptとTypeScriptに最適化されたインクリメンタルバンドラーで、Rustで書かれ、Next.jsに組み込まれています。ページルーターとアプリルーターの両方でTurbopackを使用でき、はるかに高速なローカル開発体験が得られます。

Turbopackを選ぶ理由

Turbopackは、以下を含むNext.jsのパフォーマンスを向上させるために構築されました。

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

はじめる

Turbopackはいまや、Next.jsのデフォルトバンドラーです。Turbopackを使用するために設定は必要ありません。

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

代わりにWebpackを使用する

Turbopackの代わりにWebpackを使用する必要がある場合は、--webpackフラグでオプトインできます。

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

サポートされている機能

Next.jsのTurbopackは一般的なユースケースに対してゼロコンフィギュレーションです。以下は、標準でサポートされている機能の概要と、必要に応じてTurbopackをさらに設定する方法へのリファレンスです。

言語機能

フレームワークとReact機能

CSSとスタイリング

アセット

モジュール解決

パフォーマンスとFast Refresh

webpackとの既知のギャップ

webpackとTurbopackの間には、アプリケーションを移行する際に認識すべき多くの重要な動作の違いがあります。一般的に、これらは新しいアプリケーションではあまり懸念事項ではありません。

CSSモジュールの順序付け

Turbopackは、JS インポート順序に従ってCSSモジュールを順序付けします。これらは明示的に順序付けされていません。例えば、

import utilStyles from './utils.module.css'
import buttonStyles from './button.module.css'
export default function BlogPost() {
  return (
    <div className={utilStyles.container}>
      <button className={buttonStyles.primary}>クリック</button>
    </div>
  )
}

この例では、Turbopackは、生成されたCSSチャンク内でutils.module.cssがbutton.module.cssの前に表示されることを保証します。これはインポート順序に従っています。

Webpackも一般的にこれを行いますが、JS ファイルが副作用なしと推測される場合など、JS 推定順序を無視する場合があります。

Turbopackを採用する際に、アプリケーションが任意の順序に依存するようになっている場合、微妙なレンダリング変更が発生する可能性があります。一般的に、解決策は簡単です。例えば、button.module.cssで@import utils.module.cssを使用して順序を強制したり、競合するルールを特定して同じプロパティをターゲットにしないように変更したりします。

Sassのnode_modulesインポート

Turbopackは、node_modulesのSassファイルのインポートを標準でサポートしています。Webpackはこのためのレガシータイルダー~構文をサポートしていますが、Turbopackではサポートされていません。

変更前：

@import '~bootstrap/dist/css/bootstrap.min.css';

変更後：

@import 'bootstrap/dist/css/bootstrap.min.css';

インポートを更新できない場合は、turbopack.resolveAlias設定を追加して、~構文を実際のパスにマップできます。

module.exports = {
  turbopack: {
    resolveAlias: {
      '~*': '*',
    },
  },
}

バンドルサイズ

本番アプリケーションでのテストから、Turbopackは一般的にWebpackと同様のサイズのバンドルを生成することが観察されました。ただし、turbopackはより少ないがより大きなチャンクを生成する傾向があるため、比較は困難です。より高いレベルのメトリクス（Core Web Vitalsなど）またはバンドラー間のパフォーマンスを比較するための独自のアプリケーションレベルのメトリクスに焦点を当てることをお勧めします。ただし、大きな回帰を時々引き起こす可能性のある1つのギャップに気付いています。

Turbopackにはまだ、webpackのデフォルトで有効になっているInner Graph Optimizationに相当するものがありません。この最適化は大規模なモジュールをツリーシェイクするのに便利です。例えば、

import heavy from 'some-heavy-dependency.js'
 
export function usesHeavy() {
  return heavy.run()
}
 
export const CONSTANT_VALUE = 3

アプリケーションがCONSTANT_VALUEのみを使用する場合、Turbopackはこれを検出し、usesHeavyエクスポートを削除しますが、対応するimportは削除しません。ただし、Inner Graph Optimization を使用する場合、webpack はimportも削除でき、依存関係も削除できます。

Turbopackで Inner Graph Optimization に相当するものを提供することを計画していますが、まだ開発中です。このギャップの影響を受ける場合は、モジュールの手動分割を検討してください。

ビルドキャッシング

Webpackはディスクビルドキャッシングをサポートして、ビルドパフォーマンスを向上させます。Turbopackは、現在ベータ版の同様なオプトイン機能を提供しています。Next 16以降では、以下の実験的フラグを設定することでTurbopackのファイルシステムキャッシュを有効にできます。

• experimental.turbopackFileSystemCacheForDev
• experimental.turbopackFileSystemCacheForBuild

補足： このため、webpackとTurbopackのパフォーマンスを比較する際は、公正な比較を確認するために、ビルド間で.nextフォルダーを削除するか、turbopackファイルシステムキャッシュ機能を有効にしてください。

Webpackプラグイン

Turbopackはwebpackプラグインをサポートしていません。これは統合のためにwebpackのプラグインシステムに依存するサードパーティーツールに影響します。webpackローダーはサポートしています。webpackプラグインに依存している場合は、Turbopack互換の代替案を見つけるか、同等の機能が利用可能になるまでwebpackを使用し続ける必要があります。

サポートされていない、計画されていない機能

いくつかの機能はまだ実装されていないか、計画されていません。

• レガシーCSSモジュール機能
  • スタンドアロンの:localと:global疑似クラス（関数バリアント:global(...)のみサポートされています）。
  • @valueルール（CSS変数に置き換わった）。
  • :importと:exportICSルール。
  • .module.cssにおけるcomposesで.cssファイルを構成する。webpackではこれは.cssファイルをCSSモジュールとして扱いますが、Turbopackでは.cssファイルは常にグローバルになります。つまり、CSSモジュールでcomposesを使用する場合は、.cssファイルを.module.cssファイルに変更する必要があります。
  • CSSモジュール内の@importで.cssをCSSモジュールとしてインポートする。webpackではこれは.cssファイルをCSSモジュールとして扱いますが、Turbopackでは.cssファイルは常にグローバルになります。つまり、CSSモジュールで@importを使用する場合は、.cssファイルを.module.cssファイルに変更する必要があります。
• sassOptions.functions sassOptions.functionsで定義されたカスタムSass関数はサポートされていません。この機能により、Sassコードのコンパイル中に呼び出すことができるJavaScript関数を定義できます。TurbopackのRustベースのアーキテクチャでは、webpack のNode.jsベースのsass-loaderのようにJavaScript経由で完全に実行されるsassOptions.functionsを通じて渡されるJavaScript関数を直接実行できません。カスタムSass関数を使用している場合は、Turbopackの代わりにwebpackを使用する必要があります。
• next.config.js内のwebpack()設定 Turbopackはwebpackに置き換わるため、webpack()設定は認識されません。代わりにturbopack設定を使用してください。
• Yarn PnP Next.jsではTurbopackサポートに計画されていません。
• experimental.urlImports Turbopackには計画されていません。
• experimental.esmExternals 計画されていません。TurbopackはNext.jsのレガシーesmExternals設定をサポートしていません。
• いくつかのNext.js実験的フラグ
  • experimental.nextScriptWorkers
  • experimental.sri.algorithm
  • experimental.fallbackNodePolyfills これらは将来実装することを計画しています。

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

設定

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

• rules ファイル変換用に追加のwebpackローダーを定義します。
• resolveAlias 手動エイリアスを作成します（webpackのresolve.aliasのような）。
• resolveExtensions モジュール解決のためにファイル拡張子を変更または拡張します。

module.exports = {
  turbopack: {
    // 例：エイリアスとカスタムファイル拡張子を追加する
    resolveAlias: {
      underscore: 'lodash',
    },
    resolveExtensions: ['.mdx', '.tsx', '.ts', '.jsx', '.js', '.json'],
  },
}

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

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

パフォーマンスまたはメモリの問題が発生した場合、Next.jsチームが診断するのに役立つようにトレースファイルを生成するには、NEXT_TURBOPACK_TRACING=1をdevコマンドに追加します。

NEXT_TURBOPACK_TRACING=1 next dev

これにより、.next/dev/trace-turbopackファイルが生成されます。Next.jsリポジトリでGitHub問題を作成する際にそのファイルを含め、診断を支援してください。

デフォルトでは、開発サーバーは.next/devに出力します。isolatedDevBuildの詳細を読んでください。

概要

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

バージョン変更