Turbopack v produkci Next.js 16: Migrace z Webpacku a filesystémové cache

Aktualizováno: 15. července 2026

Turbopack je od Next.js 16 stabilní a výchozí bundler pro next dev i next build, který nahrazuje Webpack a přináší 2–5× rychlejší produkční buildy a 10× rychlejší HMR díky funkčně granularnímu cache v Rustu. Migrace ale není bezplatná: vlastní webpack() override v next.config.js se neaktivuje, Webpack pluginy nejsou podporovány a některé loadery (obrázky, styly) vyžadují alternativy. V tomto textu popisuji, co jsem se v naší SaaS platformě naučil při přechodu produkčních buildů na Turbopack, od turbopack.rules přes turbopackFileSystemCacheForBuild až po tichá selhání cache v CI.

• Turbopack je od Next.js 16 (říjen 2025) výchozí bundler pro dev i produkci; přepínač --turbopack už není potřeba a --webpack slouží jako dočasný únikový poklop.
• Kompletní migrace vyžaduje minimálně Node.js 20.9+, přepsání experimental.turbo na turbopack a překlad všech loaderů do klíče turbopack.rules.
• Webpack pluginy (Module Federation, MiniCssExtractPlugin) nejsou přenositelné. Turbopack má vlastní CSS a asset pipeline založenou na SWC.
• Filesystémový cache pro produkční buildy (turbopackFileSystemCacheForBuild) je od 16.3 stabilnější a v CI dokáže snížit build o 50–70 %.
• V monorepech je potřeba nastavit turbopack.root, jinak Turbopack nerozpozná linkované balíčky mimo aplikaci.
• Cache může selhat tiše: dev server odpovídá „Ready", ale worker pool je zablokovaný. V CI proto vždy validujte, že build skutečně produkuje výstup.

Co je Turbopack a proč nahradil Webpack

Turbopack je inkrementální bundler napsaný v Rustu, který Vercel vyvíjí od roku 2022 jako nástupce Webpacku. Zásadní architektonický rozdíl je v tom, že Turbopack cachuje na úrovni jednotlivých funkcí (function-level caching přes Turbo engine), zatímco Webpack rekonstruuje celý dependency graph při každé změně. V praxi to znamená, že první build je zhruba srovnatelný, ale druhý, třetí a desátý běh dramaticky zrychlují. Pro dev servery s Fast Refresh je efekt okamžitě viditelný: sub-50ms rebuildy bez ohledu na velikost projektu.

Honestly, čísla, která Next.js 16 zveřejnil pro produkci, sedí s tím, co jsem viděl na naší kódové bázi: 2× až 5× rychlejší next build, o 10× rychlejší HMR v dev módu a o 8–15 % menší client bundle díky agresivnějšímu tree-shakingu na úrovni SWC. V rámci našeho staging pipelinu klesl produkční build z 3 min 52 s na 51 s, což pro tým s ~20 deployi denně přímo přeložilo do nižších faktur za CI minuty. Když píši „Turbopack nahradil Webpack", myslím to doslova: v Next.js 16 už nejde o experimentální flag, ale o výchozí runtime. Webpack zůstává jen jako --webpack escape hatch pro migraci.

Aby to bylo úplné: Turbopack sdílí SWC jako transpiler s Next.js jádrem, spravuje kód pro klient i server jedním unifikovaným mechanismem (Webpack pro to potřeboval dva kompilátory) a integruje se s Cache Components a Partial Prerendering, což jsou dvě další velké architektonické změny, které Next.js 16 přinesl. Obě vrstvy (bundler a caching) spolu úzce spolupracují: Turbopack ví, které komponenty jsou statické a které dynamické, a podle toho generuje odděleně cachovatelné artefakty.

Turbopack vs. Webpack: srovnání pro produkci

Než přejdu k migraci, potřebuji ukázat, kde jsou skutečné rozdíly. Následující tabulka shrnuje dimenze, které staff-level engineeři obvykle porovnávají; nikoli marketingová čísla z blogpostu, ale to, co je vidět v produkci a v CI:

