Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add rstackjs/agent-skills --skill rspress-v2-upgrade -a claude-code
Open on GitHub

What 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-code

2Manually: put the files in place

~/.claude/skills/rspress-v2-upgrade/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/rspress-v2-upgrade/

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

Similar skills

All skills for Frontend and UI →
prisma-upgrade-v7 prisma prisma-upgrade-v7 is a Claude Code skill covering the Prisma ORM v6 to v7 migration: generator, driver adapters, ESM config, and imports. Use it during upgrades or to investigate v7 errors. CX Codex +1 425,400installs metabase-modular-embedding-to-modular-embedding-sdk-upgrade metabase metabase-modular-embedding-to-modular-embedding-sdk-upgrade is a Claude Code skill that moves a React project from Metabase embed.js to the React SDK for a web components migration. CX Codex +1 385installs react19-upgrade official Awesome Copilot Community react19-upgrade is a GitHub Copilot plugin that moves React 18 projects to React 19. It starts with an upgrade request and handles code checks, dependency changes, source edits, and tests. ★ 41,430repo stars react18-upgrade official Awesome Copilot Community react18-upgrade guides React 16 and 17 projects through an upgrade to React 18.3.1, covering deprecated APIs, dependencies, class components, and tests. ★ 41,430repo stars play-billing-library-version-upgrade Google LLC play-billing-library-version-upgrade guides an Android project migration to the latest stable Google Play Billing Library. It identifies the effective starting version and lays out a direct or staged upgrade. CX Codex +1 2,300installs netsuite-suitescript-upgrade Oracle NetSuite The netsuite-suitescript-upgrade skill assesses SuiteScript 1.0, 2.0, and 2.x migrations, converts scripts to 2.1, and checks the result. Use it when updating a NetSuite codebase. CX Codex +1 910installs

From the same set21

The whole set →
migrate-to-rsbuild migrate-to-rsbuild — a skill that migrates webpack, Vite, Create React App, and Vue CLI projects to Rsbuild. It rewrites build configs and validates dev servers before cleaning up old packages. CX Codex +1 342installs rspack-tracing rspack-tracing — a skill for Claude Code and other IDEs that captures and analyzes Rspack build traces to pinpoint slow compiler phases, plugins, and loaders. Diagnose performance bottlenecks and crashes during development. CX Codex +1 291installs rspack-debugging rspack-debugging captures the crash state of native Rspack with LLDB: backtraces for segfaults, deadlocks and builds that hang. Useful when the failure sits inside Rust. CX Codex +1 282installs storybook-rsbuild The storybook-rsbuild skill sets up Storybook with Rsbuild or migrates an existing project from webpack or Vite. It also handles integrations with Rslib, Modern.js, and Rspack. CX Codex +1 212installs migrate-to-rslib migrate-to-rslib converts TypeScript library builds from tsc or tsup to Rslib with validation before cleanup. CX Codex +1 201installs rspack-split-chunks rspack-split-chunks teaches the agent to diagnose and tune optimization.splitChunks in Rspack: find duplicate modules, over-fetching, cache group issues, and oversized chunks. CX Codex +1 187installs rstest-debugging rstest-debugging diagnoses Rstest startup, build, runtime, logging, memory, and performance issues with traces and comparable measurements. CX Codex +1 133installs rslib-modern-package The rslib-modern-package skill guides agents through building or reviewing JS/TS libraries with Rslib, from package exports to release readiness. Use it for a new library or a package refresh. CX Codex +1 125installs

Project sponsors

Companies that keep this analytics open