Turbopackの現在地 - Next.jsでの利用範囲とWebpack移行の注意点

中級 | 8分 で読める | 2026.04.24

公式ドキュメント
RustNext.js

TurbopackはRustで実装されたincremental bundlerで、Next.jsに組み込まれています。clientとserverなど複数の実行環境を1つのmodule graphで扱い、必要なmoduleだけを処理するlazy bundlingと、変更箇所に応じたincremental computationを採用しています。

現在の公開状態

記事情報: 2026年4月24日初出。Next.js公式Turbopack資料を2026年7月25日に再確認しています。

Turbopackの状態はNext.jsのversionによって変わります。

  • Next.js 15.0でnext dev向けがstable
  • Next.js 15.3でnext buildがexperimental
  • Next.js 15.5でnext buildがbeta
  • Next.js 16でdevelopmentとproduction buildの既定bundler

したがって、「Turbopackは開発専用」「production buildは未対応」という古い説明も、すべてのNext.js versionで既定という説明も正しくありません。使用中のNext.js versionに対応するdocumentを確認します。

現在のNext.jsでは通常のscriptでTurbopackを使います。

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

Webpackへ切り戻す場合は--webpackを明示します。

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

移行時に切り戻しcommandを残すと、bundler固有の問題かapplicationの問題かを比較できます。

何が違うのか

Turbopackはclient、server、edgeなどの出力を統一したgraphで扱います。計算結果を細かい単位でcacheし、変更に関係する処理だけを再計算します。developmentではrequestされたrouteに必要なcodeをlazyにbundleします。

これは設計上の特徴であり、「どのprojectでもWebpackの何百倍」という保証ではありません。初回compile、route遷移後のcompile、Fast Refresh、memory使用量はproject構成で異なります。

比較する場合は次を同じ環境で測ります。

  1. cacheがない状態のnext dev起動
  2. 最初に主要routeを開くまでの時間
  3. leaf componentと共通moduleを変更したときの反映時間
  4. production build時間とoutput
  5. peak memoryとerror・warning

広告上の最大値ではなく、自分のrepositoryで作業時間が改善するかを判断します。

Next.jsでの対応範囲

TurbopackはApp RouterとPages Routerの両方をsupportし、Next.jsのJavaScript、TypeScript、CSSなど基本機能を組み込みで扱います。Babel設定fileがある場合のsupportもNext.js 16で追加されています。

一方、TurbopackはWebpackそのものではありません。next.config.jsのwebpack() callbackは認識されず、Webpack pluginもそのまま利用できません。

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  turbopack: {
    resolveAlias: {
      underscore: "lodash",
    },
    resolveExtensions: [
      ".mdx",
      ".tsx",
      ".ts",
      ".jsx",
      ".js",
      ".json",
    ],
  },
};

export default nextConfig;

以前のexperimental.turboはturboを経て、現在はturboではなくturbopack keyです。古い設定は公式codemodで変換できます。

npx @next/codemod@latest next-experimental-turbo-to-turbopack .

codemod後は設定が同じ意味になっているか差分をreviewします。

Webpack loaderとpluginの違い

Turbopackのrulesでは、一部のWebpack loaderをfile変換に利用できます。公式資料には@svgr/webpack、yaml-loader、string-replace-loaderなど動作確認済みの例があります。

const nextConfig: NextConfig = {
  turbopack: {
    rules: {
      "*.svg": {
        loaders: ["@svgr/webpack"],
        as: "*.js",
      },
    },
  },
};

ただしloader APIのsupportはsubsetです。loaderがJavaScript objectを返さず、最終的にJavaScript codeを返せる必要があるなど制約があります。

Webpack pluginはcompiler lifecycleへ深く接続するため、そのまま移植できません。現在のwebpack()設定を次の分類に分けます。

  • aliasやextension変更 → turbopack.resolveAliasなどへ移行
  • file transform → turbopack.rulesでloaderを検証
  • Next.js組み込み機能で代替可能 → custom設定を削除
  • Webpack plugin固有 → Webpack継続または別の仕組みを検討

設定量が多いほど、まず一覧を作って1項目ずつ対応状況を確認します。

既知のgap

Next.js公式資料にはWebpackとのgapが明記されています。代表例は次のとおりです。

  • webpack() configurationとWebpack plugin
  • Yarn Plug’n’Play
  • experimental.urlImports
  • experimental.esmExternals
  • JavaScript functionを渡すcustom Sass function
  • 一部のNext.js experimental flag

CSS Modulesのclass順序も、WebpackとTurbopackで差が表面化する場合があります。CSS Modulesの順序はimport順に従うため、global scopeで競合するselectorをcomponent間に分散させず、同じ順序でimportします。

非対応機能があるからTurbopack全体を避ける必要はありませんが、使っている機能がgapに該当するならWebpackを残すのが安全です。

Monorepoとfilesystem root

Turbopackはproject rootを検出し、その外側のfileをresolveしません。lockfileから推測されたrootがmonorepo構成と合わない場合はturbopack.rootを絶対pathで設定します。

import path from "node:path";

const nextConfig: NextConfig = {
  turbopack: {
    root: path.join(__dirname, "../.."),
  },
};

rootを広げすぎると、本来対象外のfileがgraphへ入る可能性があります。workspace rootとpackage境界を確認し、必要な範囲へ限定してください。

Cacheと調査

Next.jsのversionによってfilesystem cacheの状態やoptionは変わります。cacheを削除すればすべて解決すると考えず、まず再現手順とversionを記録します。

性能・memory問題をNext.js側へ報告するときは、公式資料のtracingを利用できます。

NEXT_TURBOPACK_TRACING=1 next dev

生成されるtraceにはproject情報が含まれる可能性があります。外部へ共有する前に内容と組織のpolicyを確認してください。

移行手順

  1. Next.jsとNode.jsのversionを固定する
  2. webpack()設定、plugin、loaderを一覧化する
  3. testとproduction buildの基準点を作る
  4. Turbopackでdevelopmentの主要routeを確認する
  5. Fast Refresh、CSS、source map、error表示を確認する
  6. Turbopackでproduction buildとE2E testを実行する
  7. platform側のdeploy outputを確認する
  8. 問題があれば--webpackで比較し、最小再現を作る

Next.jsをmajor updateしながらbundlerも変更すると、原因の切り分けが難しくなります。可能ならNext.js更新、deprecated設定の解消、bundler比較を小さな差分に分けます。

選定判断

新しいNext.jsではTurbopackが既定なので、まずTurbopackで動かし、非対応機能がある場合にWebpackへ切り戻す流れが自然です。ただし既存のWebpack pluginやcustom Sass functionが重要なら、無理に移行する必要はありません。

Turbopackは現時点でNext.jsに組み込まれたbundlerとして評価します。旧記事にあるstandalone Turbopackの導入例や、Vite向けSPAを直接置き換える説明は、現在の公式Next.js利用方法と混同しないでください。

参考リソース

おすすめ記事

← 一覧に戻る
PR
PR
PR
PR