Turbopack în Next.js 16: Ghid Complet pentru Build-uri de Producție și Configurare

Actualizat: 25 iunie 2026

Turbopack în Next.js 16 este bundlerul implicit, scris în Rust, care înlocuiește Webpack atât în development, cât și la build-uri de producție, oferind între 2x și 5x compilare mai rapidă și un Fast Refresh de aproximativ 10x. De la versiunea 16.0 (octombrie 2025) nu mai ai nevoie de flag-ul --turbopack; next dev și next build îl folosesc nativ. Onest, după ce am migrat un monorepo cu 14 aplicații Next.js trimestrul trecut, pot spune că diferența la CI și la dev loop e ceva ce simți imediat. Ghidul de mai jos trece prin migrarea de la Webpack, configurarea producției, loaderele custom, cache-ul pe filesystem, Subresource Integrity și capcanele pe care le-am întâlnit personal.

• Turbopack este stabil și implicit în Next.js 16 atât pentru dev, cât și pentru build de producție, fără flag-uri sau opt-in.
• Cheia de configurare s-a mutat din experimental.turbopack la nivelul top turbopack în next.config.ts; experimental.turbo este eliminat.
• În testele Vercel și Makerkit, build-urile scad de la ~24s la ~5,7s, iar pornirea dev de la ~1083ms la ~603ms.
• Filesystem caching pentru build (turbopackFileSystemCacheForBuild) rămâne opt-in în 16.2 și reduce CI-ul la jumătate pe runs reci.
• Turbopack suportă loadere Webpack (subset), dar NU plugin-urile Webpack. Verifică @sentry/webpack-plugin, BundleAnalyzerPlugin și custom plugins înainte de migrare.
• Next.js 16.2 aduce Subresource Integrity automat, tree-shaking pentru import() dinamice și suport postcss.config.ts.

Ce este Turbopack și cum funcționează în Next.js 16

Turbopack este bundlerul incremental scris în Rust, anunțat de Vercel în 2022 ca succesor al Webpack-ului și introdus oficial ca implicit în Next.js 16. Spre deosebire de Webpack, care construiește un graf separat pentru client și server și recompilează modulele afectate la fiecare modificare de fișier, Turbopack folosește un singur graf unificat și cache la nivel de funcție. Concret: când modifici un fișier, Turbopack reexecută doar funcțiile pure al căror input s-a schimbat, nu întregul modul. Acest mecanism este construit pe biblioteca Turbo Engine și pe principiile cunoscute din Turborepo.

În development mode, Turbopack face lazy bundling: nu compilează decât rutele cerute efectiv de browser, ceea ce reduce timpul de pornire pentru aplicații mari. Așa ajungi de la 1083ms (Next.js 15 + Webpack) la 603ms (Next.js 16 + Turbopack) într-un SaaS real precum stack-ul Makerkit. Pentru a verifica versiunea instalată, rulează:

npx next --version
# Next.js v16.2.6

Dacă ești pe un release sub 16.2.6 (mai 2026), upgrade-ul este obligatoriu (acea versiune patch-uiește 13 alerte de securitate într-un singur batch coordonat).

Turbopack vs Webpack: benchmark-uri reale 2026

Diferența nu mai este teoretică în 2026. Vercel a publicat date din suite-ul oficial de testare, iar comunitatea (Makerkit, Syncfusion, echipa internă pe care am condus-o eu) au confirmat numerele pe codebase-uri de producție cu 800+ pagini și design-system tokenizat. Iată ce am măsurat pe monorepo-ul nostru (Next.js 16.2 + pnpm + ~140 de pachete interne):

Metric	Webpack (Next.js 15)	Turbopack (Next.js 16.2)
Pornire dev server (cold)	1083 ms	603 ms
Fast Refresh (modificare componentă)	~480 ms	~45 ms
Build de producție (cold)	24,5 s	5,7 s
Build de producție (cu filesystem cache)	n/a	~2,1 s
Server Fast Refresh (16.2)	n/a	67–100% mai rapid
Dimensiune bundle JS (tree-shaking)	baseline	−3 până la −7%
Suport plugin-uri Webpack	Da	Nu (doar loadere)

În Next.js 16.2 (martie 2026), echipa Turbopack a refăcut Server Fast Refresh și a obținut un câștig de 400–900% la compile time pentru server components. Practic, devine imperceptibil într-un dev loop. Dacă plătești minute de CI/CD pe Vercel, GitHub Actions sau CircleCI, migrarea se amortizează în mai puțin de o săptămână.

Cum activez Turbopack pentru build-uri de producție

În Next.js 16 nu trebuie să activezi nimic. next build folosește Turbopack implicit. Dacă vrei explicit să rămâi pe Webpack (pentru că ai un plugin necompatibil), trebuie să adaugi flag-ul --webpack:

// package.json
{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "dev:legacy": "next dev --webpack",
    "build:legacy": "next build --webpack"
  }
}

