rspress-v2-upgrade
Skill97 starsChanged 3 months agoMITView on GitHub
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.
We split this skill into the rules it gives an agent
9 rules. About 0 are common, 5 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 11
Read package.json to identify Rspress and plugin packages in use.
- Distinctive: line 13
Check for custom theme files and MDX usage.
- Distinctive: line 16
Use the v1 → v2 guide as the source of truth:
- Very specific: line 25
Remove packages now built into @rspress/core (e.g.
- Very specific: line 30
Update import paths (rspress/runtime → @rspress/core/runtime, rspress/theme → @rspress/core/theme, @rspress/theme-default → …
- Very specific: line 31
If the project has a custom theme (in theme directory), use @rspress/core/theme-original to import the original theme components.
- Distinctive: line 32
Update the Rspress config to match v2 options and defaults.
- Distinctive: line 33
Remove deprecated or unsupported settings.
- Distinctive: line 36
Run the build and dev server.
≈ “Common” is an estimate: at least 1 in 5 of the 308,232 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Rspress v1 to v2 upgrade
Workflow
- Confirm current setup
- Read
package.jsonto 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.
- Read
- Open the official upgrade guide
- Use the v1 → v2 guide as the source of truth:
- 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.
- Update dependencies
- Replace
rspresswith@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.
- Replace
- 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
themedirectory), use@rspress/core/theme-originalto import the original theme components. - Update the Rspress config to match v2 options and defaults.
- Remove deprecated or unsupported settings.
- Update import paths (
- 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.
In this repository31 other files it gives its agents.
- AGENTS.mdAGENTS.md
- create-draft-release-notesSkill
- mdx-to-markdownSkill
- pr-creatorSkill
- release-blog-writerSkill
- rstack-docs-writerSkill
- rstack-eco-ci-debugSkill
- rstack-repo-maintainSkill
- rstack-skill-evaluatorSkill
- migrate-to-rsbuildSkill
- migrate-to-rslibSkill
- migrate-to-rslintSkill
- migrate-to-rstestSkill
- rsbuild-best-practicesSkill
- rsbuild-v2-upgradeSkill
- rsdoctor-analysisSkill
- rsdoctor-v2-upgradeSkill
- rslib-best-practicesSkill
- rslib-modern-packageSkill
- rspack-best-practicesSkill
- rspack-debuggingSkill
- rspack-split-chunksSkill
- rspack-tracingSkill
- rspack-v2-upgradeSkill
- rspress-best-practicesSkill
- rspress-custom-themeSkill
- rspress-description-generatorSkill
- rspress-docs-generatorSkill
- rstest-best-practicesSkill
- rstest-debuggingSkill
- storybook-rsbuildSkill
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
Reviews can't be read right now.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.