Next.js 16 Turbopack in der Produktion: Migration, Fehlerbehebung und Webpack-Opt-out

Aktualisiert: 27. Mai 2026

Mit Next.js 16 wird Turbopack der Standard-Bundler für next dev und next build, und genau dieser zweite Teil hat in den letzten Monaten die meisten Production-Probleme verursacht. Wer eine eigene webpack()-Konfiguration, ein Plugin wie withPayload oder Loader für SVG, MDX oder Sass im Projekt hat, sieht nach dem Upgrade entweder einen abgebrochenen Build oder, schlimmer, einen erfolgreich kompilierten Build, der zur Laufzeit 500er liefert. Dieser Leitfaden zeigt, wie du auf Turbopack migrierst, wann du gezielt mit NEXT_DISABLE_TURBOPACK=1 oder dem --webpack-Flag aussteigst, und welche Konfigurations-Stolperfallen 16.2.6 mitbringt.

• Turbopack ist seit Next.js 16 (Oktober 2025) der stabile Default für next dev und next build. Die Mindestversion ist Node.js 20.9.
• Eigene webpack()-Konfigurationen werden im Production-Build von Turbopack ignoriert; der Build bricht ab, sobald Next.js diese Diskrepanz erkennt.
• Du steigst pro Build mit next build --webpack oder pro Umgebung mit NEXT_DISABLE_TURBOPACK=1 aus. Auf Vercel die Environment Variable nur in Production scopen.
• Turbopack unterstützt Webpack-Loader, aber keine Webpack-Plugins. Drittanbieter wie @payloadcms/next verursachen genau deshalb häufig Build-Fehler.
• Die experimental.turbo-Option ist entfernt; die Config liegt jetzt auf Top-Level als turbopack. Migration via npx @next/codemod@latest next-experimental-turbo-to-turbopack .
• 16.2.6 (7. Mai 2026) bündelt 13 Security-Advisories. Wer auf 16.x < 16.2.6 ist, sollte sofort upgraden.

Was sich mit Turbopack als Default ändert

Turbopack ist der Rust-basierte Nachfolger von Webpack, der seit Next.js 13 in Entwicklung war. Ich habe ihn ehrlich gesagt jahrelang ignoriert: solange er nur next dev beschleunigte, war mir der Migrationsaufwand zu hoch. Mit Next.js 16 hat sich das geändert. Vercel berichtet von 2× bis 5× schnelleren Production-Builds (in einem Makerkit-Benchmark: 5,7 s mit Turbopack gegen 24,5 s mit Webpack) und 10× schnellerem Fast Refresh. Über 20 % der 15.3+-Production-Builds liefen bereits vor dem Stable-Release auf Turbopack.

Konkret heißt das: next build startet jetzt automatisch Turbopack, sofern du nichts anderes angibst. next start bleibt unverändert, da es nur die Build-Artefakte serviert. Die experimental.turbopack-Konfiguration ist aus dem experimental-Block herausgewandert und liegt jetzt direkt unter turbopack im next.config.ts. Die alte Schreibweise experimental.turbo ist komplett entfernt; Projekte, die noch auf Next.js 13 bis 15 hängen und diese Option setzen, müssen erst migrieren, bevor sie überhaupt auf 16 upgraden können.

Wichtig für Plattform-Teams: Next.js 16 hebt die minimale Node.js-Version auf 20.9+ an. Wer noch CI-Images auf Node 18 fährt (Lambda-Defaults, alte Docker-Layer), sieht den Build erst gar nicht starten. Honestly, behandle das Upgrade wie ein kleines Plattform-Projekt: Node-Bump, Webpack-Audit, CI-Cache-Validation. Nicht wie ein npm install next@latest.

Wie deaktiviere ich Turbopack in Next.js 16?

Es gibt drei offizielle Wege, Turbopack pro Build, pro Umgebung oder projektweit auszuschalten, und jeder hat einen anderen Anwendungsfall. Mein Standard-Ansatz: Dev und Preview auf Turbopack, Production temporär auf Webpack, bis der Loader-Stack nachgezogen hat. So bekommt das Team die Iterationsgeschwindigkeit, ohne dass die Produktiv-Pipeline an einem inkompatiblen Plugin scheitert.

Variante 1, CLI-Flag pro Build (empfohlen für CI):

