Turbopack

Turbopackは、Rustで書かれた、JavaScriptとTypeScriptに最適化されたインクリメンタルバンダーであり、Next.jsに組み込まれています。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で推論される順序を無視する場合があります。

これは、アプリケーションが恣意的な順序に依存するようになった場合に、微妙なレンダリング変更につながる可能性があります。一般的に、解決策は簡単です。例えば、順序を強制するために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を削除できるため、依存関係もドロップできます。

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

ビルドキャッシュ

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

• experimental.turbopackFileSystemCacheForDev
• experimental.turbopackFileSystemCacheForBuild

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

Webpackプラグイン

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

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

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

• レガシーCSS Modules機能
  • スタンドアロンの:localおよび:global擬似クラス（関数形式の:global(...)のみサポート）。
  • @valueルール（CSS変数に置き換えられました）。
  • :importおよび:export ICSSルール。
  • .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ベースのアーキテクチャは、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は、turbopackキーの下でnext.config.js（またはnext.config.ts）を介して設定できます。設定オプションには以下が含まれます。

• 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のゼロコンフィグサポートを提供します。

バージョン変更履歴