Introduction

Turbopack has reached stability in Next.js 15, marking the end of Webpack's decade-long dominance as the default JavaScript bundler for React applications. Built in Rust by the team behind Webpack itself, Turbopack delivers 700x faster incremental builds than Webpack in the largest applications, with cold startup times reduced from minutes to seconds. This isn't an incremental improvement—it's a paradigm shift in how JavaScript applications are built, bundled, and served during development.

The stability milestone means Turbopack is now the recommended bundler for next dev, with full support for all Next.js features including App Router, Server Components, Server Actions, Middleware, and image optimization. Production builds continue to use Webpack while Turbopack's production optimization pipeline matures, but development workflows can immediately benefit from the speed improvements.

Understanding Turbopack: Core Concepts

The Architecture

Turbopack is built on Turbo, the Rust-based incremental computation framework. Unlike Webpack's eager bundling model (which processes the entire dependency graph on every change), Turbopack uses a lazy, demand-driven approach. It only processes the code that's actually needed for the current page, deferring everything else.

The key architectural decisions:

1. Rust-native: All core operations (parsing, resolving, transforming, bundling) are implemented in Rust, eliminating JavaScript runtime overhead
2. Function-level caching: Changes are tracked at the function level, not the module level, enabling more granular invalidation
3. Lazy bundling: Only the code needed for the current request is processed
4. Persistent disk cache: Build artifacts survive process restarts, making subsequent startups near-instant

How Turbopack Processes Code

When you save a file, Turbopack:

1. Detects the file change via filesystem watcher
2. Identifies which functions in the file changed (not just which files)
3. Invalidates only those functions in the computation graph
4. Recomputes only the affected outputs
5. Sends the update to the browser via HMR

This is fundamentally different from Webpack's approach:

Turbopack vs Other Bundlers

Enabling Turbopack

Development Mode

# Enable Turbopack for development
next dev --turbopack
 
# Or in package.json
{
  "scripts": {
    "dev": "next dev --turbopack",
    "dev:webpack": "next dev"  // Fallback to Webpack if needed
  }
}

Configuration

Turbopack supports most Webpack configuration through next.config.js:

// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  // Turbopack-specific configuration
  turbopack: {
    // Module resolution aliases (replaces Webpack resolve.alias)
    resolveAlias: {
      '@components': './src/components',
      '@lib': './src/lib',
      '@styles': './src/styles',
    },
    // Extensions to resolve (replaces Webpack resolve.extensions)
    resolveExtensions: ['.ts', '.tsx', '.js', '.jsx', '.json'],
    // Custom loaders (subset of Webpack loader API)
    rules: {
      '*.svg': {
        loaders: ['@svgr/webpack'],
        as: '*.js',
      },
    },
  },
 
  // Standard Next.js config works with Turbopack
  images: {
    remotePatterns: [
      { protocol: 'https', hostname: '**.example.com' },
    ],
  },
  experimental: {
    optimizePackageImports: ['lodash', 'date-fns', 'lucide-react'],
  },
}
 
module.exports = nextConfig

Turbopack Module Resolution

Turbopack uses the same module resolution algorithm as Webpack (enhanced resolution) but with Rust-native performance:

// These configurations work identically in Turbopack and Webpack
 
// tsconfig.json paths
{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"],
      "@components/*": ["./src/components/*"]
    }
  }
}
 
// Import resolution
import { Button } from '@/components/ui/button'  // Works
import { formatDate } from '@lib/utils'            // Works
import styles from './page.module.css'              // Works (CSS Modules)

Performance Deep Dive

Cold Startup

Cold startup is the time from running next dev to the development server being ready. Turbopack's persistent cache makes subsequent startups nearly instant:

# First run (no cache)
$ time next dev --turbopack
ready - started server on 0.0.0.0:3000
2.4s
 
# Second run (cache hit)
$ time next dev --turbopack
ready - started server on 0.0.0.0:3000
0.8s
 
# Webpack comparison
$ time next dev
ready - started server on 0.0.0.0:3000
34.2s

Hot Module Replacement (HMR)

HMR is the measure of how quickly changes appear in the browser after saving a file:

// Changing this component...
 
