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]

ScreenShot

[SoonIter]

Use shiki v3 by default, drop prism support

related PR: #1672, #2046, #2122

Migrate all code highlighting from prism to shiki in compile time. It is worth noting that some code block syntax will be changed, e.g transformerNotationHighlight

before

You can only use shiki via @rspress/plugin-shiki.

import { defineConfig } from 'rspress/config';
import { pluginShiki, createTransformerLineNumber, createTransformerDiff } from '@rspress/plugin-shiki';

export default defineConfig({
  plugins: [
    pluginShiki({
      transformers: [
        createTransformerLineNumber(),
        createTransformerDiff(),
        // createTransformerErrorLevel(),
        // createTransformerHighlight(),
        // createTransformerFocus(),
      ],
    }),
  ],
});

after

use shiki by default, @rspress/plugin-shiki is needless, you can uninstall it

import { defineConfig } from 'rspress/config';
import {
  transformerNotationDiff,
} from '@shikijs/transformers';

export default defineConfig({
  markdown: {
    showLineNumber: true,
    shiki: {
        transformers: [
          transformerNotationDiff(),
          // transformerNotationErrorLevel(),
          // transformerNotationFocus(),
          // transformerNotationHighlight(),
      ],
    }
  }
});

[SoonIter]

For line-highlight breaking change

Migrate to transformerNotationHighlight (Recommended Usage)

https://shiki.style/packages/rehype#line-highlight

1. // [!code highlight] or # [!code highlight] For single-line highlight, add after the single-line comment, highlighting only the current line
2. // [!code highlight:n] For multiple-line highlight, e.g: "// [!code highlight:2]", after adding a single-line comment, highlight the bottom 2 lines

// rspress.config.ts
import { transformerNotationHighlight } from '@shikijs/transformers'

defineConfig({
  markdown: {
    shiki: {
      transformers: [transformerNotationHighlight()]
    }
  }
})

```ts
console.log('Not highlighted')
console.log('Highlighted') // [!code highlight]
console.log('Not highlighted')
```

Example 1

Before

```ts {1,3-4}
console.log('Highlighted')
console.log('Not highlighted')
console.log('Highlighted')
console.log('Highlighted')
```

After

```ts
console.log('Highlighted') // [!code highlight]
console.log('Not highlighted')
console.log('Highlighted') // [!code highlight]
console.log('Highlighted') // [!code highlight]
```

Example 2, with more lines highlighted

Before

```ts {3-6}
console.log('Not highlighted')
console.log('Not highlighted')
console.log('Highlighted')
console.log('Highlighted')
console.log('Highlighted')
console.log('Highlighted')
```

After

```ts
console.log('Not highlighted')
console.log('Not highlighted')
// [!code highlight:4]
console.log('Highlighted')
console.log('Highlighted')
console.log('Highlighted')
console.log('Highlighted')
```

Migrate to transformerCompatibleMetaHighlight

Adding transformerCompatibleMetaHighlight can be compatible with the old highlight syntax like ts {1,3}

import { defineConfig } from '@rspress/core';
import { transformerCompatibleMetaHighlight } from '@rspress/core/shiki-transformers';

export default defineConfig({
  markdown: {
     shiki: {
       transformers: [transformerCompatibleMetaHighlight()]
     }
  }
})

[SoonIter]

Remove markdown.highlightLanguages config

By default, shiki within Rspress uses lazy: true and register all languages on demand at compile time. So all languages are supported as long as they are shiki builtin languages.

If you need to use the language alias feature, you can migrate to markdown.shiki.langAlias

For example:

export default defineConfig({
  markdown: {
    shiki: {
      langAlias: {
        ejs: 'js',
        oc: 'objective-c'
      },
      langs: ['js', 'objective-c']
    },
  },
});

