从0到1搭建react组件库-文档篇

环境配置

rspress作为一个基于rsbuild的静态站点生成器，它的构建性能非常好，并且支持MDX（可以在MDX中引用react组件渲染），并且包含所有的文档站基础功能（国际化、多版本支持、全文搜索等），并且内置插件系统，可以根据需求拓展功能。（如果文章中有错误内容，欢迎大家交流指正。）

rspress项目配置

1. 进入apps/website/目录下， 运行npm init -y.
2. 然后在devDependencies字段中添加rspress以及typescript相关依赖，并且修改包的名称。

json

代码解读

复制代码

// apps/website/package.json { "name": "@mini-ui/website", "version": "1.0.0", "description": "", "main": "index.js", "scripts": { }, "devDependencies": { "rspress": "1.30.0", "typescript": "5.6.2", "ts-node": "10.9.2" } }

1. 命令行进入apps/website目录下的中运行pnpm i， 下载安装rspress及typescript相关的依赖。
2. 在apps/website目录下新建一个ts.config.json文件，用来配置typescript的基本内容（ts继承于根目录tsconfig, 然后根据官网信息加入ts的额外配置即可）。

json

代码解读

复制代码

//apps/website/tsconfig.json { "extends": ["../../tsconfig.json"], "include": ["docs", "theme", "rspress.config.ts"], "mdx": { "checkMdx": true } }

1. 在apps/website目录下新建一个rspress.config.ts， 然后按照官网配置即可， 具体配置信息见rspress基础配置。

ts

代码解读

复制代码

// /apps/website/rspress.config.ts import { defineConfig } from "rspress/config"; export default defineConfig({ root: "docs", title: "mini-ui", })

1. apps/website目录下的package.json中追加启动命令，如下。

json

代码解读

复制代码

// apps/website/package.json { "name": "@mini-ui/website", "version": "1.0.0", "description": "", "main": "index.js", "scripts": { "dev": "rspress dev", "build": "rspress build", "preview": "rspress preview" }, "keywords": [], "author": "", "license": "ISC", "devDependencies": { "rspress": "1.30.0", "typescript": "5.6.2", "ts-node": "10.9.2" } }

至此，rspress的基本配置已经完成。接下来就是去了解rspress的约定式路由的相关概念，然后如何通过_meta.json创建文档的nav导航栏、sidebar侧边栏主体展示的文档内容了。

rspress基础概念

约定式路由

约定式路由的概念其实很常见，也可以将其称之为文件路由， 框架会去读取约定的文件夹下的文件的文件路径，然后通过文件路径解析出路由配置，这样的做法可以让整个项目的路由非常直观， 不用打开路由配置文件查找路由信息。

官方例子如下：

代码解读

复制代码

docs ├── foo │ └── bar.md └── foo.md

具体映射规则如下：

文件路径	路由路径
index.md	/
/foo.md	/foo
/foo/bar.md	/foo/bar
/zoo/index.md	/zoo/

自动化导航栏/侧边栏

Rspress中， 有两种实现导航栏和侧边栏的声明。

1. 在配置文件中通过ThemeConfig字段中声明nav和siderbar来实现导航栏和侧边栏的内容。
2. 通过在目录下创建_meta.json来自动化生成导航栏和侧边栏。

在这里我们选择第二种方式，即通过_meta.json描述文件，来声明导航栏和侧边栏的信息。其中_meta.json在项目中声明的位置不同，也代表着不同的级别。

1. 在文档根目录(/apps/website/docs下，或者配置文件中root字段的目录下)的_meta.json将会被解析成为导航栏。
2. 在根目录中的子目录中， 生成的则是侧边栏级别。

开发

配置首页面

这里配置比较简陋，仅包含标题、子标题、还有两个按钮内容。

md

代码解读

复制代码

// apps/website/index.md --- pageType: home hero: name: mini-ui actions: - theme: brand text: 快速开始 link: /guide/basic/ - theme: alt text: Github link: https://github.com/frontendley/mini-ui ---