Dimenze	Turbopack (Next.js 16)	Webpack 5 (Next.js 15 a starší)
Jazyk implementace	Rust (Turbo engine, SWC)	JavaScript (Node.js worker pool)
Cachování	Function-level, persistentní na disk	Modulární, pouze v paměti mezi buildy
Rychlost produkčního buildu	2–5× rychlejší (typicky 19–85 % redukce)	Baseline
HMR / Fast Refresh	Sub-200 ms nezávisle na velikosti	Roste s velikostí projektu (často 3–8 s)
Podpora pluginů	Nepodporuje Webpack pluginy	Plná (Module Federation, MiniCssExtract, atd.)
Podpora loaderů	Ano, ale jen loadery vracející JS	Plná (obrázky, styly, binární assety)
Bundle size (median)	±0 až −15 % dle projektu; v Cal.com +72 % first-load JS	Predikovatelné, historicky odladěné
Konfigurace	turbopack.rules (statická data)	webpack() callback (imperativní)

Nejzajímavější řádek je bundle size. Testy na Cal.com s Next.js 15.5 ukázaly regresi first-load JS o medián +279 kB (+72 %) napříč všemi 151 App routami. Vercel na to reagoval tvrzením, že reporting velikostí z next build může být nepřesný a plánuje ho odstranit. V každém případě je to signál, že po migraci má smysl porovnat reálná čísla z produkčního CDN, ne jen build output. Pokud vaše aplikace optimalizuje na LCP a INP, nastavte si RUM baseline před migrací a měřte perceived performance, ne bundle bytes.

Kdy Turbopack jednoznačně vyhrává

Dev experience je dnes bez debat: Fast Refresh na velkých projektech (řekněme 2000+ modulů) je 10–20× rychlejší a to se přímo přenáší do rychlosti iterace. Produkční buildy vyhrávají všude, kde dominuje teplý cache (CI runnery s persistentním disk mountem nebo lokální rebuildy). Kde je efekt nejmenší, jsou green-field cold buildy v efemérních CI kontejnerech, které začínají od nuly a končí; tam se rozdíl smrsknul na 19–30 %.

Migrace na Turbopack krok za krokem

So, pojďme na věc. Migrace na Turbopack v Next.js 16 je z 80 % mechanická a z 20 % audit vaší build konfigurace. Doporučuji tuto sekvenci, kterou jsme prošli na monorepu s pěti aplikacemi:

1. Prerekvizity

• Node.js 20.9+. Next.js 16 tvrdě odmítá starší runtime; zkontrolujte Docker base images (node:20-alpine nebo novější) a všechny CI runnery.
• Čistý git working tree. Codemody fungují nejlépe bez rozpracovaných změn.
• Baseline benchmark. Před upgradem si zaznamenejte čas npm run build třikrát za sebou, ať máte s čím porovnávat.

2. Upgrade balíčků a spuštění codemodů

# Náhled změn bez zápisu
npx @next/codemod upgrade --dry-run

# Aplikace codemodů (přepíše next.config.js, imports, atd.)
npx @next/codemod upgrade

# Explicitní migrace experimental.turbo -> turbopack
npx @next/codemod@latest next-experimental-turbo-to-turbopack .

# Upgrade Reactu na 19 (vyžadováno Next.js 16)
npm install next@latest react@19 react-dom@19

# Full build s logem, kritické pro diagnostiku
npx next build 2>&1 | tee build.log

3. Přepis konfigurace v next.config.js

Předtím (Next.js 15 s experimentálním klíčem):

// next.config.js (starý formát)
module.exports = {
  experimental: {
    turbo: {
      rules: {
        '*.svg': {
          loaders: ['@svgr/webpack'],
          as: '*.js',
        },
      },
    },
  },
};

Potom (Next.js 16, stabilní klíč):

// next.config.js pro Next.js 16
/** @type {import('next').NextConfig} */
const nextConfig = {
  turbopack: {
    rules: {
      // Loader pro SVG jako React komponenty
      '*.svg': {
        loaders: ['@svgr/turbopack'],
        as: '*.js',
      },
    },
    resolveAlias: {
      '@/components': './src/components',
      '@/lib': './src/lib',
    },
    // V monorepu ukažte na kořen workspaces
    root: '../..',
  },
  experimental: {
    // Filesystémový cache pro produkci, viz sekce níže
    turbopackFileSystemCacheForBuild: true,
  },
};