# package.json
{
  "scripts": {
    "dev": "next dev",
    "build": "next build --webpack",
    "build:turbo": "next build --turbopack",
    "start": "next start"
  }
}

Das --webpack-Flag erzwingt den Webpack-Pfad nur für diesen einen Build. Es ist in CI-Logs sofort sichtbar (anders als eine versteckte Env-Variable) und lässt sich später durch einen einzeiligen Patch wieder entfernen.

Variante 2, Environment Variable pro Umgebung:

# .env.production (oder Vercel Project Settings)
NEXT_DISABLE_TURBOPACK=1

Diese Variante eignet sich für Plattformen wie Vercel, Netlify oder Railway, wo du pro Environment unterschiedliche Variablen setzen kannst. Production zieht den Webpack-Pfad, Preview und Dev behalten Turbopack-Geschwindigkeit. Wichtig: Die Variable beeinflusst nur den Build-Schritt, nicht Runtime.

Variante 3, projektweit über die Config:

// next.config.ts, nicht empfohlen
import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  experimental: { turbo: false },
};

export default nextConfig;

Diese Variante zieht Turbopack auch in next dev ab, du verlierst also den 10× schnelleren Fast Refresh. Nutze sie nur, wenn dein Team wirklich keinen Turbopack-Pfad fahren kann, z. B. weil ein Hauptloader völlig inkompatibel ist.

Warum schlägt mein Next.js 16 Production-Build fehl?

Die häufigste Fehlermeldung beim Upgrade lautet: This build is using Turbopack, with a webpack config and no turbopack config. This may be a mistake. Next.js wirft diesen Fehler bewusst, sobald es eine webpack()-Funktion in deiner Konfiguration findet, aber kein turbopack-Pendant. Der Grund: Turbopack würde deine Webpack-Anweisungen stillschweigend ignorieren, und Build und Runtime würden auseinanderdriften.

Die zweite häufige Fehlerquelle sind Drittanbieter-Plugins, die unbedingt eine webpack()-Funktion injizieren, auch wenn dein Projekt selbst keine definiert. Ein bekanntes Beispiel ist @payloadcms/next: Der withPayload-Wrapper hängt seinen Webpack-Hook in jede Config, was unter Turbopack zum oben genannten Fehler führt (siehe Payload CMS Issue #14354). Lösung: entweder auf einen Patch warten oder per --webpack aussteigen.

Der heimtückischste Fall ist allerdings ein Build, der durchläuft, aber zur Laufzeit kaputt geht. Ich bin bei einem Kundenprojekt genau in diese Falle gelaufen, und so sah's aus:

• SVG-Imports geben undefined zurück. Wer SVGR per Webpack-Loader eingebunden hatte, sieht plötzlich leere React-Komponenten. Turbopack hat zwar einen SVGR-Pfad, aber er muss explizit konfiguriert werden.
• MODULE_NOT_FOUND oder ENOENT auf der ersten Request. Tritt auf, wenn Edge-Runtime-Tweaks oder serverExternalPackages-Listen nicht migriert wurden.
• Hydration-Fehler in Client-Komponenten. Turbopack ist strenger bei NEXT_PUBLIC_-Prefixes: Variablen, die du im Client liest, werfen jetzt, wenn das Präfix fehlt.

Bei kryptischen Turbopack-Fehlern wie expected chunkable module for async reference hilft fast immer ein vollständiges Clean: rm -rf .next node_modules .turbo package-lock.json und neu installieren. Klingt nach Kanonen auf Spatzen, ist aber bei Bundler-Wechseln Standardprotokoll.

Konfiguration von experimental.turbo zu turbopack migrieren

Die Config-Migration ist in den meisten Projekten zum Glück mechanisch. Vor Next.js 16 lag die Turbopack-Konfiguration unter experimental.turbo; jetzt liegt sie auf Top-Level als turbopack. Es gibt einen offiziellen Codemod:

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

Das Skript verschiebt nicht nur den Key, sondern aktualisiert auch verschachtelte Optionen wie rules oder resolveAlias. Vorher-Nachher-Beispiel:

// next.config.ts, Next.js 15 (alt)
const nextConfig = {
  experimental: {
    turbo: {
      rules: {
        '*.svg': {
          loaders: ['@svgr/webpack'],
          as: '*.js',
        },
      },
    },
  },
};

// next.config.ts, Next.js 16 (neu)
import type { NextConfig } from 'next';

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

export default nextConfig;

Wer Cache Components nutzt (die das alte experimental.ppr-Flag ersetzen), sollte diese Migration zusammen mit dem Turbopack-Upgrade machen. Wie das im Detail aussieht, habe ich in meinem Deep Dive zu Cache Components und der use cache-Direktive beschrieben. Praktischer Hinweis: Die cacheComponents: true-Option ist seit 16 stabil und hat experimental.ppr komplett abgelöst.

Loader, Aliase und Sass-Imports anpassen

Turbopack unterstützt Webpack-Loader, aber keine Webpack-Plugins. Das ist die wichtigste mentale Unterscheidung. Ein Loader transformiert eine Datei (z. B. SVG zu React-Komponente, MDX zu JSX); ein Plugin hängt sich in den Build-Lifecycle ein (z. B. BundleAnalyzerPlugin, DefinePlugin). Loader migrierst du; Plugins brauchen einen Turbopack-nativen Ersatz oder einen Workaround.

SVGs mit SVGR

// next.config.ts
import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  turbopack: {
    rules: {
      '*.svg': {
        loaders: [
          {
            loader: '@svgr/webpack',
            options: { icon: true },
          },
        ],
        as: '*.js',
      },
    },
  },
};