export function Counter() {
  const [count, setCount] = useState(0)
  return (
    <div>
      <p>Count: {count}</p>  // Change "Count" to "Total"
      <button onClick={() => setCount(c => c + 1)}>Increment</button>
    </div>
  )
}
 
// Turbopack HMR: 15-32ms
// Webpack HMR: 450-870ms

Real-World Application Benchmarks

Benchmarks from production applications with actual codebases:

HMR benchmarks (single file change):

Migration Guide

Step 1: Verify Compatibility

Check if your project uses Webpack-specific features that Turbopack doesn't support:

# Common Webpack plugins with Turbopack status
- webpack.DefinePlugin → ✅ Use env vars or Next.js config
- webpack.IgnorePlugin → ✅ Not needed (tree shaking handles this)
- MiniCssExtractPlugin → ✅ Built into Turbopack
- TerserPlugin → ✅ Built into Turbopack
- CopyWebpackPlugin → ⚠️ Use public/ directory instead
- ModuleFederationPlugin → ❌ Not supported yet
- custom Webpack loaders → ⚠️ Partial support

Step 2: Update Configuration

// Before: Webpack customization
module.exports = {
  webpack: (config) => {
    config.resolve.alias['@components'] = path.resolve(__dirname, 'src/components')
    config.module.rules.push({
      test: /\.svg$/,
      use: ['@svgr/webpack'],
    })
    return config
  },
}
 
// After: Turbopack configuration
module.exports = {
  turbopack: {
    resolveAlias: {
      '@components': './src/components',
    },
    rules: {
      '*.svg': {
        loaders: ['@svgr/webpack'],
        as: '*.js',
      },
    },
  },
}

Step 3: Handle Incompatibilities

// If you use features not yet supported by Turbopack:
 
// Option 1: Conditional bundler selection
// package.json
{
  "scripts": {
    "dev": "next dev --turbopack",
    "dev:legacy": "next dev",  // Fallback for Webpack-specific features
    "build": "next build"       // Production still uses Webpack
  }
}
 
// Option 2: Use environment variable for conditional config
// next.config.js
const isTurbopack = process.env.TURBOPACK === '1'
 
module.exports = {
  ...(isTurbopack ? {
    turbopack: { resolveAlias: { '@components': './src/components' } }
  } : {
    webpack: (config) => {
      config.resolve.alias['@components'] = path.resolve('src/components')
      return config
    }
  })
}

Real-World Use Cases

Use Case 1: Large Enterprise Application

An enterprise application with 5,000+ modules and 200+ pages migrated from Webpack to Turbopack. The development team experienced:

• Cold startup: 120s → 8.5s (14x improvement)
• HMR: 1.4s → 45ms (31x improvement)
• Developer satisfaction: Significantly improved ("changes appear instantly")
• CI/CD: Not affected (production still uses Webpack)

The team estimated that the HMR improvement alone saved each developer 45 minutes per day in waiting time.

Use Case 2: Component Library Development

A component library with 150+ components used Turbopack for rapid iteration during component development. The instant HMR allowed designers and developers to iterate on visual details in real-time, reducing the design-to-implementation cycle from hours to minutes.

Use Case 3: Monorepo with Multiple Apps

A monorepo with 8 Next.js applications and 30+ shared packages used Turbopack for development. The lazy bundling approach meant only the active application's code was processed, reducing startup time from 90s (Webpack processing all apps) to 4s (Turbopack processing only the active app).

Best Practices for Production

1. Use Turbopack for development, Webpack for production: Turbopack is optimized for development workflows. Production builds still benefit from Webpack's mature optimization pipeline.

2. Enable persistent cache: Turbopack's disk cache makes subsequent startups near-instant. Don't disable it unless debugging cache issues.

3. Migrate Webpack config incrementally: Start with resolve.alias and simple loader rules. Complex Webpack configurations may need Turbopack-specific alternatives.

4. Monitor memory usage: Turbopack uses less memory than Webpack for equivalent workloads, but very large applications may still need memory tuning.

5. Use optimizePackageImports: This Next.js feature works with Turbopack to reduce the import footprint of large packages like lodash, date-fns, and icon libraries.

