Rspress, the Rspack-based static site generator

[sanyuan0704]

GitHub Repo: https://github.com/web-infra-dev/rspress

中文版本：#6

Today, we are pleased to announce the official release of Rspress 1.0!

Framework Position

Rspress is a static site generator incubated by the ByteDance Web Infra team. It is built using Rspack, rendered based on the React framework, supports MDX content development, and focuses on high performance, ease of use, and flexible customization.

Rspress has a set of default document themes. You can use Rspress to quickly build a document site, and you can also customize the theme to meet your personalized static site needs, such as blog sites, product homepages, etc.

Of course, you can also access the corresponding plugins provided by the official to easily build component library documents.

Background

The original form of Rspress was to provide documentation tools within the Web Infra team. In the past, when maintaining some slightly more complex documentation projects, we built the capabilities of Rspress itself around the following directions:

• Build performance. Ensure fast startup speed and bring good development experience.
• MDX support. With MDX, we can easily reuse document fragments and render custom React components in documents.
• Basic capabilities of Document Site. Including i18n, multi-version support, full-text search, component library documents, etc.
• Extensibility. Built-in plugin system supports extending framework functionality through plugin API.

Build Performance

As the project becomes larger and larger, team members often suffer from lengthy project start-up times, which have a negative impact on the development experience. The longer the project development time, the more obvious the deterioration of this experience.

We can't help but start thinking. Can we break through the limitations of the current community toolchain, break through the performance bottleneck of the existing SSG framework, and achieve the instant startup effect of most scenarios?

Then, we continued to explore in this direction and finally achieved this effect on Rspress. Taking the content of the Rspress official website documentation as an example, the performance comparison of Rspress, Docusaurus, and Nextra is as follows:

If we only talk about one core optimization method, it is undoubtedly the Rust front-end toolchain. We mainly use the Rust toolchain in two performance-sensitive parts.

• Front-end Bundler. Traditional Bundlers include webpack, Rollup, etc. For a front-end project, bundler is the integration hub of various compile toolchains, which is a very critical engineering capability and has a huge impact on project construction performance. Rspress uses the team's self-developed Rspack, which is a Rust-based Bundler with multiple performance optimization methods built in, such as multi-threaded parallel compile, incremental compile, etc. Compared with traditional packaging tools in the community, it has a performance improvement of 5-10 times.
• Markdown Compiler. For another major compile performance bottleneck in SSG framework, Markdown compile, we have also rusted this process to further speed up and customize the Markdown compiler for Rspress (i.e. @rspress/mdx-rs). This compiler has nearly 20 times performance improvement compared to the JS version compiler in the community.

MDX Support

In order to ensure the flexibility of content development, Rspress has chosen to support the content format MDX.

Because MDX actually represents a component-based content organization, on the one hand, documents are components, so we can use document fragments between different documents. On the other hand, any custom React components can be introduced in the document, which greatly releases the imagination of document development.

Document Basic Capabilities

Of course, Rspress has also done a lot of work in polishing the basic capabilities of the document site, supporting the following functional features:

• Automatically generate layouts, including navigation bar, left sidebar, etc.
• Static site generation, HTML output directly after project build.
• I18n, support documents in different languages.
• Full-text search, providing search function for out of the box.
• Multi-version document management.
• Customize theme.
• Automatically generate component demo preview or playground.

Extensibility

Rspress has designed multiple extension mechanisms internally to ensure strong customization capabilities, including:

• Support custom global components, global styles, and page layout structure. View details
• Support build capability extension, including Rspack configuration, adding MDX compile plugin, etc. View details
• Support custom themes. View details
• Built-in plugin system, supports custom plugins. View details

In order to allow more people to participate in such interesting things, we have opened up the source code of Rspress and welcome everyone to participate in the construction together.

Quick start

You can easily start a Rspress project with the following command:

# npm
npm create rspress@latest
# yarn
yarn create rspress@latest
# pnpm
pnpm create rspress@latest
# bun
bun create rspress@latest

Then execute npm run dev to start the project.

For details, please refer to the "Quick Start" document on the official website: https://rspress.dev/guide/start/getting-started.html.

Features

