前言

如果你想使用 dumi2.0 搭建组件库时，可以仔细阅读本文。本文主要记录一些在搭建组件库的详细过程以及遇到的坑。

背景

1. 由于团队缺少一个能够通用的中后台业务组件库
2. 由于项目中通用的组件，在开发过程中经常被不同的人修改，导致线上出现全局性的保错，提取组件减少该事件发生
3. 由于经过长年累月对组件无规范的修改，导致代码变得臃肿，难以维护。
4. 希望通过该组件库统一多端的样式，减少不合理的UI设计，提升用户体验
5. 希望通过该组件库提升研发效率

项目初始化

根据 dumi 文档进行 初始化。

搭建组件库一定要选择 React Library，否则在 md 文件写组件demo文档是没办法生效的。React Library 就是说你想开发一个以 React 为基础的库，dumi对md文档输出进行特殊的处理。

初始化完在之后的目录结构如下如：

组件库文档首页

我们需要将首页改成如下图所示的样子：

文案

修改 docs 文件下的 index.md 就可以改变。

yarn start 后，访问 localhost:8080 页面如下图

头部

不需要头部的 Guide 和 foo 导航，分成两步：

• 删除 docs 下的 guide.md
• 为了删除 foo导航 在.dumirc的themeConfig属性中配置如下代码

import { defineConfig } from 'dumi';

export default defineConfig({
 outputPath: 'docs-dist',
 themeConfig: {
   nav: [
     {
       title: '',
       link: '/components/export-button',
     },
   ],
   socialLinks: {
     github: 'https://github.com/tastien',
   },
 },
});

logo、右侧Actions

代码如下：

import { defineConfig } from 'dumi';

export default defineConfig({
  outputPath: 'docs-dist',
  themeConfig: {
    hd: { rules: [] },
    rtl: true,
    name: 'Tst Design',
    nav: [
      {
        title: '',
        link: '/components/export-button',
      },
    ],
    logo: '',
    footer: 'tastaien | Copyright © 2023-present',
    prefersColor: { default: 'light', switch: true },
    socialLinks: {
      github: 'https://github.com/tastien',
    },
  },
});

这一系列主题配置代码，具体可以参考 编译时配置 (umijs.org) 文档

标题、立即使用按钮

分成两步

• 配置主题，代码如下

import { defineConfig } from 'dumi';

export default defineConfig({
  // ...
  theme: {
    '@c-primary': '#b62021',
    'primary-color': '#b62021',
  },
});

配置完主题色如下图：

可以发现标题颜色有点淡，遇到这样的情况我之前也束手无策了一段时间。

后面经过研究发现，如果想要修改默认主题的样式需要找到dumi默认主题的github代码，在文件夹.dumi下创建一个theme文件夹，结构如下图：

修改标题颜色步骤如下：

1. 在github找到dumi2.0的默认主题包
2. 在我们的项目的.dumi文件下创建theme文件夹
3. 把默认主题的slots下的HeroTitle复制到我们的theme文件下，进行修改。

修改后如下图所示：

组件文档主页

布局

由于默认主题的左侧导航偏小不够放组件名，我想要改变dumi的默认主题的左侧边栏。

步骤如下：

1. 在github找到dumi2.0的默认主题包
2. 在我们的项目的.dumi文件下创建theme文件夹
3. 把默认主题的slots下的Sidebar复制到我们的theme文件下，Sidebar文件中需要的文件一样复制过来

然后进入 theme/slots/Sidebar/index.less，把左侧边栏的宽度注释掉

修改后如下图所示：

其他位置同理可以调整。

编写文档

如下图所示我们将在 index.tsx 编写组件，编写完第一个组件，开始编写第一个组件文档。

注意：文件顶部是导航配置

接着将组件入到 index.md中，有两种方式：

1. 通过 code 标签引入

如上图中的代码：

<code src="./demo/base.tsx">

1. 直接写在index.md 文件中，如下代码

## 代码演示

### 基础用法

```
import { ExportButton } from '@tastien/tstd';
import React from 'react';

const App: React.FC = () => {
    const request = () => {
        return new Promise(function (resolve) {
          setTimeout(function () {
            resolve('导出');
          }, 1000);
        });
    };
    return (
       <ExportButton request={request} type="default">
          导出
        </ExportButton>
    )
}
```

在 dumi 中 index.md 会被打包成doc-dist。

如果是基于 antd 组件库开发的，在写第一个组件后引入到index.md，第一步你可能会遇到一个问题，antd组件库的样式丢失，如下图：

