web-infra-dev/rspack
github.com/web-infra-dev/rspack ↗ · 3997 files · 13.9 MB · scan capped
Rspack English | 简体中文 Rspack is a fast Rust-based bundler for the web.
Overview
Rspack is a Rust-based web bundler for application developers and tool authors who want a webpack-compatible JavaScript API, plugin hooks, and loader ecosystem. Its TypeScript layer handles configuration and developer-facing APIs while a Node-API binding delegates compilation, graph processing, and asset generation to Rust. The inspected implementation distinguishes persistent build caching from incremental recovery within a compiler lifecycle, and exposes build, development-server, and preview commands. This brief describes source at commit 179a0934f3091463419827fc2767af07b2fd38ed; inspection was bounded and no repository code was executed.
System map
Rspack has three cooperating runtime layers: the JavaScript API, the native binding, and the Rust compilation engine. Compiler and Compilation have different lifetimes, while filesystem adapters and callback bridges connect the layers. Distribution includes npm packages, native bindings, and WASM variants rather than a single hosted service. The documentation website and repository automation have separate build responsibilities.
- The public core entrypoint attaches exports to the rspack function, aliases both rspack and webpack to that function, and provides CommonJS-compatible module.exports behavior.
- The CLI executable conditionally enables Node compile caching outside CI, imports the built CLI package, constructs RspackCLI, and passes process.argv to run.
- Compiler.#getInstance lazily constructs binding.JsCompiler with raw options, builtin plugins, hook registrations, filesystem adapters, resolver access, cache, and binding helpers.
- The Rust compiler constructs normal and context module factories, runs passes against Compilation, and collects plugin-driver diagnostics into that compilation.
- NodeEnvironmentPlugin installs a CachedInputFileSystem with a 60000 ms duration, Node fs output, and either NativeWatchFileSystem or NodeWatchFileSystem according to experiments.nativeWatcher.
- Experimental new-cache storage supports optional memory and filesystem layers; its database selects TurboDatabase on native targets and NoopDatabase on WASM.
- The Cargo workspace includes crates and xtask members with Rust 2024 metadata; pnpm includes packages, bindings, website, and test workspaces, and root scripts build the binding before JS in build:cli:dev.
- Release automation builds platform-specific npm bindings including WASI and browser variants; the separate website package uses rs doc and React/Rspress dependencies.
Feature catalog
The inspected public surface includes programmatic compilation, CLI building, live development, and static preview. Configuration controls target environments, loaders, optimization, output, caching, and watch behavior. Public plugin namespaces expose federation, runtime, and chunk-loading capabilities. Compatibility has documented exceptions, so the webpack-shaped API does not establish universal feature parity.
- rspack accepts single or multiple configurations; array configurations create a MultiCompiler and register each child's named dependencies.
- The default CLI build command has build, bundle, and b aliases; --json streams stats to stdout or a requested file, and compilation errors set exitCode to 1.
- serve has server, s, and dev aliases and exposes hot, host, port, and browser-opening options; it requires the optional @rspack/dev-server package.
- preview serves a requested directory, output.path, or context/dist using an empty-entry compiler; it disables HMR and preserves configured proxy and historyApiFallback settings.
- JavaScript loader execution supports pitching and reverse-order normal execution, optional worker delegation, cached loader results, source maps, and additional data.
- The bundling pipeline includes tree shaking, splitting, JS/CSS minification, and source-map generation; options processing installs SplitChunksPlugin conditionally and warns about mixed modern-module library formats.
- Public namespaces expose ModuleFederationPlugin and ModuleFederationPluginV1, container/reference plugins, WebAssembly loading, and JavaScript chunk-loading plugins.
- Filesystem caching exposes readonly, version, memory-generation, and idle-timeout controls; HTTP URI imports separately expose allowedUris, remote cache/lockfile locations, frozen, upgrade, and custom httpClient options.
Data flow
Configuration enters through either the JavaScript API or CLI loading, then becomes normalized options and native binding inputs. Loader results and compiler passes populate compilation state before assets cross the output filesystem boundary. Rebuilds carry changed paths and prior artifacts into a new compilation. Cache storage follows a separate path with namespaced keys, memory lookup, disk restoration, and deferred persistence.
- CLI config loading resolves an explicit path or discovers rspack.config, passes env and CLI options to baseLoadConfig with fresh:true, and rejects exports that are neither an object nor an array.
- loadExtendedConfig resolves file URLs, relative/absolute paths, or packages, recursively merges base configuration beneath the current result, and accumulates loaded paths in a WeakMap.
- createCompiler normalizes options and installs the Node environment before user plugins; it then applies full defaults and options-driven plugins before initialize.
- The JS-to-Rust boundary includes builtin rule references and virtual files in raw options, and adapts input filesystem callbacks only when ThreadsafeInputNodeFS.needsBinding permits it.
- Normal loaders consume content, sourceMap, and additionalData; a cache hit restores these values, while executed loaders return transformed values that can be stored for reuse.
- Pass execution checks is_enabled, recovers pass-associated incremental artifacts, invokes cache restore hooks, runs the pass, then invokes save hooks and captures artifacts only after success.
- CompilerCache prefixes facade names with compiler_path; Cache.get checks memory first, falls through to disk only for NotCached, and records disk hits or misses in memory.
- Asset output strips filename queries, joins the target with the configured output path, compares existing content when configured, writes through output_filesystem, and calls asset_emitted with source and target metadata.
Behavior traces
Four concrete source traces were followed: CLI startup and build, asset emission, watch rebuild, and experimental filesystem-cache persistence. Their order crosses JavaScript callbacks and asynchronous Rust execution. Several lifecycle hooks can suppress output, request another pass, or delay shutdown. The traces describe implemented control flow without asserting successful execution.
- Startup proceeds runCLI → new RspackCLI → run → registerCommands → each command.apply → CAC.parse; run then awaits the action promise captured by wrapAction.
- Build startup proceeds runBuild → setDefaultNodeEnv/normalizeCommonOptions → buildCompilerConfig → loadConfig/buildConfig → createCompiler; a watch compiler returns immediately, while a one-shot compiler runs and closes before reporting stats.
- Compiler.run rejects concurrent execution, invokes beforeRun → run → compile, and may repeat compile after needAdditionalPass and additionalPass before its final done callback.
- Compiler.compile invokes beforeCompile → compile hook → #build; initial #build calls JsCompiler.build, whose callbackified future calls Rust Compiler.build → build_inner → compile → after_compile → compile_done.
- Output proceeds compile_done → should_record → should_emit; unless should_emit returns false, emit_assets resolves output.path, runs cleaning, calls emit, writes selected assets, and calls after_emit.
- A watch invalidation merges changed/removed paths and either queues invalidation during a running build or enters #go; #go pauses the watcher, assigns deltas, invokes watchRun → compile, and completed delivery watches current dependency sets again.
- Subsequent #build calls JsCompiler.rebuild with file arrays; Rust rebuild_inner clears resolver/plugin caches, creates a hot Compilation, stores the previous compilation in IncrementalArtifacts, then compiles and emits through compile_done.
- Experimental persistence proceeds create_cache → IdleFileCache background job → FileCacheStrategy.db_init/validation; build completion calls cache.beginIdle, while Compiler.close calls cache.shutdown, whose binding awaits native shutdown before native compiler close.
Testing signals
Tests and CI were inspected, not executed; no passing result is claimed. The inspected harness uses Rstest through rs test, Playwright integration for browser behavior, TypeScript checks, and Rust tests. It includes explicit exclusions and opt-in compatibility suites that limit what a default run establishes. This was bounded source inspection, not exhaustive coverage analysis.
- The integration package uses rs test with base and hottest projects; the Rstest configuration supplies shared setup files, globals, snapshot formatting, and three retries in CI.
- NewCache.test.mjs defaults to newCacheCases; normalCases/configCases compatibility runs require NEW_CACHE_CASES selection, and the cache processor asserts cache-stat snapshots and expected unchanged-build hit rates.
- The new-cache runner explicitly excludes max-age, restored loader diagnostics, coffee-loader, extract-amd, restored async-block binding access, and stateful rebuild-module cases; its comments describe unfinished compatibility.
- Incremental-watch testing reuses watchCases through createWatchIncrementalCase; native watcher tests run in a separate project with retry:0 and maxConcurrency:1.
- Browser E2E uses @rstest/playwright configuration; the inspected cross-origin lazy-compilation test clicks a dynamic-import trigger and asserts a rendered component plus a text/plain POST request.
- API type tests invoke tsc --noEmit separately for bundler and NodeNext module-resolution configurations, providing compile-time checks rather than runtime behavior tests.
- Inspected Rust snapshot tests use tokio::test for unchanged and changed filesystem states; Rust CI runs codegen, Clippy, formatting, workspace tests with exclusions, and separate watcher jobs.
- JS CI downloads binding artifacts and invokes test:ci on supported targets; WASM runs use WASM=1, but the harness excludes cache, incremental, native watcher, and several API/stat suites under WASM.
Risk map
The principal sensitive boundaries are executable build inputs, output deletion/writes, remote-resource fetching, and native-backed JavaScript lifetimes. Source contains protective conditions as well as compatibility limitations. The observations below are not confirmed vulnerabilities, and the single resource-exhaustion concern is explicitly a hypothesis. Partial inspection does not establish the absence of other guards or tests.
- Configuration loading invokes an external config loader with parameters, and plugins/loaders execute supplied functions; this is an execution trust boundary for build inputs.
- output.clean can recursively remove the configured output directory, while CLI outputPath resolves against cwd; these operations target configured filesystem locations rather than a repository-root confinement boundary.
- HTTP imports cross a network boundary guarded by allowed_uris; redirect validation permits only HTTP(S) and rechecks the target against allowed URIs.
- Hypothesis: the inspected Node HTTP client may consume substantial memory for large or highly compressed responses because it decompresses streams, collects every chunk, and concatenates the body without a size limit visible in this function. (inferred)
- Native-backed class access depends on wrapper-specific stale-target policies and hook/loader execution windows; retained Compilation wrappers deliberately resolve to the latest native compilation after rebuild.
- Native close extends a compiler reference to a static lifetime under an explicit N-API ownership argument, waits for in-flight work to become idle, and releases compiler-scoped callback handles in finally.
- PluginDriver::new panics through expect when plugin.apply returns an error; Compiler.compile also documents that afterCompile ordering is driven from Rust, making plugin initialization and hook sequencing high-impact coupling points.
- New-cache compatibility exclusions and WASM cache-suite exclusions limit default validation; the WASM database is a no-op, so native persistence behavior must not be assumed for that target.
Extension points
Rspack offers extension seams at the CLI, configuration, compiler hooks, native plugins, module-type parsing, loaders, filesystems, and cache services. JavaScript and Rust plugin models meet through staged hook registrations. New behavior should attach to the owning lifecycle rather than bypass its boundaries. The inspected factories and registries make these integration points concrete.
- New CLI commands implement apply(cli) and join RspackCLI.registerCommands' builtin command list; asynchronous actions use wrapAction so run can await their failures.
- Configuration accepts function plugins called with the compiler as receiver and argument, or object plugins with apply(compiler); definePlugin provides typed identity helpers for both shapes.
- Rust plugins implement Plugin: Debug + Send + Sync with apply(ApplyContext), name, and clear_cache; PluginExt boxes implementations into BoxPlugin.
- PluginDriver supplies ApplyContext with compiler/compilation/factory hooks and a ModuleType-keyed parser-and-generator builder registry.
- PassExt supports run_pass, cache-aware execution, incremental artifact groups, before/after cache hooks, and is_enabled, allowing conditional compilation transformations within the shared runner.
- CompilerBuilder accepts extra plugins and independent readable, intermediate, and writable filesystem implementations; build combines configured builtin plugins with supplied plugins.
- JavaScript hook bridging partitions taps by stage ranges, skips unused hooks, and updates non-skippable registration kinds when hook usage changes.
- Compiler.get_cache exposes namespaced CacheFacade views, while HttpUriPlugin accepts a custom httpClient and configurable filesystem-backed remote cache/lockfile locations.
Contributor handoff
Use this brief as a source map for the pinned commit, then recheck the exact subsystem before editing. Tests and CI were inspected, not executed, and the bounded inventory does not establish exhaustive coverage or passing behavior. Repository conventions require building consumed artifacts before validation and reusing existing test harnesses. Cache ownership, native lifetimes, and hook ordering deserve focused attention because changes cross runtime boundaries.
- For future authorized validation, build JS changes with build:js, Rust changes with build:binding:dev, or both with build:cli:dev before running tests that consume those artifacts.
- Focused integration validation uses pnpm --dir tests/rspack-test run test -t followed by a case pattern; base, HMR, E2E, type, and Rust checks have separate documented commands.
- Add JavaScript cases beneath existing case directories and reuse runners; AGENTS.md forbids ordinary new inline/crate-local Rust tests despite the testing guide's older inline-test example.
- Before binding changes, account for both conversion directions, native-backed wrapper access windows, stale-target policies, and compiler-scoped thread-safe callback release.
- Cache edits must preserve independence from incremental recovery: cache:false cannot clear IncrementalPasses, incremental:false cannot disable cache lookup/storage, and prior compilations belong to IncrementalArtifacts.
- Scheduling edits should follow the documented preference for Rayon for synchronous CPU work and rspack_parallel for async orchestration; asset emission already uses a semaphore-limited parallel scope.
- Public behavior changes require relevant English and Chinese documentation and the PR template; compatibility policy permits documented limitations, and the support table explicitly records partial plugin support.
- Use the pinned nightly toolchain and pnpm version, and check Clone/error-handling conventions before Rust edits; inspected test scripts and CI definitions are validation instructions, not evidence that checks passed.
Languages
| Language | Files | Share of source |
|---|---|---|
| JavaScript | 13875 | 73% |
| TypeScript | 3496 | 18% |
| Rust | 1384 | 7% |
| JSON | 909 | docs/config |
| CSS | 891 | docs/config |
| Markdown | 500 | docs/config |
| TOML | 112 | 1% |
| HTML | 101 | docs/config |
Start reading here
Probable source entrypoint: Cargo.toml — inferred from the directory tree and manifest, not the upstream docs.
Source roots
crates/ (1317 files) packages/ (535 files)
Source layout — crates/
| Path | Files |
|---|---|
crates/css-module-lexer/ | 20 |
crates/node_binding/ | 8 |
crates/rspack/ | 22 |
crates/rspack_allocator/ | 2 |
crates/rspack_binding_api/ | 135 |
crates/rspack_binding_build/ | 3 |
crates/rspack_binding_builder/ | 3 |
Repository structure
| Top-level path | Files |
|---|---|
crates/ | 1317 |
tests/ | 1316 |
website/ | 569 |
packages/ | 535 |
xtask/ | 90 |
.github/ | 46 |
.agents/ | 45 |
examples/ | 18 |
Docs found: AGENTS.mdCONTRIBUTING.mdREADME.md
Package
Cargo.toml — v0.102.8, 0 declared dependencies.
CI & config entrypoints
README.md— Repository readmeAGENTS.md— Agent instructions.github/workflows/bench-rust.yml— GitHub Actions workflow.github/workflows/ci-diff.yml— GitHub Actions workflow.github/workflows/ci-resolver.yml— GitHub Actions workflow.github/workflows/ci.yml— GitHub Actions workflow.github/workflows/ecosystem-benchmark.yml— GitHub Actions workflow.github/workflows/ecosystem-ci.yml— GitHub Actions workflow.github/workflows/get-runner-labels.yml— GitHub Actions workflow.github/workflows/issue-close-require.yml— GitHub Actions workflow
Structural health signals
Average score 5.8/10 across 96 analyzed source files; 75 hotspots surfaced.
crates/rspack_plugin_esm_library/src/link.rs— 1385 lines, score 4 (Large file, Deep nesting)crates/rspack_core/src/compilation/build_chunk_graph/code_splitter.rs— 1462 lines, score 4 (Large file, Deep nesting)crates/rspack_plugin_css/src/parser_and_generator/parser.rs— 1619 lines, score 4 (Large file, Deep nesting)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
179a0934f3092026-10-01 — fix(types): allow omitting child compiler plugins (#15948)d925696de8f62026-10-01 — test: migrate persistent caching example to TypeScript (#15937)81eca8ee3a512026-09-30 — perf(sources): compact retained source storage (#15944)61dc72bca1062026-09-30 — chore: release version 2.2.8 (#15907)52c94ccffdcd2026-09-30 — fix(binding): release transient TSFN callbacks (#15938)