Turbopack

Turbopack is the Rust-based successor to Webpack in Next.js. It became the default dev bundler in Next.js 16 and is significantly faster for development, especially on large projects.

Status

# Next.js 16+: Turbopack is used by default
npm run dev

# Next.js 15: Explicitly enable
npx next dev --turbopack

# Next.js 16+: Fall back to Webpack if needed
npx next dev --no-turbopack

Performance

Turbopack uses incremental computation. It tracks dependencies at a fine-grained level and only recomputes what changed. In practice:

These numbers scale better on larger codebases. A 10,000-module app sees more dramatic improvements than a 50-module app.

Tip: The Fast Refresh improvement is the most impactful in daily development. Sub-100ms updates make editing feel instant, not just fast.

File System Caching (16.1+)

Next.js 16.1 introduces persistent File System Caching for Turbopack. Previous dev sessions are cached to disk, so restarting the dev server is nearly instant.

# First run: builds cache
npm run dev  # ~2s startup

# Second run: reads from cache
npm run dev  # ~200ms startup

The cache lives in .next/cache/turbopack. It invalidates automatically when dependencies or config change.

// next.config.ts - no special config needed, it's on by default in 16.1+
// To disable (rare):
const nextConfig = {
  turbopack: {
    unstable_fileSystemCache: false,
  },
};

Migration from Webpack

Most Next.js projects work with Turbopack without changes. Here’s what to check:

Config Differences

Webpack-specific config in next.config.ts uses the webpack key. Turbopack has its own turbopack key:

// next.config.ts
const nextConfig = {
  // Webpack config (ignored by Turbopack)
  webpack: (config) => {
    config.resolve.alias["@lib"] = path.join(__dirname, "lib");
    return config;
  },

  // Turbopack equivalent
  turbopack: {
    resolveAlias: {
      "@lib": "./lib",
    },
  },
};

Common Turbopack Configuration

// next.config.ts
const nextConfig = {
  turbopack: {
    // Custom resolve aliases
    resolveAlias: {
      "old-package": "new-package",
    },

    // Custom file extensions
    resolveExtensions: [".tsx", ".ts", ".jsx", ".js", ".mjs", ".json"],

    // Custom loaders for file types
    rules: {
      "*.svg": {
        loaders: ["@svgr/webpack"],
        as: "*.js",
      },
    },
  },
};

What Works

What Doesn’t Work (Yet)

Gotcha: If you have critical Webpack plugins with no Turbopack equivalent, you can still use Webpack for dev with --no-turbopack. But check if the plugin’s functionality is already built into Turbopack or Next.js natively.

Webpack Loaders in Turbopack

Turbopack supports a subset of Webpack loaders through its rules config:

// next.config.ts
const nextConfig = {
  turbopack: {
    rules: {
      // Use SVGR to import SVGs as React components
      "*.svg": {
        loaders: ["@svgr/webpack"],
        as: "*.js",
      },
      // Custom YAML loader
      "*.yaml": {
        loaders: ["yaml-loader"],
        as: "*.json",
      },
    },
  },
};

Debugging

Trace file

Generate a trace file for performance debugging:

NEXT_TURBOPACK_TRACING=1 npm run dev

This creates a .next/trace file you can analyze.

Common Issues

Module not found errors after switching to Turbopack:

• Check that import paths are case-sensitive (Turbopack is stricter)
• Verify path aliases match between tsconfig.json and next.config.ts

Styles not updating:

• Clear .next/cache and restart: rm -rf .next && npm run dev

Slower than expected:

• Ensure you’re not running Webpack plugins that Turbopack ignores silently
• Check for circular dependencies (Turbopack handles them but they impact performance)

Production Builds

As of Next.js 16, production builds (next build) still use Webpack by default. Turbopack for production is under active development.

# Dev: uses Turbopack
npm run dev

# Build: still uses Webpack (for now)
npm run build

Tip: Don’t worry about the dev/build bundler mismatch. Turbopack is designed to be compatible with Webpack’s output. If your app works in dev with Turbopack, it will work in production with Webpack.

Next: Cache Components | Streaming