[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

[chenjiahan]

Related PR: #2073

[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

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 the error is in your 3rd packages in node_modules and it is hard to be fixed, you can set ssg: false:

// rspress.config.ts
export default {
  ssg: false,
};

[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.

[chenjiahan]

Drop support for Node 16

related PR: #2085

Node16 has reached EOL on September 11th, 2023, see https://nodejs.org/en/blog/announcements/nodejs16-eol

Rspress 2.0 will drop support for Node 16 and the minimum supported Node version is 18.

[chenjiahan]

#2085

[SoonIter]

Support dynamic TOC generation

related PR: #2018

It brings the application of the mdx component to a new level, ships lots of features and closes lots of issues

1. dynamic TOC generation even in user's tsx component

2. the <Badge /> and more tsx component implementation in TOC

However, it is worth noting that if your website uses custom components in the title, they may be displayed in the Aside/Toc.

e.g:

## Devtools in ios <Badge text="ios only" type="info" />

[SoonIter]

Enable dev.lazyCompilation: true by default⚡️

related PR: #2123

1. startup instantly

startup time 50x↑ faster with lazyCompilation: true

before 3.80s↓

after 0.05s↑

2. When preload meets lazyCompilation magic, a magical chemical burst out

Rspress will preload the corresponding route when hovering over the link, then a magical chemical reaction bursts out between lazyCompilation and preload, enabling a seamless refresh experience.

This behavior may encounter edge cases in some scenarios, at which point you can use the following below configuration to disable this behavior during development.

// rspress.config.ts
defineConfig({
  builderConfig: {
    dev: {
      lazyCompilation: false
    }
  }
})

[SoonIter]

Enable performance.buildCache: true by default ⚡️

related PR: #2349

enable persistent cache by default, ref: https://rspack.rs/config/experiments#persistent-cache

This means that Rspress's local startup speed will be faster .

1. rspress dev

cold start 1s↓

hot start 0.3s↑

2. rspress build

cold build 6.48s↓

hot build 3.18s↑

[SoonIter]

🔥 Removed Packages

These will be integrated by default in the @rspress/core package and will not be exposed as a public API through a package.

• rspress
• @rspress/plugin-shiki
• @rspress/plugin-auto-nav-sidebar
• @rspress/modernjs-plugin
• @rspress/plugin-container-syntax
• @rspress/plugin-last-updated
• @rspress/plugin-medium-zoom

[SoonIter]

Support Single Nav Mode by renaming the top level _meta.json to _nav.json

Related PR: #2314

If your top level does not have _nav.json, themeConfig.nav will not be generated, and your homepage will directly enter the document.

For example:

├── doc
│   ├── guide
│   │   ├── advanced
│   │   │   └── plugin.mdx
│   │   ├── _meta.json
│   │   └── index.mdx
+   ├── _meta.json
│   └── index.md
├── package.json
└── rspress.config.ts

Migration Guide

If the top-level _meta.json configure the nav bar, you can rename it to _nav.json, which will have no effect on your docsite.

├── docs-locales
│   ├── en
-   │   ├── _meta.json
+   │   ├── _nav.json
│   │   ├── guide
│   │   └── index.mdx
│   └── zh
-   │   ├── _meta.json
+   │   ├── _nav.json
│       ├── guide
│       └── index.mdx

[SoonIter]

Reimplement base config with basename feature of react-router

Related PR: #2322

If you are using const { pathname } = useLocation() together with base configuration, it should be noted that pathname will not contain base url, as the top-level BrowserRouter includes basename

[SoonIter]

Correct relative link in markdown without ./ prefix

Related PR: #2348

Markdown links without "./" prefix are now relative links, e.g: [subfolder](subfolder) equal to [subfolder](./subfolder)

Before

[](installation) and [](installation.mdx) points to /installation.html which is strange ❌

After

[](installation) and [](installation.mdx) points to /guide/api/installation.html ✅

[SoonIter]

If you update to Rspress V2, don't worry, our friend markdown.checkDeadLinks which is also refactored can help use check and find these broken links 👬🏻

It will also print the corresponding actual route, making it convenient for adjustment and modification.

[SoonIter]

Remove builderPlugins, migrate to builderConfig.plugins

related PR: #2371

We can already configure Rsbuild in builderConfig, there is another configuration that is confusing.

Migration step:

export default defineConfig({
-  builderPlugins: [
-      pluginFoo()
-  ],
+  builderConfig: {
+    plugins: [
+      pluginFoo()
+    ],
+  },
});

[SoonIter]

Expose type RspressPlugin from "@rspress/core" packge

Related PR: #2360

We don't want users to use private package like @rspress/shared, only "@rspress/core" package is all your needed. This is for rspress users to install fewer packages and avoid changes caused by package exports.

before

import type { RspressPlugin } from '@rspress/shared';

// package.json
{
  "devDependencies": {
       "rspress": "1.44.0",
       "@rspress/shared": "1.44.0"
  }
}

after

import type { RspressPlugin } from '@rspress/core';

// package.json
{
  "devDependencies": {
       "@rspress/core": "2.0.0",
  }
}

For compatibility, @rspress/shared will still export RspressPlugin type, but using @rspress/core and setting "@rspress/core" as peerDependencies will make it less likely for your plugin to encounter type errors.

For example:

{
  "name": "rspress-plugin-your-plugin",
  "peerDependencies": {
     "@rspress/core": "^2.0.0"
  }
}

[SoonIter]

FIle code block syntax support in core ```tsx file="./demo.tsx"

related PR: #2361

Users can import an external demo file as a code block.

As we support this feature in the core. This also means that the syntax external code blocks are used in plugin-preview and plugin-playground will change.

before

only using with @rspress/plugin-preview and @rspress/plugin-playground

<code src="./example.tsx" />

after

This is the syntax supported in the core package.

```tsx file="./example.tsx"
```

// example.tsx
export default () => <div>I'm a example in another file</div>

[SoonIter]

Merge rspress package to @rspress/core package

related PR: #2386

It means rspress package will be deprecated, please migrate the package name to the following package name.

rspress => @rspress/core
rspress/core => @rspress/core
rspress/config => @rspress/core
rspress/theme => @rspress/core/theme
rspress/runtime => @rspress/core/runtime
rspress/shiki-transformers => @rspress/core/shiki-transformers

before

// rspress.config.ts
import { defineConfig } from 'rspress/config';
export default defineConfig({
});

// theme/index.ts
import { usePageData, useDark } from 'rspress/runtime';
import { HomeLayout } from 'rspress/theme'

after

// rspress.config.ts
import { defineConfig } from '@rspress/core';
export default defineConfig({
});

// theme/index.ts
import { usePageData, useDark } from '@rspress/core/runtime';
import { HomeLayout } from '@rspress/core/theme'

Migration Steps from V1

You can use the search and replace feature of the IDE to search for and replace the above package name.

[SoonIter]

Enable markdown.link.checkDeadLinks by default

related PR: #2423

Rspress V2 now re-implements the dead link check feature. More information is obtained during compilation, resulting in more accurate results and more beautiful logs.

Ref: https://v2.rspress.rs/guide/basic/use-mdx/link

[SoonIter]

MDX fragments usage (ignore "_" prefix routes via route.excludeConvention)

related PR: #2149

In the docs directory, MDX fragments or React components need to be excluded from routing through the route.exclude configuration. For convenience, we agree that files starting with "_" will be excluded by default.

Ref: https://v2.rspress.rs/guide/basic/use-mdx/components