6. Test with Turbopack in CI: Add a CI job that runs next dev --turbopack and verifies the development server starts and serves pages correctly.

7. Report incompatibilities: If you encounter features that work in Webpack but not Turbopack, report them to the Next.js team. The compatibility gap is closing rapidly.

8. Measure the improvement: Use time or built-in profiling to measure cold startup and HMR times before and after enabling Turbopack.

Common Pitfalls and Solutions

Performance Optimization

// Optimize Turbopack with package imports
// next.config.js
module.exports = {
  experimental: {
    optimizePackageImports: [
      'lodash',           // Import only used functions
      'date-fns',         // Import only used date functions
      'lucide-react',     // Import only used icons
      '@heroicons/react', // Import only used icons
      'rxjs',             // Import only used operators
    ],
  },
}
 
// Instead of importing entire packages:
import _ from 'lodash'  // ❌ Imports 70KB+
 
// Turbopack optimizes to:
import { debounce, throttle } from 'lodash'  // ✅ Imports only what's used

Comparison with Alternatives

Advanced Patterns

Custom Turbopack Loaders

// next.config.js
module.exports = {
  turbopack: {
    rules: {
      // SVG as React components
      '*.svg': {
        loaders: [{
          loader: '@svgr/webpack',
          options: { icon: true, svgo: true },
        }],
        as: '*.js',
      },
      // Custom markdown loader
      '*.md': {
        loaders: [{
          loader: 'remark-loader',
          options: { remarkOptions: { plugins: [] } },
        }],
        as: '*.js',
      },
    },
  },
}

Turbopack with Monorepos

// next.config.js for monorepo
const path = require('path')
 
module.exports = {
  turbopack: {
    resolveAlias: {
      // Reference packages in monorepo
      '@shared/ui': path.resolve(__dirname, '../../packages/ui/src'),
      '@shared/utils': path.resolve(__dirname, '../../packages/utils/src'),
      '@shared/types': path.resolve(__dirname, '../../packages/types/src'),
    },
  },
}

Testing Strategies

// Testing Turbopack configuration
import { createServer } from 'next/dist/server/next'
 
describe('Turbopack dev server', () => {
  let server
 
  beforeAll(async () => {
    server = createServer({
      dev: true,
      turbopack: true,
      dir: process.cwd(),
    })
    await server.prepare()
  }, 30000)  // Allow 30s for cold start
 
  afterAll(async () => {
    await server.close()
  })
 
  it('starts within 10 seconds', async () => {
    const start = Date.now()
    const app = server.getRequestHandler()
    const res = await app(new Request('http://localhost:3000'))
    const duration = Date.now() - start
 
    expect(duration).toBeLessThan(10000)
    expect(res.status).toBe(200)
  })
})

Turbopack Architecture Deep Dive

Rust-Based Computation Engine

Turbopack's performance advantage comes from its Rust-native implementation. Every operation—parsing JavaScript, resolving imports, transforming syntax, generating bundles—is implemented in Rust, eliminating the overhead of JavaScript's garbage collector and runtime interpretation.

The incremental computation engine tracks dependencies at the function level, not the module level. When you change a single function in a large module, Turbopack invalidates only that function and its dependents, rather than reprocessing the entire module graph. This granular invalidation is the key to sub-50ms HMR times.

// Turbopack's incremental computation model (conceptual)
// When function `calculateTotal` changes:
// 1. Invalidates: calculateTotal
// 2. Invalidates: OrderSummary (uses calculateTotal)
// 3. Invalidates: CheckoutPage (uses OrderSummary)
// 4. Does NOT invalidate: UserAvatar, NavigationBar, ProductCard

Module Graph Optimization

Turbopack optimizes the module graph through tree shaking, code splitting, and lazy loading:

// Turbopack automatically code-splits at dynamic import boundaries
const HeavyComponent = dynamic(() => import('./HeavyComponent'), {
  loading: () => <Skeleton />,
  ssr: false, // Client-only rendering
});
 
// Route-level code splitting (automatic in App Router)
// app/dashboard/page.tsx is automatically code-split from app/page.tsx

Persistent Caching Strategy

