Requirement records for Rspress v2.0.0

[Timeless0911]

This thread is used to collect planned breaking changes and notable changes for Rspress v2.0.0 in the future

[Timeless0911]

Upgrade Rspack / Rsbuild v1.0.0

Rspress v2.0.0 will upgrade the dependent @rsbuild/core to v1.0.0 which will upgrade the dependent @rspack/core to v1.0.0.

Rspack v1.0.0 contains some breaking changes, see web-infra-dev/rspack#6315 for more details.

[Timeless0911]

@rsbuild/plugin-less and @rsbuild/plugin-sass now are built-in in rspress to avoid breaking changes. May be we can remove them in 2.0.

[Timeless0911]

Upgrade React 19

Support react 19 and maintain compatibility with react 18.

[Timeless0911]

Upgrade md and mdx related dependencies

Below dependencies may be need to upgrade:

• @mdx-js/loader
• @mdx-js/mdx
• @mdx-js/react
• hast-util-from-html
• mdast-util-mdxjs-esm
• rehype-external-links
• rehype-stringify"
• remark
• remark-gfm
• remark-html
• remark-parse
• remark-rehype
• unified
• unist-util-visit
• unist-util-visit-children
• @types/mdast

[chenjiahan]

Rspress uses mdx-rs by default, can we make the mdx-js packages as peer dependencies of an optional Rspress plugin? This can greatly reduce the dependencies of Rspress core.

[Timeless0911]

Now we still need mdx-js's AST parse to do something now, and @mdx-js/react is needed which provide MDXProvider in runtime.

We should sort out the related capabilities provided by mdx-js and port same features in rust mode.

[chenjiahan]

How about the remark-related packages? can we remove them

[Timeless0911]

If so, users who enable mdxRs: false need to manually install many deps in package.json?

[Timeless0911]

Reusable theme scalability support and theme inheritance

• [Feature]: Reusable theme scalability support #901

[Timeless0911]

• [Feature]: Able to decouple the default theme (theme-default) from the project #1215

[Timeless0911]

• [Docs]: enhance docs of using slot to customize theme #1263

[Timeless0911]

components of built-in theme export

• Props are unreasonable with HomeHero component which exposed to MDX #1388

[Timeless0911]

custom layout with pageType https://vitepress.dev/reference/default-theme-layout#custom-layout

[Timeless0911]

Better AST analyze when flatten mdx content

see #1071 (comment)

[Timeless0911]

Search Enhancement

• code block and mdx components content search [Feature]: Why do searches skip code blocks？ #487 [Feature]: Support searching for code within articles #936 [Bug]: cannot search for contents inside MDX components #1065 [Feature]: Code blocks are searchable. #1543
• search weight control [Feature]: Support keywords for file to affect the search weight #942
• stable remote search API
• better distinguish the difference between remote and local search in rendering logic to avoid slow remote search causing long overall loading time of local search

[Timeless0911]

Refactor for playground and preview plugin

Maybe we can unified them or provide a better experience when used together

[Timeless0911]

• [Feature]: Support highlighting in tsx code when uses @rspress/plugin-preview #1113
• [Feature]: optimize @rspress/plugin-preview style #1315

[Timeless0911]

better preview UI

[Timeless0911]

port to mdx-rs mode

[SoonIter]

• [Feature]: The playground plugin requires iframe to isolate the style to avoid style pollution. #1394
  iframe for playground

[Timeless0911]

Support generate sitemap file in build phase

It can be implemented by a plugin.

[chenjiahan]

Try this: https://github.com/jl917/rspress-plugin-sitemap

[SoonIter]

Support _meta.{js,ts}

• feat(plugin-auto-nav): support _meta.{js,ts} #1044

[Timeless0911]

Use multicompiler to generate client and server build

• [Bug]: DEBUG=rsbuild rspress build will delete the generated rspack.config.node.js #1167

[Timeless0911]

Update flexsearch version and optimize the search UX

[Timeless0911]

Lazy compilation by default

[Timeless0911]

Fix some mdx-rs issues

https://github.com/web-infra-dev/mdx-rs/issues

[Timeless0911]

Add / Optimize more built-in components

• Add chapter location navigation bar on the page #1218
• Display in column
• TOC collection How to customize the outline display level #1460

[chenjiahan]

Add Tailwind CSS Prefix

If Rspress users want to use tailwindcss, the built-in tailwindcss of Rspress will conflict with the user's tailwindcss styles. We can add tailwindcss prefix to avoid the conflict.

https://tailwindcss.com/docs/configuration#prefix

[Timeless0911]

• [Bug]: When customizing a page using TailwindCSS, internal components encounter styling errors #1269

[SoonIter]

apiParseTool

apiParseTool of @rspress/plugin-api-docgen uses react-docgen rather than react-docgen-typescript

• [Feature]: Support react-docgen in @rspress/plugin-api-docgen #1290

[chenjiahan]

Strict SSG

Make SSG strict by default, remove the ssg.strict config and add ssg.fallback config.

see #1317 for more details.

[Timeless0911]

Container Optimize

Make details expandable to enlarge the unimportant content of the paragraph.

[Timeless0911]

• [Bug]: Container syntax inside lists or other components are not rendered #1513

[chenjiahan]

Upgrade React Router 7

https://remix.run/blog/react-router-v7

[markH5]

when @rspress/plugin-shiki is upgraded to v2.0, will upgrade shiki to the new version?

[Timeless0911]

Shiki will be the default highlighting solution in v2.0 and will be upgraded to v3.

[markH5]

Thanks

[SoonIter]

Unify all the runtime translation text in i18n.json

1. theme-default text key

2. plugin-algolia text key

3. other runtime components should can be registered in i18n.json

and it can be consumed by

const { t } = useI18n();