next-rspack

# Next.js with Rspack ## When to Use Use this skill when you need to: - Upgrade `@rspack/core` npm package version - Upgrade rspack crate dependency versions - Upgrade Rust version in `rspack/rust-toolchain.toml` (rspack directory only) - Fix Rspack-related compilation issues - Develop Rspack-specific features in Next.js > **⚠️ Scope Limitation**: This skill only applies to code and configuration under the `rspack/` directory. The `rust-toolchain.toml` in the repository root is for Turbopack and is outside the scope of this skill. ## Architecture Overview ### Package Structure ``` rspack/ # Independent workspace (separate rust toolchain and npm releases) ├── Cargo.toml # Rust workspace configuration ├── rust-toolchain.toml # Rust version configuration ├── package.json # @next/rspack-core package definition ├── lib/ │ ├── index.js # Exports @rspack/core + custom plugins │ └── index.d.ts # Type definitions └── crates/ └── binding/ ├── Cargo.toml # Rust crate dependencies (rspack_* crates) └── package.json # @next/rspack-binding package definition packages/ └── next-rspack/ └── package.json # References @next/rspack-core ``` ### Dependency Graph ``` packages/next-rspack └── @next/rspack-core (rspack/package.json) ├── @rspack/core (npm dependency) └── @next/rspack-binding (rspack/crates/binding) └── rspack_* crates (Cargo.toml dependencies) ``` ### Version Mapping Rules | @rspack/core npm version | rspack crate version | Notes | | ------------------------ | -------------------- | ------------------------------------------------- | | `2.0.0-rc.0` | `0.100.0-rc.0` | npm major.minor maps to crate 0.(major\*50+minor) | | `1.3.x` | `0.53.x` | e.g., 1.3 → 0.53 | | `1.2.x` | `0.52.x` | e.g., 1.2 → 0.52 | ## Upgrade Process ### Step 1: Get Upstream Version Information Query https://github.com/web-infra-dev/rspack to obtain: - Target `@rspack/core` npm version - Corresponding rspack crate version - Rust channel version from `rust-toolchain.toml` ### Step 2: Update npm Dependencies Edit `rspack/package.json`: ```json { "dependencies": { "@rspack/core": "<new version>", "@next/rspack-binding": "workspace:*" } } ``` ### Step 3: Update Cargo.toml Edit `rspack/crates/binding/Cargo.toml`, update all rspack crate versions: ```toml [dependencies] rspack_binding_builder = { version = "=<new crate version>" } rspack_binding_builder_macros = { version = "=<new crate version>" } rspack_core = { version = "=<new crate version>" } rspack_error = { version = "=<new crate version>" } rspack_hook = { version = "=<new crate version>" } rspack_plugin_externals = { version = "=<new crate version>" } rspack_regex = { version = "=<new crate version>" } # rspack_sources version is managed separately, may not follow the main version [target.'cfg(...)'.dependencies] rspack_binding_builder = { version = "=<new crate version>", features = ["plugin"] } [build-dependencies] rspack_binding_build = { version = "=<new crate version>" } ``` ### Step 4: Update Rust Toolchain Edit `rspack/rust-toolchain.toml`: ```toml [toolchain] profile = "default" components = ["rust-src"] channel = "<nightly version matching upstream rspack>" ``` ### Step 5: Verify Build ```bash # Execute in rspack directory cd rspack # Check Rust code cargo check # Build binding (requires Rust installed) pnpm build ``` ### Step 6: Link to packages/next-rspack `rspack/` is an independent workspace not included in the root pnpm-workspace, manual linking is required: ```bash # Execute from repository root cd packages/next-rspack # Link locally built @next/rspack-core pnpm link ../../rspack ``` Or modify `packages/next-rspack/package.json` to use local path (for local testing only, do not commit): ```json { "dependencies": { "@next/rspack-core": "link:../../rspack" } } ``` > **Important**: After linking, run `pnpm install` in the root directory to update dependency relationships. ### Step 7: Run Tests ```bash # Execute from repository root pnpm test-rspack ``` ## Key Files Checklist Files to check/modify during upgrade: | File Path | Modification | | ------------------------------------ | ------------------------------------------------------------------------------------- | | `rspack/package.json` | `@rspack/core` version, package version | | `rspack/crates/binding/Cargo.toml` | rspack\_\* crate versions | | `rspack/crates/binding/package.json` | binding package version | | `rspack/rust-toolchain.toml` | Rust nightly version | | `packages/next-rspack/package.json` | `@next/rspack-core` version reference (update on release, use link for local testing) | ## Pre-requisites for Local Testing Before running `pnpm test-rspack`, you must build and link `@next/rspack-core`: ```bash # 1. Build @next/rspack-core cd rspack pnpm install pnpm build # 2. Link to packages/next-rspack cd ../packages/next-rspack pnpm link ../../rspack # 3. Return to root and update dependencies cd ../.. pnpm install # 4. Run tests pnpm test-rspack ``` > **Note**: After modifying Rust code under `rspack/`, you need to re-run `pnpm build` from step 1. ## Test Commands ```bash # Full test suite (using Rspack compiler) pnpm test-rspack # Development mode tests pnpm test-dev-rspack # Production mode tests pnpm test-start-rspack # Run specific tests only pnpm run with-rspack pnpm testonly -- <test-pattern> ``` All test commands set environment variables via `with-rspack`: ```bash cross-env NEXT_RSPACK=1 NEXT_TEST_USE_RSPACK=1 ``` ## Development Notes ### Environment Variable Differentiation Use the `NEXT_RSPACK` environment variable to differentiate compilers in `packages/next/` code: ```typescript // Check if using Rspack const isRspack = Boolean(process.env.NEXT_RSPACK) if (process.env.NEXT_RSPACK) { // Rspack-specific logic } else { // Webpack logic } ``` ### Common Code Locations - Compiler selection logic: `packages/next/src/lib/bundler.ts` - Webpack configuration: `packages/next/src/build/webpack-config.ts` - Loader adaptations: `packages/next/src/build/webpack/loaders/` ### Custom Plugins `@next/rspack-core` exports = `@rspack/core` + custom plugins: - `NextExternalsPlugin` - externals handling plugin implemented in Rust ## Release Process Release via GitHub Actions workflow: - Workflow: `.github/workflows/release-next-rspack.yml` - Supports dry-run mode - Supports multiple npm tags (latest, alpha, beta, canary) ## References - Upstream Rspack repository: https://github.com/web-infra-dev/rspack - Rspack documentation: https://rspack.rs - Next.js with Rspack example: `examples/with-rspack/`