Turbopack Bundler Setup for Web Project

Turbopack Bundler Configuration for Web Project

Turbopack is a bundler by Vercel, written in Rust, developed as Webpack successor inside Next.js. As of 2025, it's stable for dev mode in Next.js 13+ and gradually gaining production build support. Direct use outside Next.js is currently limited.

Current status

Turbopack doesn't exist as a standalone tool with open configuration API — unlike Webpack, Vite, or esbuild. It's integrated into Next.js via --turbopack flag and configured via next.config.ts. This is deliberate team decision: first stabilize within one framework, then expand support.

What to expect:

• dev mode — stable with Next.js 14+, noticeable speed gains for large codebases
• production build — in active development, support appeared in Next.js 15 in experimental mode
• standalone use — not publicly available yet

Enabling in Next.js

# Next.js 14+
next dev --turbopack

# Or via package.json
{
  "scripts": {
    "dev": "next dev --turbopack",
    "build": "next build"  // production without flag for now
  }
}

Configuration via next.config.ts

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

const config: NextConfig = {
  experimental: {
    turbo: {
      // Custom loaders (webpack loaders equivalent)
      rules: {
        '*.svg': {
          loaders: ['@svgr/webpack'],
          as: '*.js',
        },
        '*.mdx': {
          loaders: ['@mdx-js/loader'],
          as: '*.js',
        },
      },

      // Path aliases
      resolveAlias: {
        '@components': './src/components',
        '@utils': './src/utils',
        // Module replacement (webpack resolve.alias equivalent)
        'lodash': 'lodash-es',
      },

      // File extensions in priority order
      resolveExtensions: ['.tsx', '.ts', '.jsx', '.js', '.json'],
    },
  },
};

export default config;

Webpack loaders compatibility

Turbopack supports limited set of webpack-compatible loaders. Fully compatible:

rules: {
  '*.mdx': { loaders: ['@mdx-js/loader'], as: '*.js' },
  '*.svg': { loaders: ['@svgr/webpack'], as: '*.js' },
  '*.yaml': { loaders: ['yaml-loader'], as: '*.js' },
  '*.graphql': { loaders: ['graphql-tag/loader'], as: '*.js' },
}

Don't work or work partially: most CSS-loaders (Next.js handles CSS itself), loaders with complex side-effects, loaders requiring webpack compilation hooks.

Environment variables and define

// In next.config.ts Turbopack respects standard Next.js env
// .env.local, .env.development, .env.production

// For custom define there's no direct API in Turbopack —
// use standard Next.js mechanism:
const config: NextConfig = {
  env: {
    CUSTOM_KEY: process.env.CUSTOM_KEY,
  },
};

Performance debugging

Turbopack has built-in tracing:

NEXT_TURBOPACK_TRACING=1 next dev --turbopack

Generates .next/trace file, which can be opened in Chrome DevTools Performance tab via chrome://tracing.

Useful metrics to track after enabling Turbopack:

# Time of first dev server start
time next dev --turbopack

# Time of HMR after file change — see in terminal:
# "compiled client and server successfully in Xms"

Limitations vs Webpack

Currently unavailable in Next.js with Turbopack:

• webpack() function in next.config.ts is ignored
• Some Babel plugins (Turbopack uses SWC)
• next/bundle-analyzer — replacement: @next/bundle-analyzer doesn't work, use turbo-pack-analyze or built-in tracing
• Part of community plugins that patch webpack config directly

// This won't work with --turbopack:
const config: NextConfig = {
  webpack(config) {
    config.plugins.push(new MyPlugin());  // ignored
    return config;
  },
};

Migration from webpack customizations

If project uses non-standard webpack configurations, audit before enabling Turbopack:

# Check what's used in webpack config
grep -r "webpack(" next.config.*
grep -r "new webpack\." next.config.*

For each customization, find equivalent in Turbopack API or temporarily keep webpack for production:

// Hybrid approach: Turbopack for dev, Webpack for build
{
  "scripts": {
    "dev": "next dev --turbopack",
    "build": "next build"  // webpack
  }
}

Timeline

Enabling --turbopack in existing Next.js project without custom webpack loaders: 1–2 hours (including testing and compatibility verification). Migrating project with non-standard webpack configurations: 1–3 days depending on customization complexity.