Agent skill

turbopack

Configures Turbopack as the default Rust-based bundler for Next.js with incremental compilation and webpack loader compatibility. Use when optimizing Next.js development builds, migrating from webpack, or configuring custom loaders.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/development/turbopack

SKILL.md

Turbopack

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

Quick Start

bash
# 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+)

typescript
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)

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

Loader Configuration

SVG as React Components

typescript
turbopack: {
  rules: {
    '*.svg': {
      loaders: ['@svgr/webpack'],
      as: '*.js',
    },
  },
}
tsx
import Logo from './logo.svg';

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

GraphQL

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

YAML/TOML

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

Markdown

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

Loader Options

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

Resolve Configuration

Path Aliases

typescript
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

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

Performance Comparison

Feature Turbopack Webpack
Cold start ~700x faster Baseline
HMR updates ~10x faster Baseline
Memory usage Lower Higher
Incremental Native Limited

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:

typescript
// 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

typescript
// 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:

bash
next dev --webpack  # Keep using webpack if needed

Replace Custom Webpack Config

typescript
// 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

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

Memory Issues

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

Cache Issues

bash
# Clear Turbopack cache
rm -rf .next
next dev

Alternative: Rspack

For projects with complex webpack configs:

bash
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.

Didn't find tool you were looking for?

Be as detailed as possible for better results