rspress-v2-upgrade — Claude Code skill for v1-to-v2 migration
The rspress-v2-upgrade skill automates upgrading an Rspress project from v1 to v2. It reads the config, updates dependencies, rewrites import paths, and validates the build against the official migration guide.
MIT 150 installs ★ 100 updated 2026-10-22
npx skills add rstackjs/agent-skills --skill rspress-v2-upgrade -a claude-codeWhat rspress-v2-upgrade does
The skill runs through a migration checklist: inspects package.json and the Rspress config file, swaps rspress for @rspress/core@^2.0.0, removes packages now bundled into v2 (like @rspress/plugin-shiki, @rspress/plugin-auto-nav-sidebar), and fixes import paths (rspress/runtime → @rspress/core/runtime, @rspress/theme-default → @rspress/core/theme-original). If the project uses a custom theme, the skill suggests importing base components from @rspress/core/theme-original.
Next, it updates config options for v2, runs the build and dev server, and catches any errors. Node.js >= 20.9.0 is required—the upgrade will not proceed without it. When issues arise, the skill points to the [official migration guide](https://rspress.rs/guide/migration/rspress-1-x) and asks you to verify that no steps were skipped.
What it helps with
- upgrade Rspress from v1 to v2 in an existing project
- replace old import paths with new ones throughout the codebase
- remove packages now built into @rspress/core
- rewrite the config for v2 compatibility
- validate the build and dev server after migration
Example prompts for the agent
- Help me upgrade our Rspress project from v1 to v2
- I'm migrating to Rspress v2—what changes do I need to make in the config?
- Which packages should I remove when moving to rspress v2?
How to install rspress-v2-upgrade
1Skills CLI (Vercel)
npx skills add rstackjs/agent-skills --skill rspress-v2-upgrade -a claude-code2Manually: put the files in place
~/.claude/skills/rspress-v2-upgrade/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/rspress-v2-upgrade/
1Skills CLI (Vercel)
npx skills add rstackjs/agent-skills --skill rspress-v2-upgrade -a codex2Manually: put the files in place
.agents/skills/rspress-v2-upgrade/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add rstackjs/agent-skills --skill rspress-v2-upgrade -a cursor2Manually: put the files in place
.cursor/skills/rspress-v2-upgrade/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install rstackjs/agent-skills skills/rspress-v2-upgrade2Manually: put the files in place
.github/skills/rspress-v2-upgrade/SKILL.md1Skills CLI (Vercel)
npx skills add rstackjs/agent-skills --skill rspress-v2-upgrade -a gemini-cli2Platform CLI
gemini skills install https://github.com/rstackjs/agent-skills --path skills/rspress-v2-upgradeManually: put the files in place
.devin/skills/rspress-v2-upgrade/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add rstackjs/agent-skills --skill rspress-v2-upgrade -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about rspress-v2-upgrade
How do I install rspress-v2-upgrade in Claude Code?
Run npx skills add rstackjs/agent-skills --skill rspress-v2-upgrade -a claude-code, then open ~/.claude/skills/rspress-v2-upgrade/SKILL.md.
What does rspress-v2-upgrade do?
The skill automates migrating an Rspress project from v1 to v2 by updating dependencies, rewriting imports, converting the config, and validating the result.
What Node.js version is required for v2?
Node.js >= 20.9.0 is required. If your version is lower, the upgrade will not work.
Source text
SKILL.md · MIT
---
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.
© rstackjs · MIT · rstackjs/agent-skills