经过查阅 antd 组件库文档以及网上的资料发现，有两种方式解决：

• 要在 .dumi 中 global.less 引入 antd 的样式。

@import '~antd/dist/antd.css';

• 在 .dumirc.ts 中添加配置，这种方式是按需加载的，所以我采用的是这种方式。

extraBabelPlugins: [
    [
      'babel-plugin-import',
      {
        libraryName: 'antd',
        libraryDirectory: 'es',
        style: true,
      },
    ],
],

组件库发布到npm

开发完组件库后接着就是要把组件库发布到npm上，我们遵循semver 语义化版本规范, 也就是1(主版本号).0(次版本号).0(修订版本号)这样的模式。有破坏性的更新动第一位，有新功能动第二位，改bug动第三位。大部分的开源项目都遵循这个规范，所以我们后续不要随心所欲改动版本号。

接下来就将组件进行发布到 npm 上，你可能会在发布后会遇到如下问题：

组件库在项目中引入组件但样式不生效

遇到这个问题说明组件库文档中引入的组件是有样式的，需要先确认文档中样式生效的原因，通常有 3 种可能：

1. 借助 .dumi/global.less 加载了组件库样式表
2. 借助 .dumirc.ts 中的 styles 配置项加载了组件库样式表
3. 借助 babel-plugin-import 并将其配置到 .dumirc.ts 中按需加载了组件样式

实际上，这些样式引入方案均只对文档构建生效，也就是说它们都是依托于 dumi 框架提供的能力，而组件库发布为 NPM 包以后，组件库的编译将由实际使用组件库的项目负责。

因此，我们需要根据项目使用的开发框架做等价配置，才能确保样式生效，此处以 Umi 项目为例，上述 3 种方案的等价配置方式如下：

1. 借助 src/global.less 加载组件库样式表
2. 借助 .fatherrc.ts 中的 styles 配置项加载组件库样式表
3. 借助 babel-plugin-import 并将其配置到 .fatherrc.ts 中按需加载组件样式

最佳解决方案: 在 .fatherrc.ts 中添加配置

extraBabelPlugins: [
    [
      'babel-plugin-import',
      {
        libraryName: 'antd',
        libraryDirectory: 'es',
        style: true,
      },
    ],
],

部署文档

文档部署在哪里是一个问题，对于大部分的人来说，可能没有精力去维护一个静态服务器， 所以我们的目标是将文档部署到 githubPages，根据dumi文档描述，这样的情况属于非根目录部署。

部署到githubPages

非根目录部署需要修改 Umi 的 base 配置项 和 视实际情况 修改 publicPath 配置项。

意思就是说，在github上的项目名称为 tst-design，那么就要在.dumirc文件中的属性 base 和 publicPath 改成：

export default defineConfig({
  base: '/tst-design',
  publicPath: '/tst-design/',
})

手动步骤

注意手动部署文档时操作如下：

• 先安装 gh-pages

yarn add gh-pages -D

• package.json 中添加

"scripts": {
  "deploy": "gh-pages -d docs-dist"
}

• 运行 yarn docs:build
• 运行 deloy

运行完后你在看下 github 上会多出一个 gh-pages 分支。

部署成功后的文档地址位置如下图，找到项目点击Actions，成功会给你一个地址：

如果失败，记得看一下这里是不是配置对了：

只有这样才能访问文档页面。

自动化部署

当项目有多个贡献者时，一些贡献者不可避免会犯一些流程错误。比如提交代码时，没有尝试对项目进行生产模式的构建等等，我们需要在提交代码到git远程仓库时去做一些流程性的任务，也就是我们常说的ci/cd或者流水线。

所以我们将采用自动化部署也就是Git Actions，让它帮执行单元测试和代码校验、github的同步、文档的部署。

具体操作如下：

创建 .github/workflows/gh-pages.yml 文件

gh-pages.yml模板如下：

name: github pages

on:
  push:
    branches:
      - main # default branch

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: yarn
      # 文档编译命令，如果是 react 模板需要修改为 npm run docs:build
      - run: yarn docs:build
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.MY_TOKEN }}
          # 文档目录，如果是 react 模板需要修改为 docs-dist
          publish_dir: ./docs-dist

上面的文件中的 MY_TOKEN 变量，需要在github上面进行申明。

第一步：你要去 github的 Developer Settings 中申请一个 Personal access tokens (classic)，个人权限token。

第二步：然后找到对应的项目中，按照下图进行操作。

参考文档:

dumi - 为组件研发而生的静态站点框架 (umijs.org)