Next.js 16 Turbopack: webpack-migraatio…

Next.js 16 teki Turbopackista oletuksen — sekä next dev- että next build -komennoille. Ja kun 16.2 ilmestyi maaliskuussa 2026, se toi mukanaan 400–900 % parannukset käännösaikoihin sekä Server Fast Refreshin, joka päivittää vain muuttuneen moduulin ja sen suorat riippuvuudet. Jos sovelluksesi nojaa yhä webpack-konfiguraatioon tai erillisiin --turbopack-flageihin, nyt on kyllä aika päivittää.

Tässä oppaassa käydään läpi konkreettinen migraatio webpackistä, tiedostojärjestelmävälimuistin konfigurointi, CI-välimuistin virittäminen ja ne yhteensopivuusansat, jotka pysäyttävät buildin ensimmäisellä yrityksellä. Omassa monorepossani siirtymä vei reilun iltapäivän — ja sen jälkeen CI-putki lyheni noin 3 minuutista 40 sekuntiin. Ei hullumpaa.

Mikä Next.js 16.2:n Turbopackissa on uutta

Turbopack on Rustilla kirjoitettu bundler, joka on suunniteltu alusta asti inkrementaaliselle uudelleenkäännökselle. Version 16.2 mittarit puhuvat puolestaan:

Tuotantobuildit 2–5× nopeammat verrattuna webpackiin suurissa sovelluksissa.
Fast Refresh jopa 10× nopeampi — tyypillisesti alle 50 ms, jopa syvästi sisäkkäisissä komponenteissa.
Server Fast Refresh päivittää vain muuttuneen moduulin ja sen suorat riippuvuudet (59 ms → 12 ms on arkinen luku iteroinnissa).
Tiedostojärjestelmävälimuisti (turbopackFileSystemCacheForDev) on oletuksena päällä ja säilyttää käännösartefaktit restarttien välillä.
Yli 200 Turbopack-korjausta pelkästään 16.2:ssa, mikä parantaa yhteensopivuutta kolmannen osapuolen paketteihin.

Käytännössä tämä tarkoittaa sitä, että sekä paikallinen kehityssilmukka että CI-putki voivat molemmat kutistua merkittävästi — kunhan konfiguraatio on kunnossa.

Esivaatimukset ja tarkistuslista ennen migraatiota

Ennen kuin ajat next build:n ilman --webpack-lippua, varmista muutama asia:

Node.js 20.9 tai uudempi. Next.js 16 nostaa minimin, joten Docker-imaget ja CI-runnerit pitää päivittää.
Ei suoraa webpack()-funktiota tiedostossa next.config.ts. Jos tiedosto sisältää sen, Turbopack-build kaatuu eksplisiittisellä virheellä.
Poista vanhat experimental.turbo-avaimet ja siirrä konfiguraatio top-level turbopack-avaimen alle.
Ei tilde-prefiksejä (~) Sass-importeissa — Turbopack ei tue tätä legacy-syntaksia.
Kartoita webpack-pluginit. Turbopack ei tue webpackin plugin-järjestelmää ollenkaan, mutta useimmat loaderit toimivat.

Tuo toinen kohta on muuten yleisin kompastuskivi — siitä lisää vähän myöhemmin.

Webpack-migraatio vaihe vaiheelta

1. Aja automaattinen codemod

Jos tulet Next.js 15.x -versiosta, kannattaa aloittaa näistä:

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

Ensimmäinen komento siirtää experimental.turbo-avaimet oikeaan paikkaan. Toinen päivittää riippuvuudet ja asynkronisoi cookies()-, headers()- ja params-kutsut, jotka Next.js 16 vaatii.

2. Siirrä konfiguraatio top-level-avaimelle

Vanha muoto:

// next.config.ts — ennen
const nextConfig = {
  experimental: {
    turbo: {
      resolveAlias: {
        '@components': './src/components',
      },
    },
  },
};
export default nextConfig;

Ja uusi:

// next.config.ts — jälkeen
import type { NextConfig } from 'next';

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

export default nextConfig;

