Rspack is a high-performance JavaScript bundler written in Rust that offers strong compatibility with the webpack ecosystem.

• Monorepo with Rust crates (crates/) and JavaScript packages (packages/)
• See Project Architecture for details

• Synchronous concurrency: Prefer rayon for CPU-bound parallel work and data-parallel iteration
• Asynchronous concurrency: Prefer the abstractions provided by rspack_parallel instead of using raw tokio task orchestration directly
• Thread pool boundaries: Avoid mixing rayon and tokio thread pools for the same workflow unless there is a clear boundary that cannot be avoided
• Rule of thumb: Do not use tokio to parallelize synchronous CPU-heavy work, and do not introduce rayon inside async orchestration that should stay within rspack_parallel

• Rust: Latest stable (via rustup)
• Node.js: Latest LTS
• pnpm: Version in package.json
• Run pnpm run setup to install and build

• pnpm run build:js - Build JavaScript/TypeScript packages
• pnpm run build:binding:dev - Build Rust crates (dev)
• pnpm run build:cli:dev - Full build (dev)
• pnpm run build:binding:debug - Debug build
• pnpm run build:binding:release - Release build
• pnpm run build:cli:dev:wasm - WASM build
• pnpm run build:cli:dev:browser - Browser build

• pnpm run test:rs - Rust unit tests
• pnpm run test:unit - JavaScript unit tests
• pnpm run test:e2e - E2E tests
• pnpm run test:base - Integration tests (in tests/rspack-test)
• pnpm run test:hot - HMR tests
• cd tests/rspack-test && pnpm run test -t "configCases/asset" - Run filtered tests

Before running tests after code changes:

• If you modified JavaScript/TypeScript code, run pnpm run build:js first
• If you modified Rust code, run pnpm run build:binding:dev first
• If your change spans both JS and Rust, run pnpm run build:cli:dev first

• VS Code: .vscode/launch.json with Debug Rspack and Attach options
• Rust: Set breakpoints, use Debug Rspack or Attach Rust
• JavaScript: Use --inspect flag, attach with Attach JavaScript
• rust-lldb: rust-lldb -- node /path/to/rspack build for panic debugging

• Linting: pnpm run lint:js (Rslint), pnpm run lint:rs (cargo check), cargo lint (Rust)
• Formatting: pnpm run format:rs (cargo fmt), pnpm run format:js (prettier), pnpm run format:toml (taplo), cargo fmt --all --check (Rust)
• Style: snake_case for Rust, camelCase for JS/TS

1. Create feature branch from main
2. Implement in appropriate crate/package
3. Add tests (Rust unit tests, JS integration tests)
4. Update docs if APIs change
5. Run linters and tests: pnpm run lint:js && pnpm run lint:rs && cargo lint && pnpm run test:unit && pnpm run test:rs
6. Format: pnpm run format:rs && pnpm run format:js
7. Create PR

• Rust: Core in crates/rspack_core/, plugins in crates/rspack_plugin_*/, rebuild with pnpm run build:binding:dev, test with pnpm run test:rs, avoid linting and formatting for fast local development
• JS/TS: API in packages/rspack/src/, CLI in packages/rspack-cli/src/, rebuild with pnpm run build:js, test with pnpm run test:unit

• Rust: Add #[test] functions in same file or tests/ directory
• JavaScript: Add cases in tests/rspack-test/{type}Cases/ (Normal, Config, Hot, Watch, StatsOutput, StatsAPI, Diagnostic, Hash, Compiler, Defaults, Error, Hook, TreeShaking, Builtin)

• Package manager: pnpm (workspaces for monorepo)
• Rust: Cargo.toml in each crate
• JavaScript: package.json files
• Version check: pnpm run check-dependency-version

• Benchmarks: tests/bench/, run with pnpm run bench:ci (setup: pnpm run bench:prepare)
• Profiling: pnpm run build:binding:profiling
• Tracing: See crates/rspack_tracing/

• Site: website/ directory
• Docs: website/docs/en/ (English), website/docs/zh/ (Chinese)
• API: website/docs/en/api/

• Template: Use .github/PULL_REQUEST_TEMPLATE.md
• Title prefix: test:, fix:, feat:, refactor:, chore:
• Semver alignment:
  • fix: -> PATCH bump
  • feat: -> MINOR bump
  • Any breaking change -> MAJOR bump (type(scope)!: and/or BREAKING CHANGE: in commit body)
• CI: All checks must pass

• Follow existing code patterns
• Add tests for new features
• Update docs when APIs change
• Run linters before submitting
• Use Conventional Commits in semver style: type(scope): subject
• Prefer these types for release impact: fix, feat; use ! or BREAKING CHANGE: only for incompatible changes
• Keep PRs focused (one feature/fix per PR)

• Rust core: crates/rspack_core/
• Plugins: crates/rspack_plugin_*/
• JavaScript API: packages/rspack/src/
• CLI: packages/rspack-cli/src/
• Tests: tests/rspack-test/

• Use rspack_error crate for Rust errors
• Provide clear, actionable error messages
• Include context (file paths, line numbers)

This project includes comprehensive documentation designed for AI assistants and large language models. All AI-friendly documentation is located in the .agents/ directory:

• Architecture Guide - High-level architecture overview, core components, compilation pipeline, and system design
• API Design - API design principles, patterns, versioning strategy, and compatibility guidelines
• Code Style - Coding standards and conventions for Rust and TypeScript/JavaScript
• Common Patterns - Common code patterns, templates, and best practices for plugin/loader development
• Glossary - Comprehensive glossary of terms and concepts used throughout the codebase
• Skills - Required skills and knowledge areas for contributing to Rspack

These documents provide detailed context about the project structure, coding standards, common patterns, and domain-specific knowledge to help AI assistants better understand and contribute to the codebase.

• Project Architecture
• Testing Guide
• Debugging Guide
• API Docs