Next, we will introduce the main functional features of Rspress.

Auto Layout Generation

For the construction of a document website, in addition to displaying the body content, we generally need the following layout modules:

• Navigation bar, used to provide global navigation entry.
• Sidebar, used to display the article table of contents under the current navigation.
• Article outline column, used to display the outline structure of the current page.

For article outline, Rspress will automatically extract the headings of each level in the document, generate outline information, and display it on the right side of the article page by default. You don't need to do anything else.

For the navigation bar and sidebar, we provide two configuration methods. You can choose one to configure:

• Declarative configuration. Configure the corresponding data by declaring _meta.json in the directory, for example:

// docs/guide/_meta.json
['introduction', 'install', 'start']

Configuration design follows Occam's razor rule, avoiding unnecessary config structure as much as possible, and describing the intention with the simplest structure. For the details of _meta.json you can read the "Auto Nav/Sidebar" documentation.

• Programmatic configuration. This is achieved by specifying the nav and sidebar config items in the Rspress config file. The details can be found in the "API documentation".

We recommend using declarative configuration in general, which has many benefits:

1. The config file is more concise and clear.
2. The correspondence between the file directory structure and the sidebar directory structure is more intuitive.
3. When adding or deleting sidebar directories, operate directly in the current directory instead of navigating to the corresponding location in the rspress.config.ts file and then adding/deleting configurations, thereby reducing the cost of developing context switching.

However, programmatic configuration is very useful in some scenarios that require dynamic config generation, such as the official TypeDoc plugin of Rspress, which automatically converts to nav and sidebar configurations based on a piece of JSON data provided by TypeDoc.

MDX Support

MDX is a powerful content development format. You can not only write Markdown files as usual, but also use React components in Markdown content.

In addition, Rspress also supports some specific syntax, such as:

• Custom container syntax.
• FrontMatter Metadata definition.
• Code line highlighting syntax.

Details can be found in the document: https://rspress.dev/zh/guide/basic/use-mdx.html

SSG

Rspress is a standard SSG framework. In the production build, it will automatically help you generate static sites, that is, generate HTML content of each page. After the build process is completed, HTML will appear in the default output directory.

Afterwards, you can deploy the contents of this output directory to any static site hosting service, such as Github Pages, Netlify, Vercel, etc.

At the same time, we also provide configs that allow you to easily customize the HTML content generated by SSG. For details, please refer to the documentation: https://rspress.dev/guide/basic/ssg.html.

I18n

Internationalization(i18n) is a common requirement on a document site, and Rspress encapsulates the ability of i18n in a simple and easy-to-use way. In the framework, we abstract i18n into the following requirements:

• How to define an I18n data source?
• How to configure sites in different languages?
• How to organize document directories in different language versions?
• How to use I18n data sources in custom components?

The framework has already supported these demand scenarios for you, and you can follow the official tutorial step by step to implement i18n for your site.

Multi Version

In some scenarios, we need to manage multi-version documents. Rspress has built-in support for multi-version documents. On the one hand, you can enable this capability through simple config. On the other hand, you only need to organize the directory in the usual way, without introducing unnecessary directories and concepts, which minimizes mental burden.

// Config file
import { defineConfig } from 'rspress/config';

export default defineConfig({
  multiVersion: {
    default: 'v1',
    versions: ['v1', 'v2'],
  },
});

// Directory structure
docs
├── v1
│   ├── README.md
│   └── guide
│       └── README.md
└── v2
    ├── README.md
    └── guide
        └── README.md

Full-text Search

Rspress provides full-text search capability for out of the box, which you can access without any config. The underlying implementation is based on the open-source FlexSearch engine, and the effect is as follows:

Customize Theme

Rspress supports two ways to customize themes:

1. Based on the default theme extension. In the various components of the default theme, many slots are provided for you to add custom layout content, such as accessing the AI search component provided by documate.

// theme/index.tsx
import Theme from 'rspress/theme'
import { NoSSR } from 'rspress/runtime'
import { Documate } from '@documate/react'
import '@documate/react/dist/style.css'

const Layout = () => (
  <Theme.Layout
    afterNavTitle={
      <NoSSR>
        <Documate endpoint="" />
      </NoSSR>
    }
  />
)

