Breaking changes in Rspress v2.0.0

[Timeless0911]

Rsbuild v2.0.0 is under active development.

This thread is used to collect planned breaking changes for Rspress v2.0.0.

[SoonIter]

Custom themes require named exports

related PR: #1873

If you want to customize theme, please use named export as below:

before

Layout HomeLayout setup DocLayout use default export,

other components use named export

import Theme from 'rspress/theme';

const Layout = () => <Theme.Layout beforeNavTitle={<div>some content</div>} />;

export default {
  ...Theme,
  Layout,
};

export * from 'rspress/theme';

after

all the components use named export

import { Layout as BasicLayout } from 'rspress/theme';

const Layout = () => <BasicLayout beforeNavTitle={<div>some content</div>} />;

// use named export, no need to `export default`
export { Layout };

export * from 'rspress/theme';

[SoonIter]

https://github.com/web-infra-dev/rspress/releases/tag/v2.0.0-alpha.0

[SoonIter]

Upgrade shiki v3 and use shiki transformers

related PR: #1672

import { defineConfig } from 'rspress/config';
import { pluginShiki, createTransformerDiff } from '@rspress/plugin-shiki';
+import {
+ transformerNotationDiff,
+  transformerNotationErrorLevel,
+  transformerNotationFocus,
+  transformerNotationHighlight,
+} from '@shikijs/transformers';

export default defineConfig({
  plugins: [
    pluginShiki({
      transformers: [
-        createTransformerDiff(),
-      // createTransformerLineNumber(),
-       // createTransformerErrorLevel(),
-       // createTransformerHighlight(),
-       // createTransformerFocus(),
+       createTransformerLineNumber(),
+       // transformerNotationDiff(),
+       // transformerNotationErrorLevel(),
+       // transformerNotationHighlight(),
+       // transformerNotationFocus(),
      ],
    }),
  ],
});

[SoonIter]

WIP: prism -> shiki

[chenjiahan]

Builtin Sass and Less plugins removed

Rspress 2.0 no longer has Rsbuild's Less and Sass plugins built into it. You can manually install and register plugins to support Sass and Less.

• Sass:

// rspress.config.ts
import { defineConfig } from 'rspress/config';
import { pluginSass } from '@rsbuild/plugin-sass';

export default defineConfig({
  builderPlugins: [pluginSass()],
});

• Less:

// rspress.config.ts
import { defineConfig } from 'rspress/config';
import { pluginLess } from '@rsbuild/plugin-less';

export default defineConfig({
  builderPlugins: [pluginLess()],
});

#1937

[chenjiahan]

React 19

Rspress 2.0 uses React 19 by default, and the minimum supported React version is 18, which means React 17 will no longer be supported.

[markH5]

Is it expected that React 19 will be derived from rspress? I don't want to have 2 React 19 at runtime. 😀

[chenjiahan]

Rspress sets aliases for React packages by default to ensure that only one copy of React is bundled.

See:

rspress/packages/core/src/node/utils/detectReactVersion.ts

Line 30 in 5dca98b

export async function resolveReactAlias(reactVersion: number, isSSR: boolean) {

[markH5]

thank you

[SoonIter]

enable search.codeBlocks by default

related PR: #1952

This means that the search will include more information of code example, most of which is useful, but there may also be some noise.

[SoonIter]

Add tailwind prefix to @rspress/theme-default for CSS isolation

related PR: #1990

This means you can control the integration of unocss or tailwindcss on your own, and it will not cause any conflict now.

If you depend on Rspress' existing CSS class names such as dark:hidden, please configure Tailwind in the project.

[chenjiahan]

It this a breaking change?

[Timeless0911]

For people who rely on /index to analyze some URLs, it should be a breaking change?

[chenjiahan]

I tend to ignore trivial breaking, as the chances of it affecting users are small.

[Timeless0911]

We can hide it in this thread.

[SoonIter]

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

related PR: #2015

#1105 (comment)

Rspress will not fallback to csr, if ssg failed, the process exit and the user need to investigate why it failed

if you want to go back to the old behavior, please set below

export default {
  ssg: {
    fallback: 'csr',
  },
};

[SoonIter]

Update unified@11 and mdx related pkgs

related PR: #2017

If you are using your own rehype or remark plugin in Rspress, you also need to upgrade to a version compatible with unified@11.