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

rsbuild-v2-upgrade skill

safe

This skill guides you through upgrading a Rsbuild v1 project to v2 by updating dependencies, config, and validating builds.

npx playbooks add skill rstackjs/agent-skills --skill rsbuild-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: rsbuild-v2-upgrade
description: Use when upgrading a Rsbuild 1.x project to v2, including dependency and configuration updates.
---

# Rsbuild v1 to v2 Upgrade

## Workflow

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

2. **Open the official upgrade guide**
   - Use the v1 → v2 guide as the source of truth:
     - https://v2.rsbuild.rs/guide/upgrade/v1-to-v2

3. **Plan the upgrade path**
   - 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**
   - Bump `@rsbuild/core` to v2 (currently Beta tag).
   - Bump Rsbuild plugins to latest versions via `npx taze major --include /rsbuild/ -w -r`

5. **Apply config and code changes**
   - Update the Rsbuild config to match v2 options and defaults.
   - Remove deprecated or unsupported settings.

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

Overview

This skill helps upgrade a Rsbuild 1.x project to Rsbuild v2 by guiding dependency updates, configuration changes, and validation steps. It packages a pragmatic checklist and commands to minimize downtime and surface-breaking changes early. Use it to plan, execute, and verify a safe migration to Rsbuild v2.

How this skill works

The skill inspects package.json and the project Rsbuild config file to identify current Rsbuild core and plugin versions. It references the official v1→v2 upgrade guide as the source of truth, produces a list of breaking changes that apply, and recommends dependency bumps and configuration edits. Finally, it runs validation steps: build, dev, and tests to catch regressions and missing API updates.

When to use it

You maintain a project that currently uses Rsbuild 1.x and want to migrate to v2.
You need a repeatable checklist to update Rsbuild core and plugins safely.
Preparing a repo for newer plugin APIs or renamed/removed config options.
Before upgrading CI pipelines to ensure builds and tests pass with v2.

Best practices

Start by reading the official v1→v2 upgrade guide and treat it as authoritative.
Audit package.json and locate the Rsbuild config file before making changes.
List project-specific breaking changes and update config incrementally.
Bump @rsbuild/core to v2 and update plugins with a controlled command like npx taze major --include /rsbuild/ -w -r.
Run builds, dev servers, and tests after each change to catch issues early.

Example use cases

Upgrading a web app using Rsbuild plugins that changed option names in v2.
Migrating a monorepo where multiple packages reference Rsbuild core or shared plugins.
Updating CI to use Rsbuild v2 artifacts and confirming dev servers still run.
Fixing type-check or runtime errors introduced by removed or renamed plugin APIs.

FAQ

What files should I inspect first?

Open package.json to find Rsbuild core and plugin versions and locate the Rsbuild config file (rsbuild.config.ts/js/mjs/cjs).

How do I update Rsbuild plugins safely?

Use a controlled update command such as npx taze major --include /rsbuild/ -w -r, then test builds and dev servers incrementally.