feat(theme)!: custom theme should use @rspress/core/theme-original#2860
feat(theme)!: custom theme should use @rspress/core/theme-original#2860
@rspress/core/theme-original#2860Conversation
✅ Deploy Preview for rspress-v2 ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Rsdoctor Bundle Diff Analysis📁 webPath:
📦 Download Diff Report: web Bundle Diff Generated by Rsdoctor GitHub Action |
There was a problem hiding this comment.
Pull request overview
This PR standardizes the theme import pattern in Rspress to align with Docusaurus conventions, introducing a clear distinction between @rspress/core/theme (user's custom theme with fallback to default) and @rspress/core/theme-original (always points to Rspress's default theme).
Key Changes:
- Introduces
@rspress/core/theme-originalalias for accessing the default theme from custom theme files - Refactors icon imports from
@theme-assets/*pattern to named exports from the theme package - Updates all documentation and examples to use the new import patterns
- Adds plugin support for custom theme directories via
themeDirhook
Reviewed changes
Copilot reviewed 37 out of 38 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| website/theme/index.tsx | Updated to import from @rspress/core/theme-original instead of @rspress/core/theme |
| website/docs/zh/ui/custom-theme.mdx | Updated Chinese documentation with new import patterns |
| website/docs/en/ui/custom-theme.mdx | Updated English documentation with new import patterns |
| website/docs/zh/fragments/builtin-components.mdx | Replaced @theme-assets imports with exported icon components |
| website/docs/en/fragments/builtin-components.mdx | Replaced @theme-assets imports with exported icon components |
| packages/shared/src/types/index.ts | Updated comment for themeDir config property |
| packages/shared/src/types/Plugin.ts | Added themeDir plugin hook definition |
| packages/core/src/theme/index.ts | Added icon exports and cleaned up comment formatting |
| packages/core/src/theme/icons.ts | New file exporting all theme icons as named exports |
| packages/core/src/theme/env.d.ts | Removed @theme-assets/* module declaration |
| packages/core/src/theme/components/*.tsx | Refactored all components to use named icon imports instead of @theme-assets |
| packages/core/src/node/utils/detectCustomIcon.ts | Removed deprecated custom icon detection utility |
| packages/core/src/node/logger/hint.ts | Updated breaking change detection and migration hints |
| packages/core/src/node/initRsbuild.ts | Updated alias configuration to support new theme import patterns |
| packages/core/src/node/PluginDriver.ts | Added themeDir method to support plugin-provided themes |
| packages/core/package.json | Added ./theme-original export path |
| e2e/fixtures//theme/.tsx | Updated test fixtures to use new import patterns |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Summary
For
@rspress/core/theme-originalor@theme-originalBefore
but
@themeis an alias which points totheme/index.tsxand falls back torspress/themerspress/themeor@rspress/core/themepoints to Rspress'stheme-default, they are actually different things.After
We standardize this behavior, which is the same as docusaurus.
In
docsdirectory,@themeor@rspress/core/themeshould be used, which points totheme/index.tsxand falls back totheme-defaultIn
themedirectory ,@theme-originalor@rspress/core/theme-originalshould be used, which always points to Rspress'stheme-defaultFor
@theme-assetsBefore
We have a separate entry for exporting @theme-assets
After
@theme-assetshas been removed. Icons are exported from@themeand prefixed withIcon, for example:IconSearchRelated Issue
Checklist