Rspack CLI

@rspack/cli is the official command-line interface for Rspack, the Rust-based web bundler built as a near drop-in replacement for webpack. It provides the rspack binary with build, serve, and preview commands, wrapping @rspack/core’s compiler API behind a small, webpack-cli-compatible surface so existing webpack projects can adopt Rspack with minimal script changes.

Under the hood it resolves and merges rspack.config.* files (including TypeScript configs via jiti, and multi-config extends chains), applies CLI-flag overrides for entry, output, mode, devtool, and watch mode, and wires the optional @rspack/dev-server peer dependency into the serve/preview commands for local development with HMR. It’s maintained as part of the Rspack monorepo alongside @rspack/core, @rspack/dev-server, and the wider Rstack toolchain (Rsbuild, Rslib, Rspress).

What You Get

• rspack binary - a single CLI entry point exposing build, serve, and preview commands via the cac argument parser.
• Flexible config loading - resolves rspack.config.js/ts/mjs automatically, loads TypeScript configs through jiti, and merges extends chains across multiple config files.
• Dev server integration - serve and preview commands wire in the optional @rspack/dev-server peer dependency for local development with hot module replacement.
• Stats and JSON output - build results print human-readable stats by default or stream JSON stats (via @discoveryjs/json-ext) to stdout or a file for CI tooling.
• Multi-compiler support - accepts array/multi configs and CLI --config-name filtering to build only named configurations.

Common Use Cases

• Migrating a webpack project - swap webpack/webpack-cli scripts for rspack build/rspack serve against a webpack-shaped config with minimal changes.
• CI production builds - run rspack build --json stats.json in a pipeline and feed the stats file to bundle-analysis or budget-checking tools.
• Local development with HMR - run rspack serve for a dev server with fast incremental rebuilds powered by the Rust compiler core.
• Multi-target builds - use an array rspack.config.js with --config-name to build separate client/server or multiple entry configurations from one CLI invocation.

Under The Hood

Architecture @rspack/cli follows a clean command-pattern architecture: RspackCLI in src/cli.ts owns the cac-based argument parser and registers three pluggable command classes (BuildCommand, ServeCommand, PreviewCommand, each implementing RspackCommand.apply) that wire their own flags and call back into shared orchestration methods (buildCompilerConfig, createCompiler, isWatch). Config resolution is factored into its own layer (utils/loadConfig.ts), which locates rspack.config.* via findConfig, loads it through @rstackjs/load-config/jiti, and recursively resolves extends chains with loadExtendedConfig, merging results via rspack-merge while tracking each contributing file in a WeakMap-based path map later used to seed persistent-cache build dependencies. Options normalization is centralized in utils/options.ts rather than scattered across commands. The abstraction that would break the whole package if it changed is @rspack/core’s rspack() compiler factory and its Compiler/MultiCompiler/Stats types — the CLI is a thin, well-isolated shell around that API, not a reimplementation of bundler logic.

Tech Stack Written in TypeScript targeting Node ESM, the package uses cac for argument parsing, @rstackjs/load-config plus jiti for loading JS/TS config files without a separate compile step, rspack-merge for config-extends merging, @discoveryjs/json-ext for streaming large stats objects to JSON, and small supporting utilities like exit-hook, concat-stream, and execa. @rspack/core and the optional @rspack/dev-server are peer dependencies, workspace-linked in this monorepo via pnpm’s catalog protocol, keeping the CLI decoupled from a specific compiler build. It ships from a pnpm-workspace monorepo that also houses @rspack/core, create-rspack, and the Rust crates that back the actual compiler.

Code Quality The tests directory contains an extensive integration test suite covering serve, build, and API surfaces that spins up real CLI processes through a shared test-utils harness and asserts on stdout, including numbered regression tests tied to specific GitHub issues — a strong signal of test-driven regression prevention rather than ad hoc fixes. TypeScript is used throughout with explicit types for CLI options and config shapes; error handling favors typed checks such as instanceof guards over generic catches. The monorepo runs dedicated CI workflows for linting and Rust checks, and enforces formatting conventions for the Rust side it interoperates with, though the CLI package has no dedicated lint config of its own — linting is enforced monorepo-wide rather than per-package.

API Design The public surface is deliberately small and webpack-cli-shaped: three commands (build/b, serve, preview) with familiar flags for config path, config name, environment, watch mode, mode, and devtool, plus a pair of type-only defineConfig/definePlugin helpers exported for config authors. Getting started requires no CLI-specific boilerplate beyond an rspack.config.js — the CLI infers sensible default mode and devtool per command and only overrides config values when a flag is explicitly passed, so existing webpack configs largely work unmodified. Documentation lives centrally on the project’s docs site rather than in the package’s own README, which stays intentionally minimal — install instructions plus a pointer to the required dev-server peer dependency.