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

rspress-v2-upgrade skill

This skill guides upgrading rspress from v1 to v2 by updating configs, dependencies, and themes per the official migration guide.

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

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

Files (1)

SKILL.md

2.0 KB

---
name: rspress-v2-upgrade
description: Migrate Rspress projects from v1 to v2. Use when a user asks to upgrade Rspress, follow the v1-to-v2 guide, update configs/themes, or validate the upgrade.
---

# Rspress v1 to v2 Upgrade

## Workflow

1. **Confirm current setup**
   - Read `package.json` to identify Rspress and plugin packages in use.
   - Locate the Rspress config file (commonly `rspress.config.(ts|js|mjs|cjs)`).
   - Check for custom theme files and MDX usage.

2. **Open the official upgrade guide**
   - Use the v1 → v2 guide as the source of truth:
     - <https://rspress.rs/guide/migration/rspress-1-x>

3. **Plan the upgrade path**
   - List breaking changes that apply to the project's current config, plugins, and theme.
   - Note any removed or renamed packages, options, and APIs.

4. **Update dependencies**
   - Replace `rspress` with `@rspress/core@^2.0.0`.
   - Remove packages now built into `@rspress/core` (e.g. `rspress`, `@rspress/plugin-shiki`, `@rspress/plugin-auto-nav-sidebar`, `@rspress/plugin-container-syntax`, `@rspress/plugin-last-updated`, `@rspress/plugin-medium-zoom`, `@rspress/theme-default`, `@rspress/runtime`).
   - Bump remaining Rspress plugins to latest versions via `npx taze major --include /rspress/ -w -r`.
   - Ensure Node.js >= 20.9.0.

5. **Apply config and code changes**
   - Update import paths (`rspress/runtime` → `@rspress/core/runtime`, `rspress/theme` → `@rspress/core/theme`, `@rspress/theme-default` → `@rspress/core/theme-original`).
   - If the project has a custom theme (in `theme` directory), use `@rspress/core/theme-original` to import the original theme components.
   - Update the Rspress config to match v2 options and defaults.
   - Remove deprecated or unsupported settings.

6. **Validate**
   - Run the build and dev server.
   - Fix any warnings or errors that appear in the new version. If errors or warnings occur, please refer to the [Official Upgrade Guide](https://rspress.rs/guide/migration/rspress-1-x) and first check if it's caused by any omitted or incomplete migration steps.

Overview

This skill migrates Rspress projects from v1 to v2. It automates the upgrade checklist, updates dependencies and import paths, adjusts config and theme references, and validates the resulting build. Use it to follow the official v1→v2 guide and reduce manual mistakes during migration.

How this skill works

The skill inspects package.json, detects Rspress packages and plugins, and locates the project Rspress config and theme files. It compares installed items against known breaking changes from the v1→v2 guide, prescribes dependency changes, and outlines code/config edits for imports and options. Finally, it runs validation steps and surfaces errors or warnings with remediation pointers.

When to use it

You have a project using Rspress v1 and want to upgrade to v2.
You need a checklist that maps your current config, plugins, and theme to v2 equivalents.
You want automated guidance for dependency changes and import path updates.
You must validate the migration by running build and dev server checks.
You need to identify breaking changes that affect your custom theme or MDX usage.

Best practices

Back up the repository or create a feature branch before making changes.
Open the official v1→v2 upgrade guide as the authoritative reference.
Ensure Node.js is at least 20.9.0 before upgrading dependencies.
Replace deprecated packages with @rspress/core@^2.0.0 and remove built‑ins now included in core.
Run the dev server and fix warnings progressively; address errors using the upgrade guide.

Example use cases

Upgrade a documentation site that uses Rspress v1 and a custom theme directory.
Migrate a project that uses multiple Rspress plugins and needs dependency pruning.
Validate that a v1 config file requires option changes to match v2 defaults.
Replace old import paths (runtime/theme) with @rspress/core equivalents across the codebase.

FAQ

Which packages must be replaced or removed?

Replace rspress with @rspress/core@^2.0.0. Remove packages now built into core such as @rspress/plugin-shiki, plugin-auto-nav-sidebar, plugin-container-syntax, plugin-last-updated, plugin-medium-zoom, @rspress/theme-default, and @rspress/runtime.

What import path changes are required?

Update imports like rspress/runtime → @rspress/core/runtime, rspress/theme → @rspress/core/theme, and @rspress/theme-default → @rspress/core/theme-original. Custom themes should import components from @rspress/core/theme-original if needed.