Turbopack

Turbopack

Incremental bundler written in Rust, built into Next.js for faster development builds.

Quick Start

# Turbopack is default in Next.js 16+
next dev          # Uses Turbopack
next build        # Uses Turbopack

# Explicitly use webpack instead
next dev --webpack
next build --webpack

Configuration

next.config.ts (Next.js 16+)

import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  turbopack: {
    // Custom loaders
    rules: {
      '*.svg': {
        loaders: ['@svgr/webpack'],
        as: '*.js',
      },
      '*.graphql': {
        loaders: ['graphql-tag/loader'],
        as: '*.js',
      },
    },

    // Resolve aliases
    resolveAlias: {
      '@': './src',
      '@components': './src/components',
      'lodash': 'lodash-es',
    },

    // File extensions
    resolveExtensions: ['.tsx', '.ts', '.jsx', '.js', '.json'],

    // Module ID strategy
    moduleIdStrategy: 'deterministic', // or 'named'
  },
};

export default nextConfig;

Legacy Config (Next.js 15)

// In experimental section
const nextConfig: NextConfig = {
  experimental: {
    turbo: {
      rules: {
        '*.svg': {
          loaders: ['@svgr/webpack'],
          as: '*.js',
        },
      },
    },
  },
};

Loader Configuration

SVG as React Components

turbopack: {
  rules: {
    '*.svg': {
      loaders: ['@svgr/webpack'],
      as: '*.js',
    },
  },
}

import Logo from './logo.svg';

export default function Header() {
  return <Logo className="h-8 w-8" />;
}

GraphQL

turbopack: {
  rules: {
    '*.graphql': {
      loaders: ['graphql-tag/loader'],
      as: '*.js',
    },
    '*.gql': {
      loaders: ['graphql-tag/loader'],
      as: '*.js',
    },
  },
}

YAML/TOML

turbopack: {
  rules: {
    '*.yaml': {
      loaders: ['yaml-loader'],
      as: '*.js',
    },
    '*.toml': {
      loaders: ['toml-loader'],
      as: '*.js',
    },
  },
}

Markdown

turbopack: {
  rules: {
    '*.md': {
      loaders: ['raw-loader'],
      as: '*.js',
    },
    '*.mdx': {
      loaders: ['@mdx-js/loader'],
      as: '*.js',
    },
  },
}

Loader Options

turbopack: {
  rules: {
    '*.svg': {
      loaders: [
        {
          loader: '@svgr/webpack',
          options: {
            svgo: true,
            svgoConfig: {
              plugins: [{ name: 'removeViewBox', active: false }],
            },
            titleProp: true,
          },
        },
      ],
      as: '*.js',
    },
  },
}

Resolve Configuration

Path Aliases

turbopack: {
  resolveAlias: {
    // Simple alias
    '@': './src',
    '@components': './src/components',
    '@lib': './src/lib',
    '@utils': './src/utils',

    // Package substitution
    'lodash': 'lodash-es',
    'react-native': 'react-native-web',

    // Conditional (use package.json exports)
    'package-name': './node_modules/package-name/esm/index.js',
  },
}

Extensions

turbopack: {
  // Order matters - first match wins
  resolveExtensions: [
    '.tsx',
    '.ts',
    '.jsx',
    '.js',
    '.mjs',
    '.json',
  ],
}

Performance Comparison

Supported Features

Built-in Support

• TypeScript/TSX
• JavaScript/JSX
• CSS/CSS Modules
• Sass/SCSS
• PostCSS
• next/image optimization
• next/font
• Server Components
• App Router
• Pages Router
• Middleware

Webpack Loader Compatibility

Many webpack loaders work with Turbopack:

// Tested compatible loaders
'@svgr/webpack'
'graphql-tag/loader'
'yaml-loader'
'raw-loader'
'@mdx-js/loader'
'babel-loader'
'sass-loader'

Migration from Webpack

Check for Plugin Dependencies

// webpack plugins are NOT supported
// This won't work with Turbopack:
webpack: (config) => {
  config.plugins.push(new SomeWebpackPlugin());
  return config;
}

Find Turbopack-compatible alternatives or use webpack:

next dev --webpack  # Keep using webpack if needed

Replace Custom Webpack Config

// Before (webpack)
webpack: (config) => {
  config.module.rules.push({
    test: /\.svg$/,
    use: ['@svgr/webpack'],
  });
  return config;
}

// After (Turbopack)
turbopack: {
  rules: {
    '*.svg': {
      loaders: ['@svgr/webpack'],
      as: '*.js',
    },
  },
}

Troubleshooting

Unsupported Loader

# Error: loader 'some-loader' is not supported
# Check if loader is compatible or use webpack fallback
next dev --webpack

Memory Issues

# Increase Node.js memory limit
NODE_OPTIONS="--max-old-space-size=8192" next dev

Cache Issues

# Clear Turbopack cache
rm -rf .next
next dev

Alternative: Rspack

For projects with complex webpack configs:

npm install @next/rspack

# Use in next.config.ts
import { withRspack } from '@next/rspack';

export default withRspack({
  // Full webpack API compatibility
});

See references/loaders.md for complete loader compatibility and references/migration.md for detailed migration guide.