Turbopack's persistent cache stores intermediate computation results on disk. On subsequent startups, it loads the cache and only recomputes what changed since the last session:

# Cache location
.next/cache/turbopack/
 
# Cache contents:
# - Parsed module ASTs
# - Resolved dependency graphs
# - Transformed source code
# - Generated bundle chunks
 
# Clear cache if corrupted
rm -rf .next/cache/turbopack

Production Build Optimization Strategies

While Turbopack handles development, production builds still use Webpack. Optimize your production builds:

// next.config.js - production optimizations
module.exports = {
  // Compression
  compress: true,
 
  // Image optimization
  images: {
    formats: ['image/avif', 'image/webp'],
    deviceSizes: [640, 750, 828, 1080, 1200, 1920, 2048],
  },
 
  // Bundle analysis
  webpack: (config, { dev, isServer }) => {
    if (!dev && !isServer) {
      config.optimization.splitChunks = {
        chunks: 'all',
        cacheGroups: {
          vendor: {
            test: /[\\/]node_modules[\\/]/,
            name: 'vendors',
            chunks: 'all',
          },
        },
      };
    }
    return config;
  },
 
  // Output configuration
  output: 'standalone', // For Docker deployments
};

Troubleshooting Common Issues

Cache Corruption

If Turbopack behaves unexpectedly, clear the cache:

# Clear all Next.js caches
rm -rf .next
 
# Clear only Turbopack cache
rm -rf .next/cache/turbopack
 
# Restart dev server
npm run dev

Memory Limits

For very large applications, increase Node.js memory:

{
  "scripts": {
    "dev": "NODE_OPTIONS='--max-old-space-size=8192' next dev --turbopack"
  }
}

Module Resolution Errors

If imports fail after enabling Turbopack, check your path aliases:

// next.config.js - ensure aliases match tsconfig.json
module.exports = {
  turbopack: {
    resolveAlias: {
      // Must match tsconfig.json paths
      '@components': './src/components',
      '@lib': './src/lib',
    },
  },
};

CSS and PostCSS Issues

If CSS preprocessing fails, ensure PostCSS and Tailwind are properly configured:

// postcss.config.js - must exist at project root
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
};

Source Map Debugging

Turbopack generates source maps that work with browser DevTools and VS Code:

// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next.js: debug server-side",
      "type": "node",
      "request": "attach",
      "port": 9229
    }
  ]
}

Future Outlook

Turbopack's roadmap includes production build support (currently in development), incremental compilation for CI/CD, and support for additional frameworks beyond Next.js. The Rust-based tooling trend (SWC, Turbopack, Rspack, OXC) is accelerating, and Turbopack is positioned to become the standard bundler for React applications.

The Next.js team has announced that Turbopack for production is actively being developed, with early benchmarks showing 5-10x faster production builds than Webpack. When production support ships, it will eliminate the need to maintain separate Webpack and Turbopack configurations. The team is also working on Turbopack support for other frameworks, potentially making it a universal Rust-based bundler for the JavaScript ecosystem.

Integration with the React Compiler (formerly React Forget) is another exciting development. The React Compiler can automatically memoize components, and Turbopack's function-level caching makes it the ideal bundler for leveraging compiler optimizations. Together, they promise a future where developers write straightforward React code and the toolchain handles performance optimization automatically without any manual intervention.

Conclusion

Turbopack in Next.js 15 represents the most significant improvement to JavaScript development tooling in a decade. The Rust-based bundler delivers 700x faster incremental builds than Webpack, with HMR times reduced from hundreds of milliseconds to tens of milliseconds. For development workflows, Turbopack transforms the feedback loop from "save, wait, see" to "save, see."

Key takeaways:

1. Turbopack is stable for next dev—enable it immediately for development speed improvements
2. Production builds still use Webpack—don't use --turbopack in CI/CD yet
3. HMR improvements range from 15x to 31x depending on application size
4. Persistent cache makes subsequent startups near-instant (0.8s vs 34s for Webpack)
5. Migrate Webpack config to Turbopack's resolveAlias and rules configuration

For the complete Turbopack documentation, visit turbo.build/pack. For migration guidance, consult the Next.js Turbopack guide.