Turbopack

Since Next.js 16 10,514 Turbopack 10,514 is the default bundler for next dev and next build, which is why every build in this chapter opens with ▲ Next.js 16.3.5 (Turbopack). Webpack 3,824 remains behind --webpack, needed on platforms with no native bindings (Turbopack ships for macOS, Windows and Linux on x64 and ARM64) and for the few things it replaced: webpack() config functions, webpack plugins — loaders do work — Yarn 11,798 PnP and sassOptions.functions. Configuration lives under a turbopack key:

const nextConfig: NextConfig = {
  turbopack: {
    root: __dirname,
    rules: { '*.txt': { type: 'asset' } },
    resolveAlias: { '@flags': './lib/flags.prod.ts' },
  },
}

root is the filesystem boundary: modules outside it are not resolved, which keeps cache validation and file watching cheap. Next.js infers it from the nearest lockfile and says so when the guess is ambiguous. A stray package-lock.json in a parent folder produced this, which setting root silenced:

⚠ Warning: Next.js inferred your workspace root, but it may not be correct.
 We detected multiple lockfiles and selected the directory of
 ...\scratchpad\package-lock.json as the root directory.
 To silence this warning, set `turbopack.root` in your Next.js config

rules maps a glob to a module type (asset, raw, css, wasm, ...) or to webpack loaders; resolveAlias redirects module specifiers. With the config above, import url from '../../content/shipping.txt' rendered /_next/static/media/shipping.1m-v_xg3t6g5d.txt, and import { showBeta } from '@flags' rendered false — the value in flags.prod.ts, not the true in lib/flags.ts.

The filesystem cache

Turbopack caches at function granularity and persists that cache to .next/cache/turbopack, by default in dev and in builds (turbopackFileSystemCacheForDev and ...ForBuild under experimental, both true):

The cache cost 34 MB there. Set turbopackFileSystemCacheForBuild: false only where CI discards .next/cache anyway; otherwise make sure the pipeline restores that directory.