export default {
  ...Theme,
  Layout,
}

export * from 'rspress/theme'

The effect is as follows:

Integration document in detail: https://documate.site/integration/rspress

2. Fully customized theme. If you want to develop a custom theme from scratch, you can customize the content of the Layout and use various Runtime APIs provided by Rspress (such as usePageData) to obtain compile-time data, routing and other information.

For details on custom themes, you can refer to the documentation https://rspress.dev/zh/guide/advanced/custom-theme.html.

Plugin System

The plugin system is a crucial part of Rspress, which allows you to easily extend the functionality of the framework during the process of building a site. The overall architecture of Rspress is as follows:

The framework is divided into two parts: the Node side and the browser runtime. Through the plugin system, you can easily extend the functions of these two parts, such as adding Markdown/MDX compile plugins, adding custom routes, adding custom global components, adding Rspack plugins, and so on.

It is worth noting that since the underlying Rspack provides good compatibility with webpack, you can use most of the webpack plugins in the community in Rspress.

The official plugins currently available include:

• @rspress/plugin-medium-zoom： medium-zoom integrated plugin, used to support MediumZoom image magnification effect.
• @rspress/plugin-last-updated：support displaying the last updated time.
• @rspress/plugin-container-syntax：support container syntax in rspress.
• @rspress/plugin-typedoc： TypeDoc integrated plugin, which is used to generate api doc from typescript files.
• @rspress/plugin-preview：support component preview in code blocks.
• @rspress/plugin-playground：support component preview in code blocks and provide a real-time playground.

Component Document

Demo Preview

Rspress provides a preview plugin that can automatically generate component previews for you. After registering the preview plugin, declare the following code block in the mdx file:

import React from "react";
import { Tag, Space } from "@arco-design/web-react";
import "@arco-design/web-react/dist/css/arco.css";
const COLORS = ["red", "orangered", "orange", "gold", "lime", "green", "cyan", "blue", "arcoblue", "purple", "pinkpurple", "magenta", "gray"];

export default () => (
  <Space wrap>
    {COLORS.map((color, i) => (
      <Tag key={i} color={color}>
        {color}
      </Tag>
    ))}
  </Space>
);

Then you can see the following preview effect:

Of course, the plugin also supports mobile preview mode. You can enable it through the plugin config. The effect is as follows:

Demo Playground

For component documents, providing the ability to edit components in real time will greatly improve the interactive experience of the document.

To achieve this function, you only need to register the official playground plugin and declare your code block in mdx file. (Taking the above code block as an example here)

Next, you will see the following playground effect in the document:

Built-in smooth transition animation

View Transition API is a set of APIs provided natively by modern browsers to achieve transition effects during page jumping. We have also followed up on this feature in Rspress, implementing document transition animations based on View Transition without using any third-party SPA animation schemes. In the future, we will explore more animation effects to further improve the experience.

export default defineConfig({
  themeConfig: {
    // Enable View Transition
    enableContentAnimation: true,
  },
});

Differences from Other SSG Frameworks

Differences from Docusaurus

Docusaurus is an open-source SSG framework by Meta. Like Rspress, it uses React as the rendering framework and supports MDX. However, the main differences between Rspress and Docusaurus are:

1. Rspress has better build performance. Based on the Rust front-end toolchain, Rspress's project startup/build speed is 5 ~ 10 times faster than Docusaurus. For details, refer to Build Performance.
2. Rspress has simpler config and lower learning curve. Rspress's config is simpler, does not introduce too many concepts, and reduces cognitive load as much as possible. For example, it provides out-of-the-box search functionality, intuitive multi-version document management, etc.
3. Rspress provides a higher level of abstraction for Bundler in its architecture. For low-level Bundlers like webpack and Rspack, their config items are complex and not easy to get started with. Docusaurus chooses to directly expose the config items of the underlying Bundler, while Rspress provides a higher level of abstraction for Bundler, offering simpler and more user-friendly config items. For instance, you can easily add tags in <head> through builderConfig.html.tags, without having to register related plugins via Bundler like html-webpack-plugin.