配置导航栏

导航栏就是顶部的主要内容。（这里的title是在rspress.config.ts中配置），主要是配置了一个Guide按钮，以及右侧的github地址。

注意导航栏的配置是在根目录中。

json

代码解读

复制代码

// apps/website/docs/_meta.json [ { "text": "Guide", // 显示的文本 "link": "/guides/start", // 跳转的链接 "activeMatch": "^/guides/", // 路由匹配正则，若匹配会高亮 "position": "left" // 位置 左边还是右边 }, { "text": "Github", "link": "https://github.com/frontendley/mini-ui", "activeMatch": "", "position": "right" } ]

配置侧边栏

侧边栏的内容，在根目录的子目录下进行配置。

json

代码解读

复制代码

// /apps/website/docs/guide/_meta.json [ { "type": "dir", // 文件/目录/链接， 若为目录，则有子菜单，若为文件，则点击即可跳转。 "name": "basic", // 文件名/目录名 "label": "基础指南" // 展示在页面中的内容。 }, { "type": "dir", "name": "components", "label": "组件" } ]

配置侧边栏中的嵌套路由

快速开始

创建basic目录， 然后在basic目录下创建_meta.json以及index.mdx，分别用来配置子菜单，以及点击子菜单后显示的内容。

• _meta.json

json

代码解读

复制代码

// apps/website/docs/guide/basic/_meta.json [ { "type": "file", "label": "快速开始", "name": "index" } ]

• index.mdx

ruby

代码解读

复制代码

// apps/website/docs/guide/basic/index.mdx # 快速开始 ## 通过本教程快速开始使用mini-ui

组件/按钮组件配置

创建components目录，以后的组件主要展示在这个目录下。 先创建一个button.mdx文件，然后在_meta.json中声明这个菜单项。

• button.mdx

md

代码解读

复制代码

// apps/website/docs/components/button.mdx # 按钮组件

• _meta.json

less

代码解读

复制代码

// apps/website/docs/components/_meta.json [ { "type": "file", "label": "按钮", "name": "button" }]

Demo项目配置

参照开发方案篇中的对mini-ui的react下载配置，以及如何在测试项目中声明下载组件库的内容。配置下react以及ts，和mini-ui的依赖即可。

button组件Demo

1. 在demo目录中新增一个button文件夹， 然后新建一个basic-button.tsx文件，用来调用@mini-ui中的button组件，然后在文档中引用展示。

tsx

代码解读

复制代码

// /apps/demo/button/basic-button.tsx import {Button} from "@mini-ui/ui"; export default function App () { return ( <Button></Button> ) }

1. 在apps/website/docs/guide/button.mdx中，增加内容, 引用demo下的basic-button进行展示。

css

代码解读

复制代码

# 按钮组件 <code src="../../../../demo/button/basic-button.tsx" />

5. 刷新页面后，发现不能展示引用的button组件， 是因为rspress需要预览插件，才能在页面中渲染组件内容。安装@rspress/plugin-preview插件，注意要和rspress版本一致。

json

代码解读

复制代码

// apps/website/package.json { "name": "@mini-ui/website", "version": "1.0.0", "description": "", "main": "index.js", "scripts": { "dev": "rspress dev", "build": "rspress build", "preview": "rspress preview" }, "keywords": [], "author": "", "license": "ISC", "devDependencies": { "rspress": "1.30.0", "typescript": "5.6.2", "ts-node": "10.9.2", "@rspress/plugin-preview": "1.30.0" // 预览插件 } }

1. 接着在website/rspress.config.ts中，配置插件内容。

ts

代码解读

复制代码

import { defineConfig } from "rspress/config"; import { pluginPreview } from "@rspress/plugin-preview"; export default defineConfig({ root: "docs", title: "mini-ui", plugins: [pluginPreview()], })

1. 刷新页面。

项目地址

未完待续

后续会开始样式的整体内容设计。（参照arco-desgin的思路。）

原文链接：https://juejin.cn/post/7416168750363541516