Claude Code for Rspack — Workflow Guide

Written by Michael Lip · Solo founder of Zovo · $400K+ on Upwork · 100% JSS Join 50+ builders · More at zovo.one

The Setup

You are migrating from Webpack to Rspack, the Rust-based bundler that is API-compatible with Webpack but 5-10x faster. Rspack supports most Webpack loaders and plugins, making migration straightforward. Claude Code can assist with the migration, but it sometimes generates pure Webpack configs that include incompatible features or misses Rspack-specific optimizations.

What Claude Code Gets Wrong By Default

  1. Generates a full Webpack config as-is. Claude copies the existing webpack.config.js without adjustments. While Rspack is mostly compatible, some Webpack plugins need Rspack equivalents (like @rspack/plugin-html instead of html-webpack-plugin).

  2. Uses Webpack 4 syntax. Claude writes Webpack 4 patterns (optimization.splitChunks with deprecated options). Rspack targets Webpack 5 compatibility — use Webpack 5 syntax and APIs.

  3. Installs webpack alongside rspack. Claude keeps webpack and webpack-cli as dependencies. Rspack replaces both — use @rspack/core and @rspack/cli instead.

  4. Misses Rspack’s built-in features. Claude adds Babel loader for TypeScript/JSX when Rspack has a built-in SWC-based transformer that is much faster. Similarly, CSS handling is built-in without needing css-loader.

The CLAUDE.md Configuration

# Rspack Bundler Project

## Build Tool
- Bundler: Rspack (@rspack/core, Webpack 5 compatible)
- Config: rspack.config.ts at project root
- CLI: npx rspack build / npx rspack serve

## Rspack Rules
- Config format: same as Webpack 5 (module.exports = { ... })
- Use @rspack/core imports, not webpack imports
- Built-in SWC loader: no need for babel-loader or ts-loader
- Built-in CSS support: no need for css-loader, style-loader
- HTML plugin: @rspack/plugin-html (not html-webpack-plugin)
- Built-in asset modules: same as Webpack 5 asset modules
- Rspack-specific: builtins.define replaces DefinePlugin in some cases

## Conventions
- Config: rspack.config.ts (TypeScript supported natively)
- Dev server: rspack serve (built-in, replaces webpack-dev-server)
- Module federation: @module-federation/enhanced for Rspack
- Loaders: most Webpack loaders work, but prefer built-in transforms
- Plugins: check Rspack compatibility before using Webpack plugins
- Environment: RSPACK_* prefix for Rspack-specific env vars

Workflow Example

You want to migrate an existing Webpack project to Rspack. Prompt Claude Code:

“Migrate this Webpack 5 project to Rspack. Replace webpack packages with rspack equivalents, remove unnecessary loaders that Rspack handles natively, and update the config file. Keep the same entry points and output structure.”

Claude Code should replace webpack with @rspack/core, remove babel-loader in favor of Rspack’s SWC transform, remove css-loader/style-loader in favor of built-in CSS, replace html-webpack-plugin with @rspack/plugin-html, rename the config to rspack.config.ts, and update npm scripts to use rspack instead of webpack.

Common Pitfalls

  1. Loader compatibility edge cases. Claude assumes all Webpack loaders work with Rspack. Most do, but some loaders that use Webpack-specific internal APIs (like certain versions of thread-loader or cache-loader) are incompatible. Rspack has built-in parallelism and caching.

  2. Plugin initialization differences. Claude instantiates Webpack plugins with new webpack.DefinePlugin(). With Rspack, use new rspack.DefinePlugin() from @rspack/core, or the builtins.define shorthand in config.

  3. Dev server proxy configuration. Claude uses webpack-dev-server proxy options. Rspack’s dev server uses the same format but is a different implementation. Some advanced proxy features may behave slightly differently — test proxy rules after migration.