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は開発サーバーによって実際に要求されたもののみをバンドルします。この遅延アプローチは、初期コンパイル時間とメモリ使用量を削減できます。

はじめに

Turbopackは現在Next.jsのデフォルトバンダーです。Turbopackを使用するために設定は不要です。

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

Webpackの使用

WebpackをTurbopackの代わりに使用する必要がある場合は、--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}>Click me</button>
    </div>
  )
}

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

Webpackも一般的にこれを行いますが、JSによる推論された順序を無視する場合があります。たとえば、JSファイルが副作用フリーであると推論した場合などです。

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

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を削除できるため、依存関係もドロップできます。

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

ビルドキャッシュ

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

• experimental.turbopackFileSystemCacheForDev
• experimental.turbopackFileSystemCacheForBuild

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

Webpackプラグイン

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

未サポートおよび計画外の機能

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

• レガシーCSS Modules機能
  • スタンドアロンの:localおよび:global擬似クラス（関数形式の:global(...)のみサポート）。
  • @valueルール（CSS変数で置き換えられました）。
  • :importおよび:export ICSSルール。
  • CSS Modulesでのcomposesが.cssファイルをコンポーズする。Webpackでは.cssファイルはCSSモジュールとして扱われますが、Turbopackでは.cssファイルは常にグローバルになります。これは、CSSモジュールでcomposesを使用したい場合、.cssファイルを.module.cssファイルに変更する必要があることを意味します。
  • CSS Modulesでの@importが.cssをCSSモジュールとしてインポートする。Webpackでは.cssファイルはCSSモジュールとして扱われますが、Turbopackでは.cssファイルは常にグローバルになります。これは、CSSモジュールで@importを使用したい場合、.cssファイルを.module.cssファイルに変更する必要があることを意味します。
• sassOptions.functions sassOptions.functionsで定義されたカスタムSass関数はサポートされていません。この機能は、コンパイル中にSassコードから呼び出すことができるJavaScript関数を定義できるようにします。TurbopackのRustベースのアーキテクチャは、JavaScriptで完全に実行されるWebpackのNode.jsベースのsass-loaderとは異なり、sassOptions.functionsを介して渡されたJavaScript関数を直接実行できません。カスタムSass関数を使用している場合は、Turbopackの代わりにWebpackを使用する必要があります。
• webpack()設定 next.config.js 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: {
    // 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

これにより、.next/dev/trace-turbopackファイルが生成されます。これをGitHubのNext.jsリポジトリに問題報告として含めて、調査にご協力ください。

デフォルトでは、開発サーバーは.next/devに出力します。isolatedDevBuildについて詳しく読む。

まとめ

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

バージョン変更履歴