module.exports = nextConfig;

4. Verifikace

Po migraci spusťte tuto trojici testů. První odhalí runtime chyby, druhý bundle regrese, třetí ekvivalenci renderingu:

# 1) Full build s Turbopackem (výchozí v Next.js 16)
npx next build

# 2) Bundle diff, porovnejte s baseline z Webpacku
npx @next/bundle-analyzer

# 3) Smoke test v produkčním módu
npx next start &
npx playwright test --project=chromium-smoke

Loadery, pluginy a co se nepřenese

Tohle je sekce, kde se většina migrací zastaví. Turbopack záměrně opustil plugin API Webpacku a vsadil na SWC plus úzký loader interface. Znamená to, že některé zavedené balíčky nefungují a vy potřebujete alternativy.

Webpack pluginy: bez podpory

Turbopack nepodporuje žádné Webpack pluginy. Pokud používáte MiniCssExtractPlugin, ForkTsCheckerWebpackPlugin, DefinePlugin, ProvidePlugin nebo Module Federation, migrace se zastaví. Většina z těchto potřeb ale má v Next.js 16 nativní ekvivalent:

• CSS extrakce: Turbopack extrahuje CSS bez konfigurace přes SWC pipeline.
• TypeScript type-checking: Next.js 16 spouští tsc --noEmit paralelně přes next dev; ForkTsCheckerWebpackPlugin odpadá.
• Environment variables: DefinePlugin replace se dělá přes next.config.js env nebo NEXT_PUBLIC_*.
• Bundle analyzer: vyměňte webpack-bundle-analyzer za @next/bundle-analyzer, který má nativní Turbopack backend.
• Module Federation: nepodporováno. Pokud na něm stavíte, zůstaňte na --webpack nebo počkejte na Q3 2026 roadmap.

Loadery: podporované, ale s omezeními

Turbopack používá knihovnu loader-runner, takže většina standardního loader API funguje. Klíčové výjimky:

• Loadery musí vracet JavaScript. Loadery, které vracejí stylesheets nebo binární obrázky (file-loader, url-loader), nefungují. Použijte nativní Next.js import pro assety.
• Options musí být plain JavaScript primitives. Není možné předat require()-ované moduly jako option value (přišel jsem o dvě hodiny na tomhle).
• Babel není podporován. Migrujte .babelrc na SWC plugin nebo na @swc/plugin-* ekvivalent.

Populární balíčky, které vyžadují náhradu

// Před: @svgr/webpack
// Po: @svgr/turbopack
npm remove @svgr/webpack
npm install @svgr/turbopack

// Před: next-compose-plugins (Webpack orientované)
// Po: nativní kompozice next.config.js přes async function
module.exports = async () => ({
  turbopack: { rules: {} },
  images: { domains: ['cdn.example.com'] },
});

Filesystémový cache pro produkční buildy

Tohle je feature, kterou v Next.js 16.3 čekáme nejvíce a která zásadně mění CI ekonomiku. Persistentní disk cache umožňuje Turbopacku načíst dříve spočítanou práci a přeskočit rekompilaci nezměněných modulů.

Jak povolit filesystémový cache

// next.config.js
module.exports = {
  experimental: {
    // Dev cache, od 16.1 default true
    turbopackFileSystemCacheForDev: true,

    // Produkční cache, od 16.3 stabilnější, stále opt-in
    turbopackFileSystemCacheForBuild: true,
  },
};

Po povolení Turbopack ukládá kompilované artefakty do .next/cache/turbopack/. Při dalším buildu (ať v dev módu nebo next build) prohledá cache před tím, než začne cokoli kompilovat. Podle Next.js 16.3 release notes to znamená 50–70 % redukci teplých buildů.

CI setup: kopírování .next/cache mezi runy

V GitHub Actions to vypadá takto:

# .github/workflows/build.yml
- uses: actions/cache@v4
  with:
    path: |
      .next/cache
      node_modules/.cache
    key: nextjs-${{ hashFiles('package-lock.json') }}-${{ hashFiles('**/*.ts', '**/*.tsx') }}
    restore-keys: |
      nextjs-${{ hashFiles('package-lock.json') }}-

