前言
无论团队大小，随着时间的推进，多多少少都会有一些可提取的业务组件，沉淀组件库和对应的文档是一条必经之路。
直接进入正题，从 0 到 1 开始搞一个业务组件库（可从注释中生成）。
最终的 Demo 可看这里，请使用 Mac 或者 Linux 终端来运行，windows 兼容性未做验证。
使用到工具
这三个工具是后续业务组件库搭建使用到的，需要有一定的了解：
- Lerna ，Lerna是一个 Npm 多包管理工具，详细可查看官方文档。
- Docusaurus，是 Facebook 官网支持的文档工具，可以在极短时间内搭建漂亮的文档网站，详细可查看官网文档。
- Vite，Vite 是一种新型前端构建工具，能够显著提升前端开发体验，开箱即用，用来代替 rollup 构建代码可以省掉一些繁琐的配置。
初始化项目
注意 Node 版本需要在 v16 版本以上，最好使用 v16 版本。
初始化的文件结构如下：
.
├── lerna.json
├── package.json
└── website假设项目 root 文件夹：
第一步，初始化 Lerna 项目
$ npx lerna@latest initlerna 会添加
package.json和lerna.json。第二步，初始化 Docusaurus 项目（typescript 类型的）
$ npx create-docusaurus@latest website classic --typescript第三步，配置
package.jsonnpm run bootstrap可初始化安装所有分包的依赖包。npm run postinstall是 npm 钩子命令，在依赖包完成安装后会触发npm run postinstall的运行。
{ "private": true, "dependencies": { "lerna": "^5.1.4" }, "scripts": { "postinstall": "npm run bootstrap", "bootstrap": "lerna bootstrap" } }第四步，配置
lerna.jsonpackages设置分包的位置，详细配置可长 lerna 的文档。npmClient可指定使用的npm客户端，可以替换为内部的 npm 客户端或者yarn。hoist设置为true后，分包的同一个依赖包如果相同，会统一安装到最上层项目的根目录root/node_modules中，如果不相同会有警告，同一个相同的版本安装到最上层根目录，不相同的依赖包版本安装到当前分包的node_modules目前下。
{ "packages": ["packages/*", "website"], "version": "0.0.0", "npmClient": "npm", "hoist": true }
使用 Vite 创建组件分包
最终文件夹路径如下：
.
├── lerna.json
├── package.json
├── packages
│ └── components
│ ├── package.json
│ ├── src
│ ├── tsconfig.json
│ ├── tsconfig.node.json
│ └── vite.config.ts
└── website
- 第一步，创建
packages/components文件夹 第二步，初始化 Vite 项目，选用
react-ts的模板。$ npm init vite@latest第三步，删除不必要的文件
由于只用 Vite 的打包功能，用不上 Vite 的服务开发功能，所以要做一些清理。
删除
index.html和 清空src文件夹。第四步，配置
packages/components/vite.config.tsVite 的详细配置可以查看官方文档，可以细看配置 Vite 的库模式，Vite 的打包其实是基于 rollup，这里说明一下需要注意的配置：
rollupOptions.external 配置
确保外部化处理那些你不想打包进库的依赖，如 React 这些公共的依赖包就不需要打包进来。
rollupOptions.globals 配置
在 UMD 构建模式下为这些外部化的依赖提供一个全局变量。
Less 配置
Vite 默认是支持 Less 的，需要再 package.json 添加 less 依赖包后才生效。也默认支持 css module 功能。
由于是库类型，所以 less 需要配置 classs 前缀，这里还根据
src/Table.module.less或者src/Table/index.module.less类型的路径获取 Table 为组件名前缀。
import { defineConfig } from 'vite';
import path from 'path';
// 在 UMD 构建模式下为外部依赖提供一个全局变量
export const GLOBALS = {
react: 'React',
'react-dom': 'ReactDOM',
};
// 处理类库使用到的外部依赖
// 确保外部化处理那些你不想打包进库的依赖
export const EXTERNAL = [
'react',
'react-dom',
];
// https://vitejs.dev/config/
export default defineConfig(() => {
return {
plugins: [react()],
css: {
modules: {
localsConvention: 'camelCaseOnly',
generateScopedName: (name: string, filename: string) => {
const match = filename.replace(/\\/, '/').match(/.*\/src\/(.*)\/.*\.module\..*/);
if (match) {
return `rabc-${decamelize(match[1], '-')}__${name}`;
}
return `rabc-${name}`;
},
},
preprocessorOptions: {
less: {
javascriptEnabled: true,
},
},
},
build: {
rollupOptions: {
external: EXTERNAL,
output: { globals: GLOBALS },
},
lib: {
entry: path.resolve(__dirname, 'src/index.ts'),
name: 'RbacComponents',
fileName: (format) => `rbac-components.${format}.js`,
},
},
};
});第五步，配置
packages/components/package.json需要注意三个字段的配置：
-
- main，如果没有设置
module字段，Webpack、Vite 等打包工具会以此字段设置的文件为依赖包的入口文件。 - module，一般的工具包默认优先级高于
main，此字段指向的应该是一个基于 ES6 模块规范的模块，这样打包工具才能支持 Tree Shaking 的特性。 - files，设置发布到 npm 上的文件或者文件夹，默认 package.json 是不用做处理的。
{ "version": "0.0.0", "name": "react-antd-business-components", "main": "dist/rbac-components.umd.js", "module": "dist/rbac-components.es.js", "files": [ "dist" ], "scripts": { "build": "vite build" }, "dependencies": {}, "devDependencies": { "@types/react": "^18.0.14", "@types/react-dom": "^18.0.5", "@vitejs/plugin-react": "^1.3.2", "classnames": "2.3.1", "cross-spawn": "7.0.3", "decamelize": "4.0.0", "eslint": "8.18.0", "less": "^4.1.3", "prop-types": "^15.7.2", "react": "^17.0.2", "react-dom": "^17.0.2", "rimraf": "^3.0.2", "typescript": "^4.6.4", "vite": "^2.9.12" } } - main，如果没有设置
创建组件
在 package/components/src 目前下创建两个文件：
index.ts
export { default as Test } from './Test';Test.tsx
import React from 'react'; export interface ProContentProps { /** * 标题 */ title?: React.ReactNode; /** * 内容 */ content: React.ReactNode; } /** * 展示标题和内容 */ const Test: { (props: ProContentProps): JSX.Element | null; displayName: string; defaultProps?: Record; ); }; Test.displayName = 'Card'; Test.defaultProps = { title: '标题', content: "内容", }; export default Test;{title}{content}
编写组件文档
Docusaurus 是支持 mdx 的功能，但是并不能读取注释，也有没组件可以一起展示 Demo 和 Demo 的代码。
所以在编写文档前还需要做一些准备，支持 PropsTable 和 CodeShow 的用法，这里实现的细节就不做细说，感兴趣的可以查看 react-doc-starter。
组件文档编写准备
第一步，md 文件支持直接使用 PropsTable 和 CodeShow 组件
新建以下几个文件，同时需要添加相应的依赖包，文件内容可以在这个项目 react-doc-starter 中获取。
website/loader/propsTable.js website/loader/codeShow.js website/plugins/mdx.js第二步，支持 Less 功能
Less 的功能需要和 Vite 打包是配置的 Less 一致。
const decamelize = require('decamelize'); module.exports = function (_, opt = {}) { delete opt.id; const options = { ...opt, lessOptions: { javascriptEnabled: true, ...opt.lessOptions, }, }; return { name: 'docusaurus-plugin-less', configureWebpack(_, isServer, utils) { const { getStyleLoaders } = utils; const isProd = process.env.NODE_ENV === 'production'; return { module: { rules: [ { test: /\.less$/, oneOf: [ { test: /\.module\.less$/, use: [ ...getStyleLoaders(isServer, { modules: { mode: 'local', getLocalIdent: (context, _, localName) => { const match = context.resourcePath.replace(/\\/, '/').match(/.*\/src\/(.*)\/.*\.module\..*/); if (match) { return `rabc-${decamelize(match[1], '-')}__${localName}`; } return `rabc-${localName}`; }, exportLocalsConvention: 'camelCase', }, importLoaders: 1, sourceMap: !isProd, }), { loader: 'less-loader', options, }, ], }, { use: [ ...getStyleLoaders(isServer), { loader: 'less-loader', options, }, ], }, ], }, ], }, }; }, }; };第三步，支持 alias
需要添加
website/plugin/alias.js插件和修改tsconfig.jsonalias.js
const path = require('path'); module.exports = function () { return { name: 'alias-docusaurus-plugin', configureWebpack() { return { resolve: { alias: { // 支持当前正在开发组件依赖包（这样依赖包就无需构建，可直接在文档中使用） 'react-antd-business-components': path.resolve(__dirname, '../../packages/components/src'), $components: path.resolve(__dirname, '../../packages/components/src'), // 用于缩短文档路径 $demo: path.resolve(__dirname, '../demo'), // 用于缩短文档路径 }, }, }; }, }; };tsconfig.json
{ // This file is not used in compilation. It is here just for a nice editor experience. "extends": "@tsconfig/docusaurus/tsconfig.json", "compilerOptions": { "baseUrl": ".", "paths": { "react-antd-business-components": ["../packages/components/src"] } }, "include": ["src/", "demo/"] }第四步，配置
website/docusaurus.config.js使用插件：const config = { ... plugins: [ './plugins/less', './plugins/alias', './plugins/mdx', ], ... }; module.exports = config;第五步，修改默认的文档路径和默认的 sidebar 路径
由于我们还可能有其他文档如 Utils 文档，我们需要而外配置一下
website/docusaurus.config.js:把文档路径修改为
website/docs/components，sidebar 路径改为webiste/componentsSidebars.js，sidebar 文件直接改名即可，无需做任何处理。const config = { ... presets: [ [ 'classic', /** @type {import('@docusaurus/preset-classic').Options} */ ({ docs: { path: 'docs/components', routeBasePath: 'components', sidebarPath: require.resolve('./componentsSidebars.js'), // Please change this to your repo. // Remove this to remove the "edit this page" links. editUrl: 'https://github.com/samonxian/react-doc-starter/tree/master', }, }), ], ], ... }; module.exports = config;
正式编写组件文档
在 website/demo 文件中创建 Test/Basic.tsx 和 Test/Basic.css ，在 website/docs/components/data-show 中创建 Test.md 和 _category_.json 文件：
demo/Test/Basic.tsx
import React from 'react';
import { Test } from 'react-antd-business-components';
import './Basic.css';
const Default = function () {
return (
demo/Test/Basic.css
.test-demo-container {
background-color: #eee;
padding: 16px;
}docs/components/data-show/\_category\_.json 是 Docusaurus 的用法，详细点击这里。
{
"position": 2,
"label": "数据展示",
"collapsible": true,
"collapsed": false,
"link": {
"type": "generated-index"
}
}docs/components/data-show/Test.md
如果要定制化配置此 Markdown，如侧边栏文本、顺序等等，可细看 Markdown 前言。
CodeShow 和 PropsTable 组件用法可看这里。
## 使用
### 基本使用
运行文档服务
这里运行文档服务，可以查看 Demo 的效果，相当于一遍写文档一边调试组件，无需另起开发服务调试组件。
$ cd ./website
$ npm start发布组件
在项目 root 根目录下运行：
$ npm run build:publish此名会运行lerna build 和 lerna publish 命令，然后安装提示进行发布即可，详细的用法可查看 lerna 命令。
部署文档
详细可看 Docusaurus。
如果是 Github 项目建议发布到 GitHub Pages，命令如下：
$ cd ./website
$ npm run deploy拓展
使用 Vite 转换 src 中的文件
打包时候，Vite 会把所有涉及到的文件打包为一个文件，而我们常常把 src 文件夹的所有 JavaScript 或者 Typescript 文件转换为 es5 语法，直接提供为 Webpack、Vite 这些开发服务工具使用。
Vite 不支持多入口文件和多输出文件的模式，需要自己实现一套 npm run build:file 命令。
第一步，package.json 添加如下 scripts 命令
{ "scripts": { "tsc:es": "tsc --declarationDir es", "tsc:lib": "tsc --declarationDir lib", "tsc": "npm run tsc:lib && npm run tsc:es", "clean": "rimraf lib es dist", "vite": "vite", "build:lib": "vite build", "build:file": "node ./scripts/buildFiles.js", "build": "npm run clean && npm run tsc && npm run build:file && npm run build:lib" } }第二步，添加
package/components/.env文件，确保构建环境未 productionNODE_ENV=production第三步，创建
package/components/scripts/buildFile.js文件：- 通过读取 src 文件夹中（包含子辈）的所有 js 或 ts 类型的文件获取所有待转换的文件路径
- 然后遍历文件路径，再通过 vite 的 mode 选项传递入口文件到 vite.file.config.ts 配置中
const fs = require('fs'); const path = require('path'); const spawn = require('cross-spawn'); const srcDir = path.resolve(__dirname, '../src'); // 所有 src 文件夹包括子文件夹的 js、ts、jsx、tsx 文件路径数组 const srcFilePaths = getTargetDirFilePaths(srcDir); srcFilePaths.forEach((file) => { const fileRelativePath = path.relative(srcDir, file); spawn( 'npm', ['run', 'vite', '--', 'build', '--mode', fileRelativePath, '--outDir', 'es', '--config', './vite.file.config.ts'], { stdio: 'inherit', }, ); }); /** * 获取 src 文件夹下的所有文件 * @param {String} [targetDirPath] 目标文件夹路径 * @return {Array} 文件列表数组 */ function getTargetDirFilePaths(targetDirPath = path.resolve(__dirname, '../src')) { let fileList = []; fs.readdirSync(targetDirPath).forEach((file) => { const filePath = path.resolve(targetDirPath, file); const isDirectory = fs.statSync(filePath).isDirectory(); if (isDirectory) { fileList = fileList.concat(getTargetDirFilePaths(filePath)); } else { fileList.push(filePath); } }); return fileList .filter((f) => { if (/__tests__/.test(f)) { return false; } if (/\.d\.ts/.test(f)) { return false; } if (/\.[jt]?sx?$/.test(f)) { return true; } return false; }) .map((f) => // 兼容 windows 路径 f.replace(/\\/g, '/'), ); }第四步，创建
package/components/vite.file.config.ts文件：其中需要注意的是
rollupOptions.external字段的配置，除了less、css、svg的后缀名文件外，都不打包进输出文件。import { defineConfig } from 'vite'; import react from '@vitejs/plugin-react'; import path from 'path'; import decamelize from 'decamelize'; export const commonConfig = defineConfig({ plugins: [react()], css: { modules: { localsConvention: 'camelCaseOnly', generateScopedName: (name: string, filename: string) => { const match = filename.replace(/\\/, '/').match(/.*\/src\/(.*)\/.*\.module\..*/); if (match) { return `rabc-${decamelize(match[1], '-')}__${name}`; } return `rabc-${name}`; }, }, preprocessorOptions: { less: { javascriptEnabled: true, }, }, }, resolve: { alias: [ // fix less import by: @import ~ // less import no support webpack alias '~' · Issue #2185 · vitejs/vite { find: /^~/, replacement: '' }, ], }, }); // https://vitejs.dev/config/ export default defineConfig(({ mode }) => { return { ...commonConfig, build: { emptyOutDir: false, rollupOptions: { external: (id) => { if (id.includes('.less') || id.includes('.css') || id.includes('.svg')) { return false; } return true; }, output: [ { file: `es/${mode.replace(/\.[jt]?sx?$/, '.js')}`, indent: false, exports: 'named', format: 'es', dir: undefined, }, { file: `lib/${mode.replace(/\.[jt]?sx?$/, '.js')}`, indent: false, exports: 'named', format: 'cjs', dir: undefined, }, ], }, lib: { // mode 特殊处理为文件名 entry: path.resolve(__dirname, 'src', mode), name: 'noop', // 这里设置只有在 UMD 格式才有效，避免验证报错才设置的，在这里没用 }, minify: false, }, }; });
添加单元测试
单元测试使用 Vitest，Vitest 可共用 Vite 的配置，配置也很简单，同时兼容 Jest 的绝大部分用法。
下方的步骤基于分包 packages/components 来处理。
第一步，更新 package.json
{ "scripts": { "test": "vitest", "coverage": "vitest run --coverage" }, "devDependencies": { "happy-dom": "^6.0.2", "react-test-renderer": "^17.0.2", "vitest": "^0.18.0" } }第二步，更新 vite.config.js
配置
vitest本身，需要在 Vite 配置中添加test属性。如果你使用vite的defineConfig，还需要将 三斜线指令 写在配置文件的顶部。配置十分简单，只需要关闭 watch 和 添加 dom 执行环境。
///export default defineConfig(() => { return { ... test: { environment: 'happy-dom', watch: false, }, ... }; }); 第三步，添加
.env.test，确保环境为 test 环境。NODE_ENV=test第四步，添加测试用例
packages/components/src/__tests__/Test.spec.tsximport { expect, it } from 'vitest'; import React from 'react'; import renderer from 'react-test-renderer'; import Test from '../index'; function toJson(component: renderer.ReactTestRenderer) { const result = component.toJSON(); expect(result).toBeDefined(); return result as renderer.ReactTestRendererJSON; } it('ProContent rendered', () => { const component = renderer.create(, ); const tree = toJson(component); expect(tree).toMatchSnapshot(); });
使用 Vite 初始化 Utils 分包
其实除了业务组件，我们还会有业务 Utils 工具类的函数，我们也会沉淀工具类库和相应的文档。
得益于多包管理的方式，本人把组件库和 Utils 类库放在一起处理，在 package 中新建 utils 分包。
utils 分包和 components 分包大同小异，vite 和 package.json 配置就不细说了，可参考上方使用 Vite 创建组件分包。
创建工具函数
创建 utils/src/isNumber.ts 文件（范例）。
/**
* @param value? 检测的目标
* @param useIsFinite 是否使用 isFinite，设置为 true 时，NaN,Infinity,-Infinity 都不算 number
* @default true
* @returns true or false
* @example
* ```ts
* isNumber(3) // true
* isNumber(Number.MIN_VALUE) // true
* isNumber(Infinity) // false
* isNumber(Infinity,false) // true
* isNumber(NaN) // false
* isNumber(NaN,false) // true
* isNumber('3') // false
* ```
*/
export default function isNumber(value?: any, useIsFinite = true) {
if (typeof value !== 'number' || (useIsFinite && !isFinite(value))) {
return false;
}
return true;
}编写工具函数文档
由于工具类函数不适合使用 PropsTable 读取注释，手动编写 markdown 效率又低，本人基于微软 tsdoc 实现了一个 Docusaurus 插件。
第一步，md 文件支持直接使用 TsDoc 组件
添加 website/plugins/tsdoc.js，同时需要添加相应的依赖包，文件内容可以在这个项目 react-doc-starter 中获取。module.exports = function (context, opt = {}) { return { name: 'docusaurus-plugin-tsdoc', configureWebpack(config) { const { siteDir } = context; return { module: { rules: [ { test: /(\.mdx?)$/, include: [siteDir], use: [ { loader: require.resolve('ts-doc-webpack-loader'), options: { alias: config.resolve.alias, ...opt }, }, ], }, ], }, }; }, }; };第二步，配置
docusaurus.config.js配置 utils 文档路径为
docs/utils，sidebar 路径为./utilsSidebars，还要添加 tsdoc 插件。const config = { ... plugins: [ [ 'content-docs', /** @type {import('@docusaurus/plugin-content-docs').Options} */ ({ id: 'utils', path: 'docs/utils', routeBasePath: 'utils', editUrl: 'https://github.com/samonxian/react-doc-starter/tree/master', sidebarPath: require.resolve('./utilsSidebars.js'), }), ], './plugins/tsdoc', ], ... }; module.exports = config;第三步，添加
docs/utils/isNumber.md文件$utils别名需要在./plugins/alias和tsconfig.json中添加对应的配置。sidebar_position可以修改侧边栏同级菜单项的顺序。--- sidebar_position: 1 ---
发布组件
同 components 分包，在项目 root 根目录下运行：
$ npm run build:publish此名会运行lerna build 和 lerna publish 命令，然后安装提示进行发布即可，详细的用法可查看 lerna 命令。
部署文档
同上的部署文档。
结语
经过支持 PropsTable、CodeShow 和 TsDoc 三个便捷的组件，本人搭建的文档工具可以快速编写并生成文档。
如果对你有所帮助，可以点个赞，也可以去 Github 项目收藏一下。