3. Muunna `resolve.fallback` -määritykset

Jos client-koodisi on vahingossa importannut Node.js-moduuleja kuten fs tai path, saat virheilmoituksen "Module not found: Can't resolve 'fs'". Webpackissä tämä hiljennettiin resolve.fallback:lla; Turbopackissa käytetään resolveAlias:ia. Mutta, ja tämä on tärkeää: parempi ratkaisu on refaktoroida koodi niin, ettei client-bundle viittaa Node-moduuleihin ollenkaan.

// Väliaikainen hiljennys (jos pakko):
const nextConfig: NextConfig = {
  turbopack: {
    resolveAlias: {
      fs: { browser: './src/shims/empty.ts' },
      path: { browser: 'path-browserify' },
    },
  },
};

4. Päivitä tsconfig-aliakset

Turbopack lukee path-aliakset suoraan tsconfig.json:sta, joten duplikoitu konfiguraatio voidaan — ja kannattaa — poistaa:

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

5. Testaa build ilman flageja

npm run build
# Jos haluat verrata, voit aina palata webpackiin:
next build --webpack

Jos build kaatuu viestillä "Webpack is configured while Turbopack is not", jokin plugin (klassikkoepäilty: vanha @sentry/nextjs) lisää webpack()-funktion konfiguraatioon. Päivitä paketti uusimpaan versioon tai käytä hybridilähestymistapaa.

Tiedostojärjestelmävälimuistin konfigurointi

Turbopackin filesystem cache tallentaa käännösartefaktit .next-hakemistoon. Tämä nopeuttaa peräkkäisiä kehitys- ja build-ajoja — ero on usein huomattava.

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

const nextConfig: NextConfig = {
  experimental: {
    // Päällä oletuksena 16.1:stä alkaen
    turbopackFileSystemCacheForDev: true,
    // Vakaa kehityksessä, kokeellinen tuotannossa
    turbopackFileSystemCacheForBuild: true,
  },
};

export default nextConfig;

Tuotantobuildissa tämä on vielä kokeellinen, mutta suurissa monorepoissa sen avulla inkrementaaliset CI-buildit voivat pudota 3 minuutista alle 30 sekuntiin. Kannattaa siis kokeilla, vaikka status onkin "experimental".

Välimuistin tyhjennys

Jos epäilet välimuistin aiheuttaneen vioittuneen buildin:

rm -rf .next
npm run build

Turbopack validoi välimuistin sisällön automaattisesti, mutta manuaalinen poisto on nopein keino sulkea välimuisti pois vianetsinnästä. (Rehellisesti sanottuna tämä on ensimmäinen asia, jonka itse teen aina kun joku outo build-virhe vilahtaa.)

CI/CD-putken optimointi Turbopackille

Turbopackin välimuisti sijaitsee edelleen .next-hakemistossa, mutta rakenne on muuttunut. Next.js 16 lisää .next/dev-alihakemiston, jotta kehitys ja build voivat ajaa rinnakkain — päivitä siis CI-välimuistikonfiguraatiosi vastaamaan tätä.

GitHub Actions -esimerkki

name: Build
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20.9'
          cache: 'npm'

      - name: Restore Turbopack cache
        uses: actions/cache@v4
        with:
          path: |
            .next/cache
            .next/dev
          key: turbopack-${{ hashFiles('package-lock.json', 'next.config.ts') }}-${{ github.sha }}
          restore-keys: |
            turbopack-${{ hashFiles('package-lock.json', 'next.config.ts') }}-

      - run: npm ci
      - run: npm run build

Vercel, Netlify ja itse hostatut alustat

Vercelillä välimuisti on automaattista eikä vaadi konfigurointia. Itse hostatuissa Docker-imageissa kopioi .next/cache ja .next/dev build-vaiheiden välillä, tai käytä BuildKitin cache mountia:

# syntax=docker/dockerfile:1.6
FROM node:20.9-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN --mount=type=cache,target=/root/.npm npm ci
COPY . .
RUN --mount=type=cache,target=/app/.next/cache     --mount=type=cache,target=/app/.next/dev     npm run build