- run: npm run build
  env:
    NEXT_TELEMETRY_DISABLED: 1

Cache invalidation strategie

Pro persistentní cache je invalidation klíčová. Doporučuji key strategii, která zohledňuje tři vrstvy:

const cacheKey = [
  'nextjs-turbo',
  process.env.NODE_VERSION,           // Runtime verze
  hashFiles('package-lock.json'),      // Dependency graph
  hashFiles('next.config.js'),         // Build konfigurace
  hashFiles('src/**/*.{ts,tsx,css}'),  // Source changes
].join('-');

Turbopack v monorepu a Turborepo

Monorepa jsou mou primární doménou. Spravujeme pět Next.js aplikací a asi dvanáct sdílených balíčků v pnpm workspaces. Turbopack v monorepu funguje, ale potřebuje explicitní nastavení, jinak vypadává rezoluce linkovaných balíčků.

Nastavení turbopack.root

// apps/web/next.config.js
const path = require('path');

module.exports = {
  turbopack: {
    // Absolutní cesta k workspace root
    root: path.join(__dirname, '../..'),

    // Aliasy sdílených balíčků (pokud nepoužíváte workspace protocol)
    resolveAlias: {
      '@acme/ui': path.join(__dirname, '../../packages/ui/src'),
      '@acme/design-tokens': path.join(__dirname, '../../packages/design-tokens/src'),
    },
  },
};