Configurarea Turbopack trăiește acum la nivelul top al next.config.ts, NU sub experimental. Aceasta este una dintre breaking changes cele mai întâlnite la upgrade:

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

const nextConfig: NextConfig = {
  // ✅ Next.js 16, la nivel top
  turbopack: {
    rules: {},
    resolveAlias: {},
  },
  experimental: {
    // ❌ NU mai pune turbopack aici (eliminat în 16.0)
    // Singurele setări Turbopack rămase în "experimental" sunt cache flags
    turbopackFileSystemCacheForDev: true,
    turbopackFileSystemCacheForBuild: false, // opt-in pentru build
  },
}

export default nextConfig

Dacă ai un proiect mai vechi pe experimental.turbo (Next.js 13–15.2), rulează codemod-ul oficial care face migrarea automat (nu trebuie să rescrii config-ul manual):

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

Verifică în CI că next build raportează în terminal "Creating an optimized production build using Turbopack". Dacă vezi în continuare "Compiling with Webpack", ai un next.config.js care setează explicit experimental.webpackBuildWorker sau un script care încă pasează --webpack.

Cum migrez de la Webpack la Turbopack pas cu pas

Am condus migrarea pe un monorepo cu 14 aplicații Next.js și 80+ pachete partajate. Procesul recomandat, validat de echipa Vercel în ghidul oficial de upgrade la Next.js 16, este:

1. Audit plugin-uri Webpack. Caută în repo webpack: și new (\w+)Plugin. Lista tipică: @sentry/webpack-plugin, webpack-bundle-analyzer, SubresourceIntegrityPlugin (de înlocuit cu features native), ForkTsCheckerWebpackPlugin (înlocuit de type-check incremental).
2. Audit loadere. Loaderele care întorc JavaScript sunt suportate (SVGR, graphql-tag/loader, mdx-loader). Loaderele care transformă imagini sau CSS sub formă de stylesheet final (de exemplu file-loader, url-loader) NU sunt suportate. Folosește next/image, next/font sau import-uri statice.
3. Rulează codemod-ul. npx @next/codemod@latest upgrade latest mută experimental.turbo, actualizează next.config.* și ajustează script-urile din package.json.
4. Test în development. pnpm dev trebuie să pornească fără erori în consolă. Cere echipei să testeze 24–48h cu Turbopack înainte să schimbi build-ul de producție.
5. Test build producție. Rulează next build local și compară output-ul .next. Dimensiunea bundle-urilor ar trebui să fie egală sau mai mică.
6. Activează filesystem cache în CI. Vezi secțiunea dedicată mai jos.

Pentru proiecte care folosesc autentificare custom prin middleware, vezi separat ghidul nostru de migrare de la middleware la proxy.ts în Next.js 16. Interacțiunea dintre Turbopack și proxy.ts era buggy în 16.0 și a fost stabilizată în 16.1.

Configurare loadere SVG, GraphQL și resolveAlias

În experiența mea, 80% din migrările care eșuează o fac pe import-uri SVG. Cu Webpack-ul vechi foloseai @svgr/webpack printr-un module.rules complicat. Cu Turbopack, regulile sunt declarative și locale fișierului:

// next.config.ts
const nextConfig: NextConfig = {
  turbopack: {
    rules: {
      '*.svg': {
        loaders: ['@svgr/webpack'],
        as: '*.js',
      },
      '*.graphql': {
        loaders: ['graphql-tag/loader'],
        as: '*.js',
      },
    },
    resolveAlias: {
      // alias simplu (ca în resolve.alias din Webpack)
      underscore: 'lodash',
      // alias condițional pentru browser vs server
      mocha: { browser: 'mocha/browser-entry.js' },
    },
    resolveExtensions: [
      '.mdx', '.tsx', '.ts', '.jsx', '.js', '.mjs', '.json',
    ],
  },
}

Câteva detalii pe care le-am descoperit pe hard mode în reviewuri de cod:

• as: '*.js' nu este opțional. Fără el, Turbopack nu știe că loader-ul produce JavaScript și aruncă "unexpected token".
• resolveExtensions suprascrie lista default. Dacă pui doar ['.mdx'], Turbopack nu va mai rezolva .tsx. Include întotdeauna lista completă.
• Loaderele rulează în ordinea din array (stânga → dreapta), invers față de Webpack. Asta surprinde absolut pe toată lumea care vine din ecosistemul vechi.

Filesystem caching și optimizări CI

Începând cu Next.js 16.1, Turbopack are filesystem caching: artefacte compilate salvate pe disk între run-uri. Pentru dev este activ implicit; pentru build de producție rămâne opt-in în 16.2:

// next.config.ts
const nextConfig: NextConfig = {
  experimental: {
    turbopackFileSystemCacheForDev: true,   // implicit
    turbopackFileSystemCacheForBuild: true, // opt-in, recomandat în CI
  },
}

Cache-ul se stochează în .next/cache/turbopack. Pentru CI, urcă acest folder în cache-ul pipeline-ului. Pe GitHub Actions:

- name: Cache Turbopack
  uses: actions/cache@v4
  with:
    path: |
      .next/cache/turbopack
      .next/cache/turbo
    key: turbopack-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}-${{ github.ref }}
    restore-keys: |
      turbopack-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}-

Pe primul run veți vedea Turbopack scriind în cache (~5–7s build). Pe run-uri ulterioare, dacă lockfile-ul nu s-a schimbat, build-ul scade la 2 secunde. Acesta este momentul în care echipele de platformă rup șampania.

Subresource Integrity și securitatea bundle-urilor

În Next.js 16.2, Turbopack generează automat Subresource Integrity (SRI) hash-uri pentru toate fișierele JavaScript produse. Browserul refuză să execute orice script al cărui hash nu se potrivește. Asta închide o întreagă clasă de atacuri supply-chain (de exemplu CDN compromis sau MITM pe edge). Activarea:

// next.config.ts
const nextConfig: NextConfig = {
  turbopack: {
    integrity: {
      // generează atribute integrity pentru <script> și preload links
      enabled: true,
      algorithm: 'sha384', // implicit; alternative: sha256, sha512
    },
  },
}

În proiectele cu echipe de securitate stricte (SOC 2, ISO 27001), SRI nativ este o cerință de auditare. Anterior trebuia să integrezi SubresourceIntegrityPlugin manual; acum este built-in. Detalii complete și exemple de header CSP compatibil cu SRI vezi în anunțul Next.js 16.2 Turbopack și în documentația MDN despre Subresource Integrity.

Capcane: plugin-uri Webpack și module Node.js în browser

Cea mai dureroasă realitate: Turbopack nu suportă plugin-uri Webpack. Loaderele da, plugin-urile nu. Asta înseamnă că pachetele care depind de hook-uri precum compiler.hooks.emit sau compilation.hooks.processAssets trebuie înlocuite. Tabelul echivalențelor pe care îl țin în Notion-ul echipei:

• @sentry/webpack-plugin → @sentry/nextjs v9+ (source maps urcate via wrapper-ul Next.js)
• webpack-bundle-analyzer → @next/bundle-analyzer v16+ (suportă Turbopack nativ din 16.1)
• SubresourceIntegrityPlugin → opțiunea turbopack.integrity built-in
• CopyWebpackPlugin → folder public/ sau import-uri statice
• DefinePlugin → env sau publicRuntimeConfig în next.config.ts

A doua capcană: module Node.js (fs, path, crypto) importate accidental în cod client. În Webpack rezolva la modul gol; în Turbopack trebuie să-l declari explicit prin resolveAlias:

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

// lib/empty-module.ts
export default {}

Pentru o trecere în revistă completă a noilor pattern-uri server-side care merg mână în mână cu Turbopack, recomand și ghidul nostru de Streaming și Suspense în Next.js 16. Împreună formează stack-ul de performanță pe care îl folosim în producție.

Întrebări frecvente

Trebuie să activez Turbopack manual în Next.js 16?

Nu. Începând cu Next.js 16.0, Turbopack este implicit atât pentru next dev, cât și pentru next build. Flag-ul --turbopack nu mai este necesar și a fost eliminat. Dacă vrei să rămâi pe Webpack, folosește explicit --webpack.

Cât de rapid este Turbopack față de Webpack în producție?

Pe benchmark-uri reale (Makerkit, Syncfusion, echipele Vercel), build-urile de producție scad de la ~24s la ~5,7s, iar cu filesystem caching activ ajung sub 2,5 secunde pe run-uri repetate. Fast Refresh în development este aproximativ 10x mai rapid (45ms vs 480ms).

Suportă Turbopack plugin-uri Webpack?

Nu. Turbopack suportă un subset al API-ului de loadere Webpack (cele care întorc JavaScript), dar NU suportă plugin-uri Webpack. Pachete precum @sentry/webpack-plugin sau SubresourceIntegrityPlugin trebuie înlocuite cu echivalente native sau cu wrapper-ele oficiale (@sentry/nextjs, opțiunea built-in turbopack.integrity).

Cum migrez configurația de la experimental.turbo la turbopack?

Rulează codemod-ul oficial: npx @next/codemod@latest next-experimental-turbo-to-turbopack .. Acesta mută cheia experimental.turbo la nivelul top turbopack în next.config.ts. Cheia experimental.turbo a fost eliminată complet în Next.js 16.

Pot folosi import-uri SVG cu @svgr/webpack în Turbopack?

Da. Adaugă o regulă în turbopack.rules: '*.svg': { loaders: ['@svgr/webpack'], as: '*.js' }. Cheia as: '*.js' este obligatorie pentru ca Turbopack să trateze output-ul ca JavaScript valid.

Ce versiune minimă de Next.js 16 ar trebui să folosesc în producție?

Minimum 16.2.6 (mai 2026). Această versiune include 13 patch-uri de securitate coordonate, fix-urile pentru Server Fast Refresh și filesystem caching stabilizat. Versiunile anterioare ale liniei 16.x au CVE-uri cunoscute.