mcpField
R
rspress-v2-upgrade

rspress-v2-upgrade

github.com/rstackjsDevelopment97144 installsUpdated 6d ago
Repository

About rspress-v2-upgrade

A skill for upgrading Rspress projects from v1 to v2. It guides developers through dependency, configuration, and theme changes, then validates the migration with a build and dev server.

Key features

  1. 01Inspect Rspress packages and project configuration
  2. 02Identify applicable breaking changes
  3. 03Update dependencies and import paths
  4. 04Validate with build and dev server

Use cases

  1. 01Plan a v1-to-v2 migration
  2. 02Update a project with a custom theme
  3. 03Check an upgrade for migration errors

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/rstackjs/agent-skills --skill rspress-v2-upgrade

After installing, type/rspress-v2-upgradein Claude Code to confirm it loaded.

Details

From the project README

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

  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 and first check if it's caused by any omitted or incomplete migration steps.

Comments

Markdown supported