@rspack/dev-server

@rspack/dev-server is the official development server for Rspack, the Rust-based successor to webpack. It wraps a compiler instance with an HTTP(S) server, WebSocket-driven hot module replacement, live reload, static file serving, and a request proxy — the same feature set webpack-dev-server established, ported to Rspack’s build pipeline via @rspack/dev-middleware.

It ships as both a CLI-invoked server (rspack serve, provided by @rspack/cli) and a programmatic RspackDevServer class, so teams migrating from webpack keep a familiar devServer configuration object — proxy rules, HTTPS certs via selfsigned, custom WebSocket server implementations, and static-file options all carry over — while getting Rspack’s faster incremental rebuilds underneath.

What You Get

• Hot module replacement over WebSockets with an injected client overlay for build errors
• Live reload fallback for changes that can’t be hot-applied
• Pluggable HTTP server backends (native http/https, Express, Connect, or Hono) via the server option
• Built-in HTTPS support with automatic self-signed certificate generation
• Reverse proxy configuration for routing requests to a separate backend during development
• History API fallback for client-side-routed single-page apps

Common Use Cases

• Running rspack serve locally during frontend development for instant HMR feedback
• Migrating a webpack-dev-server-based project to Rspack while keeping the same devServer config shape
• Proxying API requests to a backend service while serving Rspack-built assets from the same origin
• Serving an app over HTTPS locally to test OAuth callbacks, secure cookies, or service workers
• Embedding a dev server programmatically (via RspackDevServer) inside a custom CLI or test harness

Under The Hood

Architecture The package centers on a single Server class (src/server.ts, ~2,700 lines) that wires together @rspack/dev-middleware for compiled-asset serving, a WebsocketServer (extending a shared BaseServer) for the HMR/live-reload transport, static file and history-API-fallback handling, HTTPS certificate setup, and reverse proxying. Config normalization lives in config.ts, producing a ResolvedDevServer shape consumed by Server. The public entry point (src/index.ts) re-exports only RspackDevServer and a re-exported Configuration type from @rspack/core, keeping the external surface deliberately thin even though most logic is concentrated in one large file — a direct consequence of this being a close fork of webpack-dev-server’s monolithic-server pattern rather than a redesigned modular architecture. A separately bundled client (client-src/) handles the browser side of the WebSocket protocol, message parsing, and error overlay rendering.

Tech Stack Written in TypeScript, published as ESM only, targeting Node 20.19+/22.12+. Core runtime dependencies include @rspack/dev-middleware for serving compiled output, ws for the WebSocket transport, pluggable HTTP layers via express, connect-next, and hono, http-proxy-middleware for request proxying, selfsigned for on-demand HTTPS certificates, chokidar for file watching, and launch-editor for click-to-open-in-editor support from error overlays. The project is built and tested through an internal monorepo toolchain (rstack/rs CLI commands for build, lint, and test), with @microsoft/api-extractor rolling up type declarations for publication.

Code Quality Testing spans unit tests (e.g. ansiHTML.test.ts), a Puppeteer-driven e2e/ suite exercising real browser behavior, and a type-tests/ directory validating the public TypeScript API — a genuinely layered test setup, though the normalizeOptions.test.ts snapshot suite is currently describe.skipped rather than running. Error handling favors explicit, typed checks over silent swallowing (getPort.ts inspects NodeJS.ErrnoException codes and rethrows anything unexpected rather than catching broadly). Types are strict and comprehensive (types.ts, config.ts), naming is consistent, and CI (.github/workflows/test.yml) runs the test suite across both Ubuntu and Windows runners plus a separate lint/format check job.

API Design The public API is intentionally narrow: one RspackDevServer class plus a re-exported Configuration type, so integrators have a single entry point and a single options object to learn rather than assembling several plugin configs. The zero-config CLI path (rspack serve) covers the common case, and the programmatic path (new RspackDevServer(options, compiler)) requires only a few lines to start a server. Because this is a close adaptation of webpack-dev-server, it doesn’t introduce new API conventions of its own, but it inherits years of upstream refinement — pluggable server implementations, an array-based proxy config, static-file options — while swapping in Rspack-specific internals like @rspack/dev-middleware. Documentation beyond the README lives externally on the rspack.rs config site rather than in embedded guides.