export default nextConfig;

Node-Module im Browser-Bundle (z. B. fs)

Webpack erlaubte resolve.fallback: { fs: false }. Turbopack hat ein Pendant: turbopack.resolveAlias in Kombination mit einem leeren Modul.

// next.config.ts
const nextConfig: NextConfig = {
  turbopack: {
    resolveAlias: {
      fs: { browser: './empty-module.js' },
    },
  },
};

Path-Aliase

Verzichte auf webpack.resolve.alias und nutze stattdessen tsconfig.json-Paths. Turbopack liest sie nativ:

// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"],
      "@components/*": ["./src/components/*"]
    }
  }
}

Sass-Imports

Turbopack unterstützt Sass-Imports aus node_modules, aber nicht die alte Tilde-Syntax @import "~bootstrap/...";. Ersetze sie durch Standard-Imports ohne ~: @import "bootstrap/scss/bootstrap";.

Vercel-Rollout: Production opt-out, Preview behalten

Auf Vercel ist der saubere Rollout-Pfad eine pro Umgebung gescopte Variable. So sieht das in der Praxis aus:

1. Projekt öffnen, dann Settings, dann Environment Variables
2. Neue Variable: NEXT_DISABLE_TURBOPACK = 1
3. Scope: Production aktivieren, Preview und Development deaktiviert lassen
4. Speichern, dann den nächsten Production-Deploy triggern (Settings-Änderungen wirken erst beim nächsten Build)

Das Ergebnis: Preview-Deployments laufen mit Turbopack, du siehst die schnelleren Build-Zeiten und kannst Edge-Cases identifizieren, Production bleibt auf dem bewährten Webpack-Pfad. Sobald ein Production-Preview-Build zwei Wochen sauber durchläuft, kannst du die Variable in Production entfernen.

Für Server Actions und mutationsschwere Routen empfehle ich, vor dem Production-Switch eine Lasttest-Pipeline laufen zu lassen. Wer das noch nie gemacht hat, in meiner Anleitung zu Next.js Server Actions, Formularen und Sicherheit findest du das Setup für eine reproduzierbare Last.

Filesystem-Caching und CI-Builds

Eine der größten Neuerungen in 16.1 (Dezember 2025) ist das Turbopack Filesystem Cache. Statt nach jedem Build neu zu kompilieren, persistiert Turbopack die Compiler-Artefakte auf der Platte und lädt sie beim nächsten Lauf nach. In großen Monorepos sind die Effekte dramatisch. Bei einem Kundenprojekt sank der CI-Build von 7 min auf 90 s, sobald der Cache warm war.

// next.config.ts
const nextConfig: NextConfig = {
  experimental: {
    turbopackFileSystemCacheForBuild: true, // opt-in für Production-Builds
    // turbopackFileSystemCacheForDev: true,  // bereits Default seit 16.1
  },
};

In CI gehört das .turbo-Verzeichnis in den Cache-Block der Pipeline. Beispiel für GitHub Actions:

# .github/workflows/build.yml
- name: Restore Turbopack cache
  uses: actions/cache@v4
  with:
    path: |
      .next/cache
      .turbo
    key: turbopack-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}-${{ hashFiles('**/*.ts', '**/*.tsx') }}
    restore-keys: |
      turbopack-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}-

Auf Vercel ist der Cache bereits Teil des Build-Pfads und muss nicht separat konfiguriert werden. Achte aber darauf, dass ein Cache-Bust (z. B. nach einem Major-Upgrade) bewusst durchgeführt wird. Sonst können stale Artefakte das schwer zu debuggende „build OK, Runtime 500" Verhalten triggern.

Turbopack vs. Webpack im Vergleich

Wann lohnt sich der Wechsel sofort, wann lieber warten? Die folgende Übersicht fasst zusammen, was nach meiner Erfahrung in 16.2.6 stabil ist und wo Webpack noch die einfachere Wahl ist.

Kriterium	Turbopack (16.2.6)	Webpack (via --webpack)
Dev-Startup	~600 ms (Cold), <100 ms (Warm)	2 bis 8 s, abhängig von Plugins
Production-Build	2 bis 5× schneller (5,7 s vs. 24,5 s in Benchmarks)	Stabil, gut verstanden
Fast Refresh	~10× schneller	Baseline
Webpack-Loader	Unterstützt	Voll unterstützt
Webpack-Plugins	Nicht unterstützt	Voll unterstützt
Filesystem-Cache	Stabil seit 16.1 (Dev), opt-in (Build)	Vorhanden, gut getestet
Drittanbieter-Integrationen	Lücken bei MDX-Plugin-Chains, Payload, manchen CSP-Tools	Voll kompatibel
Empfehlung Dev	Ja, einschalten	Nur wenn Loader-Chain blockiert
Empfehlung Production	Ja, sofern keine kritischen Plugins	Sicherer Default für Legacy-Stacks

Mein konservativer Migrationspfad: Eine Woche nur in Dev fahren, dann zwei Wochen Preview-Deploys auf Vercel mit Turbopack, dann Production. Wer eilig ist, kann den Schritt überspringen. Die meisten Apps ohne exotische Plugins laufen problemlos. Details und alle --turbopack-Flags findest du in der offiziellen Turbopack-API-Referenz und im Next.js 16 Release-Post.

Häufig gestellte Fragen

Ist Turbopack jetzt wirklich stabil für Production?

Ja. Seit Next.js 16 (Oktober 2025) ist Turbopack offiziell stabil und Default für next build. Bekannte Lücken betreffen Webpack-Plugin-Kompatibilität und einige Drittanbieter wie Payload CMS. Für Standard-App-Router-Projekte ohne exotische Plugins ist es Production-ready; bei stark angepassten Pipelines lohnt sich ein --webpack-Fallback während des Rollouts.

Was ist der Unterschied zwischen NEXT_DISABLE_TURBOPACK=1 und next build --webpack?

Funktional identisch, beide erzwingen den Webpack-Pfad. Die Environment Variable ist besser, wenn du pro Umgebung (z. B. nur Production) opt-outen willst; das CLI-Flag ist besser für CI-Skripte, weil es in den Logs sofort sichtbar ist und keine Plattform-Settings braucht.

Warum bricht mein Build mit „webpack config and no turbopack config" ab?

Next.js 16 wirft diesen Fehler, wenn es eine webpack()-Funktion in deiner Config findet, aber keine turbopack-Konfiguration. Häufige Ursache: ein Drittanbieter-Plugin wie withPayload injiziert die Webpack-Funktion. Lösung: entweder eine äquivalente turbopack-Konfiguration ergänzen oder mit --webpack aussteigen.

Brauche ich für Next.js 16 wirklich Node.js 20.9?

Ja, das ist die offizielle Mindestversion. Ältere Node-Versionen lehnen Turbopack-Binaries ab und der Build startet nicht. Prüfe vor dem Upgrade deine CI-Images, Lambda-Runtimes und lokalen nvmrc-Dateien.

Lohnt sich der Wechsel von Webpack auf Turbopack jetzt?

Für die Developer Experience definitiv. Der 10× schnellere Fast Refresh allein rechtfertigt das Upgrade. Für Production hängt es vom Plugin-Stack ab: Standard-Setups profitieren von 2 bis 5× kürzeren Build-Zeiten; komplexe Webpack-Pipelines sollten Turbopack erst in Preview-Deployments validieren, bevor Production wechselt.