home / skills / rstackjs / agent-skills / rspack-v2-upgrade

rspack-v2-upgrade skill

safe

This skill helps upgrade a Rspack 1.x project to v2 by guiding dependency updates, config changes, and validation against the official migration guide.

npx playbooks add skill rstackjs/agent-skills --skill rspack-v2-upgrade

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.2 KB

---
name: rspack-v2-upgrade
description: Use when upgrading a Rspack 1.x project to v2, including dependency and configuration updates.
---

# Rspack 1.x to v2 Upgrade

## Workflow

1. **Confirm current setup**
   - Read `package.json` to identify Rspack packages in use.
   - Locate the Rspack config file (commonly `rspack.config.(ts|js|mjs|cjs)`).

2. **Open the official migration guide**
   - Use the official guide as the single source of truth:
     - https://v2.rspack.rs/guide/migration/rspack_1.x

3. **Plan required changes**
   - Compare the current project config with the migration guide.
   - List breaking changes that apply to the project’s current config and plugins.
   - Note any removed or renamed options, defaults, or plugin APIs.

4. **Update dependencies**
   - Upgrade Rspack packages to v2 (currently Beta tag): `@rspack/core`, `@rspack/cli`, `@rspack/dev-server`.

5. **Apply migration changes**
   - Update the Rspack config and related code according to the official guide.
   - Remove deprecated or unsupported options.

6. **Validate**
   - Run build and dev commands.
   - Run project tests or type checks.
   - Fix any warnings or errors surfaced by the new version.

Overview

This skill guides upgrading a Rspack 1.x project to Rspack v2, covering dependency changes and configuration updates. It consolidates the migration workflow, points to the official migration guide as the source of truth, and helps validate the result with build and test checks. Use it to reduce upgrade risk and uncover breaking changes early.

How this skill works

The skill inspects package.json and locates the project Rspack configuration file (rspack.config.(ts|js|mjs|cjs)). It compares current config and plugins against the official Rspack v2 migration notes, recommends dependency updates for @rspack/core, @rspack/cli and @rspack/dev-server, and produces a checklist of required config edits. Finally, it guides running builds, dev server, and tests to validate the migration and surface remaining issues.

When to use it

Preparing to move a project from Rspack 1.x to Rspack v2 (beta).
After discovering build or dev-server incompatibilities following a library update.
When auditing config for deprecated or renamed Rspack options and plugins.
Before upgrading dependencies in CI to avoid breaking the main branch.
When setting a migration plan for multiple repositories or a monorepo.

Best practices

Treat the official migration guide as the single source of truth and follow it step‑by‑step.
Start by reading package.json and locating rspack.config.* to scope required changes.
List and prioritize breaking changes that affect your project, then update dependencies before code edits.
Run incremental builds and tests after each change to catch regressions early.
Keep a concise changelog of removed/renamed options and plugin API adjustments for the team.

Example use cases

Upgrading a single-page app that uses custom Rspack plugins and needs config renames applied.
Migrating a component library in a monorepo where multiple packages reference @rspack/core.
Updating CI pipelines to install @rspack/core@beta and validating that builds still pass.
Converting a legacy rspack.config.ts to the v2 configuration shape and removing deprecated options.
Troubleshooting dev-server startup failures after bumping Rspack packages.

FAQ

Do I need to update all Rspack packages at once?

Update core packages together (@rspack/core, @rspack/cli, @rspack/dev-server) to match v2; staggered updates can cause incompatibilities.

Where should I look for breaking change details?

Use the official Rspack v2 migration guide as the definitive reference and compare your current config to the examples there.