Yleisimmät yhteensopivuusongelmat ja niiden ratkaisut

Webpack-pluginit eivät toimi

Turbopack ei tue webpackin plugin-APIa. Yleisimmät yhteentörmäykset:

@sentry/nextjs — versio 8.40+ tukee Turbopackia natiivisti. Päivitä.
next-bundle-analyzer — käytä --webpack-lippua pelkästään analyysiajoihin, pidä Turbopack oletuksena.
@ducanh2912/next-pwa — ei vielä Turbopack-yhteensopiva; vaihda serwist:iin tai pidä webpack build-ajassa.

Ehdollinen konfiguraatio hybridille näyttää tältä:

const isTurbo = process.argv.includes('--turbopack')
             || !process.argv.includes('--webpack');

const baseConfig: NextConfig = {
  turbopack: { /* ... */ },
};

export default isTurbo
  ? baseConfig
  : withBundleAnalyzer(baseConfig);

Loaderit, jotka palauttavat CSS:ää tai kuvia

Turbopack tukee vain loadereita, jotka palauttavat JavaScriptiä. Jos olet käyttänyt url-loader:ia tai file-loader:ia kuville, siirry Next.js:n natiiviin next/image-komponenttiin ja staattisiin importteihin:

import logo from './logo.svg';
import Image from 'next/image';

export default function Header() {
  return <Image src={logo} alt="Logo" width={120} height={40} />;
}

Monorepot ja transpilePackages

Jos käytät pnpm-workspaceja ja importoit paikallisista paketeista, lisää ne transpilePackages-listaan:

const nextConfig: NextConfig = {
  transpilePackages: ['@acme/ui', '@acme/utils'],
};

CSS Modulesin latausjärjestys

Turbopack noudattaa tiukasti JavaScript-importtien järjestystä. Tämä voi aiheuttaa visuaalisia eroja, jos olet aiemmin luottanut webpackin järjestykseen. Korjaus: importtaa global CSS vain app/layout.tsx:ssä ja käytä CSS Modulesia kaikkialla muualla.

Sass custom functions

Rust-pohjainen Turbopack ei suorita JavaScript-funktioita Sass-käännöksen aikana. Jos sinulla on sass.use()-pohjaisia mukautettuja funktioita, ainoat vaihtoehdot ovat pre-kompiloida ne CSS-muuttujiksi tai pitää webpack build-ajassa. Ikävä kyllä.

Suorituskyvyn debuggaus: hitaat buildit

Kun build tuntuu yllättävän hitaalta, Turbopack tuottaa trace-tiedoston, jolla näet tarkan aikaprofiilin:

npx next internal trace .next/dev/trace-turbopack

Tuloste näyttää, mihin moduuleihin käännösaika oikeasti kuluu. Tyypillisimmät pullonkaulat:

Liian suuri node_modules-barreli-importti — vaihda import { Button } from '@acme/ui' spesifiseen importtiin import Button from '@acme/ui/button'.
Jätti-SVG:t, joita ajetaan @svgr/webpack-loaderilla — optimoi SVGO:lla etukäteen.
Dynaamiset importit, jotka eivät oikeasti ole dynaamisia — poista tarpeeton dynamic()-wrappaus, jos komponentti käytetään aina.

Stuck on compiling -tilanne

Jos näet "Compiling /page..." eikä mitään tapahdu minuutteihin, tarkista:

Onko projektisi juurihakemiston ulkopuolella olevia tiedostoja importattuna? Turbopack resolvoi vain juuren alta.
Onko jokin tiedosto päätynyt äärettömään import-silmukkaan (A importtaa B:n, B importtaa A:n)?
Onko node_modules vioittunut? rm -rf node_modules .next && npm ci poistaa useimmat epämääräiset tilat.

Milloin kannattaa jäädä webpackiin

Vaikka Turbopack on nyt oletus, webpack on edelleen tuettu --webpack-flagin takana. Harkitse webpackin säilyttämistä toistaiseksi, jos:

Sovelluksesi käyttää pakollista webpack-pluginia, jolle ei ole Turbopack-vastinetta (esim. erityiset PWA- tai AMP-työkalut).
Käytät custom Sass-funktioita JavaScriptilla.
Sinulla on kypsä CI-välimuististrategia webpackille, joka on mitattu nopeammaksi kuin Turbopack filesystem cache — ilman että se vie kohtuuttomasti kehittäjäaikaa.

Useimmille sovelluksille Turbopack on kuitenkin selvä parannus. Ja kun webpack-tuki todennäköisesti poistuu kokonaan Next.js 17:ssä, migraatio kannattaa tehdä nyt eikä myöhemmin.

Yhteenveto

Next.js 16.2:n Turbopack on mielestäni vuoden 2026 suurin kehittäjäkokemuksen harppaus framework-maailmassa. Oikein konfiguroituna se tarjoaa 2–5× nopeammat buildit, jopa 10× nopeamman Fast Refreshin ja tiedostojärjestelmävälimuistin, joka tekee CI-putkista mitattavasti nopeampia.

Migraatio on useimmissa sovelluksissa yhden iltapäivän työ: aja codemodit, siirrä konfiguraatio turbopack-avaimelle, poista webpack-funktiokutsu ja säädä plugin-yhteensopivuudet. Aloita ajamalla npm run build ilman flageja ja korjaa virheet yksi kerrallaan. Jos sovelluksesi tekee puhdasta, turvallista Next.js:ää, tulet luultavasti yllättymään siitä, miten vähän konfiguraatiota Turbopack oikeasti vaatii.

Usein kysytyt kysymykset

Onko Turbopack tuotantovalmis vuonna 2026?

Kyllä. Next.js 16 julistaa Turbopackin vakaaksi sekä next dev- että next build -komennoille, ja Vercel raportoi, että jo Next.js 15.3:ssa yli 50 % kehitysistunnoista ja 20 % tuotantobuildeista ajettiin Turbopackilla. Ainoastaan tiedostojärjestelmävälimuisti tuotantobuildeissa on vielä kokeellinen.

Tukeeko Turbopack webpack-plugineja?

Ei. Turbopack tukee ydinjoukon webpack-loadereita, mutta ei plugin-APIa. Kolmannen osapuolen paketit kuten @sentry/nextjs ja next-bundle-analyzer ovat päivittäneet Turbopack-yhteensopivuuden, mutta jotkin (esim. vanha next-pwa) vaativat vaihtoehtoisen kirjaston tai webpackin säilyttämistä.

Miksi Turbopack-build kaatuu viestillä "Webpack is configured while Turbopack is not"?

Joku paketti on lisännyt webpack()-funktion next.config.ts-tiedostoosi riippuvuuksien asennuksen yhteydessä. Tarkista next.config.ts:stä suorat webpack-viittaukset ja päivitä aiheuttava paketti (yleisimmät syyt: vanhat Sentry-, New Relic- tai DataDog-paketit). Vaihtoehtoisesti aja next build --webpack, kunnes saat paketin päivitettyä.

Kuinka paljon Turbopack nopeuttaa buildini käytännössä?

Vercelin benchmarkit lupaavat 2–5× nopeampia tuotantobuildeja, ja Next.js 16.2:n mittaukset näyttävät 400–900 % parannukset käännösajoissa. Todellinen hyöty riippuu sovelluksesi koosta ja riippuvuuksista — pienissä projekteissa ero on muutamia sekunteja, suurissa monorepoissa se voi tarkoittaa 5 minuutin buildin kutistumista 45 sekuntiin.

Voinko käyttää Turbopackia ja webpackia samassa projektissa?

Et samanaikaisesti, mutta voit ajaa molempia eri komennoissa: Turbopack oletuksena (npm run dev, npm run build) ja webpack tarvittaessa next build --webpack -lipulla analyysi- tai erikoisajoihin. Tämä hybridityönkulku on suositeltu siirtymästrategia niille, joilla on vielä webpack-only-plugineja tarvitsevia rakennusvaiheita.