Differences from Nextra

Nextra is an open-source SSG framework by Vercel. Like Rspress, it also uses React as the rendering framework and supports MDX. The main differences between Rspress and Nextra are:

1. Rspress has better build performance. This point can be referred to "Differences from Docusaurus".
2. Rspress is overall lighter. Nextra relies on Next.js, and its SSG process is also based on Next.js. Therefore, the SSG output is not purely HTML files, but includes some runtime code from Next.js. On one hand, this leads to a larger size of Nextra's output. On the other hand, it needs to be deployed as an application (using the next start command) rather than being deployed as a pure static site. But Rspress is not bound to any application framework, so its output is lighter and can be conveniently deployed as a pure static site.

Differences from VitePress

VitePress is a static site generator based on Vite. It is characterized by using Vue as the rendering framework and has excellent performance. The main differences between Rspress and VitePress are:

1. Rspress uses React as the rendering framework, while VitePress uses Vue.
2. Rspress uses MDX for content development, while VitePress uses Markdown and supports Vue components in Markdown, which also leads to differences in the implementation of the underlying compilation toolchain.
3. In terms of build performance, during the development phase, both Rspress and VitePress can quickly start a project. However, in the production environment, VitePress needs to bundle the project based on Rollup, so it will face similar performance issues with other JavaScript-based toolchains. At this time, Rspress will have faster build speed.

Future Plans

Improve Basic Capabilities

Rspress currently provides functions that can meet the needs of most SSG projects. At the same time, we will also enrich the basic capabilities of Rspress based on community feedback in the future to meet the needs of more scenarios.

Complete the mdx-rs capability

Although the compile capability of mdx-rs can handle most pure document development scenarios, there are still some scenarios that can not meet the requirements, such as preview plugin and playground plugin. We will further improve these commonly used capabilities.

Richer custom theme

In addition to the default document theme, we will also add richer themes to Rspress in the future. Welcome community friends to contribute 👏🏻

More abundant plugin capabilities

In the future, we will also provide more official plugin capabilities, such as:

• BackTop plugin, adds a back-to-top effect to the page.
• Google Analytics plugin, integrates Google Analytics into the site, collects website access data.
• Sitemap plugin that generates sitemap files during the build phase.
• PWA plugin, providing PWA integration.
• Client Redirect plugin that provides Route Retargeting capability.
• ......

Optimize performance and quality

Performance is the key advantage of Rspress. With the continuous iteration of the project, we will gradually establish a perfect performance observation mechanism to prevent performance degradation, find potential performance improvement points, and provide community users with a good development experience.

At the same time, we will continue to improve functional test cases, improve test coverage, and ensure the long-term healthy development of the project.

Acknowledgments

The design of Rspress has been inspired and supported by many projects in the community, and we pay gratitude to these predecessors here:

• The VitePress project (created by @Evan You), where the implementation architecture of SSG provides a reference for Rspress.
• The Vuepress project (created by @Evan You and @ulivz), whose plugin system design inspired the plugin API design of Rspress.
• The Nextra project (created by @shuding), the _meta.json design of Rspress was inspired by this and simplified by Nextra.
• The mdxjs-rs project (created by @wooorm) has saved @rspress/mdx-rs a lot of development costs.
• The NAPI-RS project (created by @Brooooooklyn) provides support for the node-binding implementation of mdx-rs.
• Dumi (created by @PeachScript) provides a design reference for the mobile component demo preview function of Rspress.

[popuguytheparrot]

Therefore, the SSG output is not purely HTML files, but includes some runtime code from Next.js.
this can disable in config by page

On the other hand, it needs to be deployed as an application (using the next start command) rather than being deployed as a pure static site.
for this need use next export command

[sanyuan0704]

I have tried next export but it doesn't work after integrating nextra plugin. shuding/nextra#1202

[hooper-hc]

性能对比不应该和：基于 Islands Architecture 的 astro 或者 VitePress比较么？你们怎么处理 Hydration 的？

[sanyuan0704]

hydration 目前使用的是全量 JS hydration，尝试过 islands 架构，但默认文档主题中交互的部分比较多加上 MPA 的体验问题，最后没有采用。