Bez root Turbopack skenuje pouze cestu apps/web/ a linkované balíčky v packages/* považuje za externí. To znamená, že jejich TypeScript nebude transpilován a build padá s SyntaxError. Tohle je nejčastější příčina „Turbopack nefunguje v pnpm workspace" tiketů. (Sám jsem tenhle problém zvedl asi třikrát, než jsem si to vypsal na papír a nalepil na monitor.)

Turborepo 2.0 orchestrace

Turborepo (samostatný nástroj pro monorepo orchestraci, nezaměňovat s Turbopackem) v release 2.0 přidal remote caching a přepsaný task runner. Kombinace vypadá takto:

// turbo.json
{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "!.next/cache/**"],
      "env": ["NODE_ENV", "VERCEL_ENV"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

Kritický detail: v outputs explicitně vylučte .next/cache/**. Cache Turbopacku by neměl být součástí Turborepo remote artefaktu, protože se rychle stává zastaralým a jeho velikost by nafoukla remote storage. Filesystémový cache Turbopacku a remote cache Turborepa jsou dvě různé vrstvy (první je „mezi buildy", druhá je „mezi runnery") a je nutné je držet oddělené.

PostCSS per-package

Pokud v monorepu potřebujete různé PostCSS transformace na balíček (typické u design systémů s vlastními presety), povolte experimentální flag turbopackLocalPostcssConfig. Turbopack pak řeší postcss.config.js nejblíže danému CSS souboru a padá zpět na root config.

Proč jsou moje Turbopack buildy pomalé v CI?

Tohle je otázka, se kterou přišel náš platform tým dva týdny po migraci. Turbopack v lokálu dělal 12 s buildy, v CI 4 minuty. Diagnostika ukázala tři root causes, které stojí za to sdílet:

1. Efemérní disk znamená studený cache

CI runnery typicky každý run začínají od nuly. Bez restoru .next/cache Turbopack ztrácí svoji největší výhodu (persistentní caching). Řešení: actions/cache@v4 nebo self-hosted runner s persistentním volume.

2. CPU dostupnost

Turbopack Rust engine škáluje s počtem CPU core. GitHub Actions ubuntu-latest má 4 vCPU, self-hosted large runner může mít 16+. Rozdíl mezi 4 a 16 CPU je pro Turbopack téměř lineární; v našem případě šlo o 51 s vs. 17 s.

3. Node ENV a NODE_OPTIONS

# Chybný setup, omezuje V8 heap
NODE_OPTIONS="--max-old-space-size=2048"

# Správně pro Turbopack build
NODE_OPTIONS="--max-old-space-size=8192"

Turbopack drží in-memory cache pro celý build; při 2 GB heap limitu začne GC pracovat overhours a wall-clock se ztrojnásobí. Od Next.js 16.3 sice cache umí evict do filesystému, ale peak footprint je stále signifikantní.

4. Middleware nebo proxy.ts jako bottleneck

Pokud máte rozsáhlou middleware logiku (nebo její Next.js 16 nástupce proxy.ts), zkontrolujte, že není v runtime: 'edge' zbytečně. Edge runtime má vlastní bundle pipeline, která se řetězí s hlavním buildem.

Kdy má smysl zůstat na Webpacku

Nejsem absolutista. Pro některé projekty je Turbopack v roce 2026 ještě předčasný. Zůstaňte na Webpacku, pokud platí alespoň jedno z:

• Používáte Module Federation. Roadmap Turbopacku ji plánuje na Q3 2026, ale zatím žádná implementace není.
• Máte legacy Webpack pluginy bez SWC alternativy a jejich přepis by trval déle než čekání na roadmap.
• Používáte Sass custom functions (sassOptions.functions). Turbopack Rust architektura je nepodporuje.
• Máte kritické bundle size SLA a benchmark ukázal regresi first-load JS o víc než 10 %.
• Váš tým už má odladěný custom webpack() callback s cíleným tree shakingem, který v Turbopacku ještě nedosáhnete.

V těchto případech použijte next build --webpack jako dlouhodobou strategii, ne jen jako escape hatch. Vercel v oficiální Turbopack API dokumentaci otevřeně přiznává, že Webpack cesta zůstane podporovaná, dokud nebude pokryto 100 % use casů (což dnes není). Doporučuji ale mít migrační ticket v backlogu a znovu ho auditovat každý kvartál; Turbopack se hýbe rychle a od 16.3 je feature-complete pro asi 90 % běžných produkčních setupů.

Pokud přemýšlíte i o dalších Next.js 16 změnách, mrkněte na náš průvodce Route Handlers v Next.js 16, kde rozebírám, jak Turbopack ovlivňuje kompilaci API endpointů. Bundle output je znatelně menší než u Webpacku, což se projeví na cold start latenci serverless funkcí.

Často kladené otázky

Podporuje Turbopack Webpack pluginy?

Ne. Turbopack záměrně nepodporuje Webpack plugin API. Podporuje ale většinu Webpack loaderů (těch, které vracejí JavaScript) přes konfiguraci turbopack.rules v next.config.js. Pokud potřebujete plugin funkcionalitu, hledejte SWC plugin ekvivalent nebo zůstaňte na next build --webpack.

Jak povolit filesystémový cache v Turbopacku pro produkci?

V next.config.js pod klíčem experimental nastavte turbopackFileSystemCacheForBuild: true. Feature je od Next.js 16.3 stabilní, ale stále opt-in. Cache se ukládá do .next/cache/turbopack/ a v CI má smysl ho zálohovat mezi runy přes actions/cache@v4.

Proč jsou moje Turbopack buildy pomalé v CI?

Tři nejčastější příčiny: (1) efemérní disk bez restoru .next/cache ničí persistentní cache, (2) nízký CPU count na runneru (Turbopack škáluje lineárně s core count) a (3) restrikce NODE_OPTIONS --max-old-space-size pod 4 GB. Nastavte cache restore, použijte larger runner a zvedněte heap limit na 8 GB.

Musím po migraci na Turbopack přejít i na React 19?

Ano. Next.js 16 vyžaduje React 19 jako peer dependency a Turbopack je s ním úzce integrován (podporuje React Compiler transformace). Codemod npx @next/codemod upgrade zvedne React automaticky, ale zkontrolujte breaking changes v použití ref, useFormStatus a odstranění useMemo tam, kde React Compiler dělá memoizaci sám.

Funguje Turbopack v monorepu s pnpm workspaces?

Ano, ale musíte nastavit turbopack.root v next.config.js na absolutní cestu workspace kořene. Bez toho Turbopack nerozpozná linkované balíčky mimo aplikaci a padá s SyntaxError na netranspilovaném TypeScriptu z packages/*. V kombinaci s Turborepo 2.0 vylučte .next/cache/** z outputs, aby se cache Turbopacku nemíchal s Turborepo remote artefaktem.