> 2021.07.03-19:49 更新： > 1. 由于 docz 问题，导致部分同学无法启动项目，于是做了一次迁移，使用 dumi 作为文档站点工具，对新手更加友好 > 2. 补充文档站点部署至 Github Pages 的流程，同时配置 Github Action 自动触发构建部署 > 3. 由于维护多个平台较为困难，以上两点具体更新请前往 github blog 阅读。地址：https://github.com/worldzhao/blog/issues --- > 2020.05.21-10:30 更新： > 1. docz在windows平台存在[Bug](https://github.com/doczjs/docz/issues/1310)，暂未修复，建议使用WSL + VSCode运行本项目。 --- > 2020.05.18-10:36 更新： > 1. 部分代码可展开-优化阅读体验； > 2. 除去部分口语化表达。 --- > 2020.05.16-18:48 更新： > 1. 增加文章头图; > 2. 增加在线预览地址。 **由于维护多个平台较为困难，请前往 github blog 阅读。地址：https://github.com/worldzhao/blog/issues** **由于维护多个平台较为困难，请前往 github blog 阅读。地址：https://github.com/worldzhao/blog/issues** **由于维护多个平台较为困难，请前往 github blog 阅读。地址：https://github.com/worldzhao/blog/issues** 一些同学碰到的问题在最新文章里解决了（主要集中在 docz 和站点部署），不保证掘金文章是最新内容，也欢迎给我的 blog star。 [🚀 在线预览](https://worldzhao.github.io/react-ui-library-tutorial) 🚆 本地预览 ```bash git clone git@github.com:worldzhao/react-ui-library-tutorial.git cd react-ui-library-tutorial yarn yarn start ``` 按顺序执行完命令后，即可在 `localhost:3000` 看到以下内容： ![preview](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/c385da8e47e449148c80f2b297e36c96~tplv-k3u1fbpfcp-zoom-1.image) ## 概览本系列文章主要包含以下内容： - 项目初始化: 组件库前期开发准备工作。`eslint`/`commit lint`/`typescript`等等； - 开发阶段: 使用 [dumi](https://d.umijs.org/zh-CN) 进行开发调试以及文档编写； - 打包阶段: 输出~~`umd`~~/`cjs`/`esm`产物并支持按需加载； - 组件测试: 使用`@testing-library/react`及其相关生态进行组件测试； - 发布 npm: 编写脚本完成发布或直接使用 [np](https://www.npmjs.com/package/np) 发布； - 部署文档站点: 使用 Github Pages 以及 Github Actions 完成文档站点自动部署。如果本文帮助到了你请给[仓库](https://github.com/worldzhao/react-ui-library-tutorial) 一颗 ✨✨。如果有错误烦请在评论区指正交流，谢谢。 [仓库地址](https://github.com/worldzhao/react-ui-library-tutorial) ## 准备工作 ### 初始化项目新建一个`happy-ui`文件夹，并初始化。 ```bash mkdir happy-ui cd happy-ui npm init --y mkdir components && cd components && touch index.ts # 新建源码文件夹以及入口文件 ``` ### 代码规范此处直接使用[@umijs/fabric](https://github.com/umijs/fabric)的配置。 ```bash yarn add @umijs/fabric --dev yarn add prettier --dev # 因为@umijs/fabric没有将prettier作为依赖所以我们需要手动安装 ``` **.eslintrc.js** ```js module.exports = { extends: [require.resolve('@umijs/fabric/dist/eslint')], }; ``` **.prettierrc.js** ```js const fabric = require('@umijs/fabric'); module.exports = { ...fabric.prettier, }; ``` **.stylelintrc.js** ```js module.exports = { extends: [require.resolve('@umijs/fabric/dist/stylelint')], }; ``` 想自行配置的同学可以参考以下文章： - [Linting Your React+Typescript Project with ESLint and Prettier!](https://medium.com/@dors718/linting-your-react-typescript-project-with-eslint-and-prettier-2423170c3d42) - [使用 ESLint+Prettier 规范 React+Typescript 项目 ](https://zhuanlan.zhihu.com/p/62401626) ### Commit Lint 进行`pre-commit`代码规范检测。 ```bash yarn add husky lint-staged --dev ``` **package.json** ```json "lint-staged": { "components/**/*.ts?(x)": [ "prettier --write", "eslint --fix", "git add" ], "components/**/*.less": [ "stylelint --syntax less --fix", "git add" ] }, "husky": { "hooks": { "pre-commit": "lint-staged" } } ``` 进行 Commit Message 检测。 ```bash yarn add @commitlint/cli @commitlint/config-conventional commitizen cz-conventional-changelog --dev ``` 新增`.commitlintrc.js`写入以下内容 ```js module.exports = { extends: ['@commitlint/config-conventional'] }; ``` package.json 写入以下内容： ```json // ... "scripts": { "commit": "git-cz", } // ... "husky": { "hooks": { "commit-msg": "commitlint -E HUSKY_GIT_PARAMS", "pre-commit": "lint-staged" } }, "config": { "commitizen": { "path": "cz-conventional-changelog" } } ``` 后续使用 `yarn commit` 替代 `git commit`生成规范的 Commit Message，当然为了效率你可以选择手写，但是要符合规范。 ### TypeScript ```bash yarn add typescript --dev ``` 新建`tsconfig.json`并写入以下内容 ```json { "compilerOptions": { "baseUrl": "./", "target": "esnext", "module": "commonjs", "jsx": "react", "declaration": true, "declarationDir": "lib", "strict": true, "moduleResolution": "node", "allowSyntheticDefaultImports": true, "esModuleInterop": true, "resolveJsonModule": true }, "include": ["components", "global.d.ts"], "exclude": ["node_modules"] } ``` ### 测试在`components`文件夹下新建`alert`文件夹，目录结构如下： ``` alert ├── alert.tsx # 源文件 ├── index.ts # 入口文件 ├── interface.ts # 类型声明文件 └── style ├── index.less # 样式文件 └── index.ts # 样式文件里为什么存在一个index.ts - 按需加载样式管理样式依赖后面章节会提到 ``` 安装`React`相关依赖： ```bash yarn add react react-dom @types/react @types/react-dom --dev # 开发时依赖，宿主环境一定存在 yarn add prop-types # 运行时依赖，宿主环境可能不存在安装本组件库时一起安装 ``` > 此处依旧安装了`prop-types`这个库，因为无法保证宿主环境也使用`typescript`，从而能够进行静态检查，故使用`prop-types`保证`javascript`用户也能得到友好的运行时报错信息。 **components/alert/interface.ts** ```js export type Kind = 'info' | 'positive' | 'negative' | 'warning'; export type KindMap = Record; export interface AlertProps { /** * Set this to change alert kind * @default info */ kind?: 'info' | 'positive' | 'negative' | 'warning'; } ``` **components/alert/alter.tsx** ```jsx import React from 'react'; import t from 'prop-types'; import { AlertProps, KindMap } from './interface'; const prefixCls = 'happy-alert'; const kinds: KindMap = { info: '#5352ED', positive: '#2ED573', negative: '#FF4757', warning: '#FFA502', }; const Alert: React.FC = ({ children, kind = 'info', ...rest }) => (

{children}

); Alert.propTypes = { kind: t.oneOf(['info', 'positive', 'negative', 'warning']), }; export default Alert; ``` **components/alert/index.ts** ```js import Alert from './alert'; export default Alert; export * from './interface'; ``` **components/alert/style/index.less** ```less @popupPrefix: happy-alert; .@{popupPrefix} { padding: 20px; background: white; border-radius: 3px; color: white; } ``` **components/alert/style/index.ts** ```js import './index.less'; ``` **components/index.ts** ```js export { default as Alert } from './alert'; ``` > 此处组件参考的`docz`项目`typescript`以及`less`示例。 git 一把梭，可以看到控制台已经进行钩子检测了。 ```bash git add . yarn commit # 或 git commit -m'feat: chapter-1 准备工作' git push ``` 准备工作完成。代码可以在[仓库](https://github.com/worldzhao/react-ui-library-tutorial)的`chapter-1`分支获取，若存在与本文内容不符的地方，以`master`分支以及文章为准。 ## 开发与调试本节解决开发组件时的预览以及调试问题，顺路解决文档编写。此处选择[docz](https://github.com/doczjs/docz)来辅助预览调试。 > `docz`基于`MDX`（Markdown + JSX），可以在 Markdown 中引入 React 组件，使得一边编写文档，一边预览调试成为了可能。而且得益于 React 组件生态，我们可以像编写应用一般编写文档，不仅仅是枯燥的文字。`docz` 也内置了一些组件，比如``。 ### 安装 docz 以及自定义配置 ```bash yarn add docz --dev yarn add rimraf --dev # 清空目录的一个辅助库 ``` 增加 `npm scripts` 至 `package.json`。 ```json "scripts": { "dev": "docz dev", // 启动本地开发环境 "start": "npm run dev", // dev命令别名 "build:doc": "rimraf doc-site && docz build", // 后续会配置打包出来的文件目录名为doc-site，故每次build前删除 "preview:doc": "docz serve" // 预览文档站点 }, ``` > 注意：本节所有操作都是针对站点应用。`打包`指代文档站点打包，而非组件库。新建`doczrc.js`配置文件，并写入以下内容： **doczrc.js** ```js export default { files: './components/**/*.{md,markdown,mdx}', // 识别的文件后缀 dest: 'doc-site', // 打包出来的文件目录名 title: 'happy-ui', // 站点标题 typescript: true, // 组件源文件是通过typescript开发，需要打开此选项 }; ``` 由于使用了`less`作为样式预处理器，故需要安装 less 插件。 ```bash yarn add less gatsby-plugin-less --dev ``` 新建`gatsby-config.js`，并写入以下内容： **gatsby-config.js** ```js module.exports = { plugins: ['gatsby-theme-docz', 'gatsby-plugin-less'], }; ``` ### 编写文档新建`components/alert/index.mdx`，并写入以下内容： ```md --- name: Alert 警告提示 route: /Alert menu: 组件 --- import { Playground } from 'docz'; import Alert from './alert'; // 引入组件 import './style'; // 引入组件样式 # Alert 警告提示警告提示，展现需要关注的信息。 ## 代码演示 ### 基本用法这是一条警告提示 ## API | 属性 | 说明 | 类型 | 默认值 | | ---- | -------- | -------------------------------------------- | ------ | | kind | 警告类型 | 'info'/'positive'/'negative'/'warning'非必填 | 'info' | ``` 执行脚本命令： ```bash yarn start # or yarn dev ``` 可以在`localhost:3000`看到如下页面： ![文档站点](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/4bcb5afdcef7465287c80a0dca1d1884~tplv-k3u1fbpfcp-zoom-1.image) 现在可以在`index.mdx`中愉快地进行文档编写和调试了！ ### 优化文档编写若`代码演示`部分的`demo`较多（比如基本用法、高级用法以及各种用法等等），在组件复杂的情况下，会导致文档源文件很长难以维护。那就抽离吧。在`components/alert/`文件夹下新建`demo`文件夹，存放我们在编写文档时需要引用的 `demo`。 **components/alert/demo/1-demo-basic.tsx** ```jsx import React from 'react'; import Alert from '../alert'; import '../style'; export default () => ; ``` **components/alert/index.mdx** ```diff - import Alert from './alert'; // 引入组件 - import './style'; // 引入组件样式 + import BasicDemo from './demo/1-demo-basic'; ... - 这是一条警告提示 + ``` 这样我们就将 demo 与文档进行了分隔。预览如下： ![文档重构](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/58e2c6de977d45048781d81b87e2e9d0~tplv-k3u1fbpfcp-zoom-1.image) 等等，代码区域显示的是``，而非`demo`源码。 ``组件暂时无法支持上述形式的展示：自定义下方展示的代码，而非``内部的代码。相关讨论如下： - [Allow to override the playground's editor's code #906 ](https://github.com/doczjs/docz/pull/906) 其实第一条 `PR` 已经解决了问题，但是被关闭了，无奈。不过既然都能引入 React 组件了，在`MDX`的环境下自定义一个`Playground`组件又有何难呢，无非就是渲染组件（MDX 自带）和展示源码，简单开放的东西大家都是喜闻乐见的，就叫`HappyBox`吧。 ### 优化代码展示 #### 编写 ``组件安装依赖： ``` yarn add react-use react-tooltip react-feather react-simple-code-editor prismjs react-copy-to-clipboard raw-loader styled-components --dev ``` - [react-use](https://github.com/streamich/react-use) - 2020 年了，当然要用`hooks` - [react-simple-code-editor](https://github.com/satya164/react-simple-code-editor) - 代码展示区域 - [prismjs](https://github.com/PrismJS/prism) - 代码高亮 - [raw-loader](https://github.com/webpack-contrib/raw-loader) - 将源码转成字符串 - [react-copy-to-clipboard](https://github.com/nkbt/react-copy-to-clipboard) - 让用户爸爸们能够 copy demo 代码 - react-tooltip/react-feather 辅助组件 - styled-components 方便在文档示例中让用户看到样式，也用作文档组件的样式处理 > 这些依赖都是服务于文档站点应用，和组件库自身毫无关联。最终效果如下： ![最终效果](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/8f240790c4454ef398d8ef51e1a66937~tplv-k3u1fbpfcp-zoom-1.image) 根目录下新建`doc-comps`文件夹，存放文档中使用的一些工具组件，比如``。 **doc-comps** ``` ├── happy-box │ ├── style.ts │ └── index.tsx └── index.ts ``` **components/doc-comps/happy-box/index.tsx**

展开查看代码

```jsx import React from 'react'; import Editor from 'react-simple-code-editor'; import CopyToClipboard from 'react-copy-to-clipboard'; import { useToggle } from 'react-use'; import ReactTooltip from 'react-tooltip'; import IconCopy from 'react-feather/dist/icons/clipboard'; import IconCode from 'react-feather/dist/icons/code'; import { highlight, languages } from 'prismjs/components/prism-core'; import { StyledContainer, StyledIconWrapper } from './style'; import 'prismjs/components/prism-clike'; import 'prismjs/components/prism-javascript'; import 'prismjs/components/prism-markup'; require('prismjs/components/prism-jsx'); interface Props { code: string; title?: React.ReactNode; desc?: React.ReactNode; } export const HappyBox: React.FC = ({ code, title, desc, children }) => { const [isEditVisible, toggleEditVisible] = useToggle(false); return (

{children}

{title || '示例'}

{desc || '暂无描述'}

alert('复制成功')}>

{renderEditor()} ); function renderEditor() { if (!isEditVisible) return null; return (

{}} highlight={code => highlight(code, languages.jsx)} padding={10} className="container__editor" style={{ fontFamily: '"Fira code", "Fira Mono", monospace', fontSize: 14, }} />

); } }; export default HappyBox; ```

**components/doc-comps/happy-box/style.ts**

展开查看代码

```ts import styled from 'styled-components'; export const StyledIconWrapper = styled.div` display: flex; align-items: center; margin-left: 10px; `; export const StyledContainer = styled.div` position: relative; display: inline-block; width: 100%; margin: 0 0 16px; border: 1px solid #ebedf0; border-radius: 2px; transition: all 0.2s; .text-divider { display: table; &::before, &::after { content: ''; position: relative; display: table-cell; transform: translateY(50%); content: ''; border-top: 1px solid #e8e8e8; } &::before { top: 50%; width: 5%; } &::after { width: 95%; top: 50%; width: 95%; } & > span { display: inline-block; padding: 0 10px; font-weight: 500; font-size: 16px; white-space: nowrap; text-align: center; font-variant: tabular-nums; line-height: 1.5; } } .divider { margin: 0; background: none; border: dashed #e8e8e8; border-width: 1px 0 0; display: block; clear: both; width: 100%; min-width: 100%; height: 1px; position: relative; top: -0.06em; box-sizing: border-box; padding: 0; font-size: 14px; font-variant: tabular-nums; line-height: 1.5; list-style: none; font-feature-settings: 'tnum'; } .code-box-demo { transition: all 0.2s; padding: 42px 24px 50px; } .code-box-meta { font-size: 14px; line-height: 2; } .code-box .ant-divider { margin: 0; } .code-box-description { padding: 18px 24px 12px; } .code-box-action { height: 40px; display: flex; align-items: center; justify-content: center; font-size: 16px; } .code-box-action .anticon { margin: 0 8px; cursor: pointer; } .container_editor_area { border-top: 1px solid rgb(232, 232, 232); padding: 16px; } .container__editor { font-variant-ligatures: common-ligatures; border-radius: 3px; } .container__editor textarea { outline: 0; background-color: none; } .button { display: inline-block; padding: 0 6px; text-decoration: none; background: #000; color: #fff; } .button:hover { background: linear-gradient(45deg, #e42b66, #e2433f); } /* Syntax highlighting */ .token.comment, .token.prolog, .token.doctype, .token.cdata { color: #90a4ae; } .token.punctuation { color: #9e9e9e; } .namespace { opacity: 0.7; } .token.property, .token.tag, .token.boolean, .token.number, .token.constant, .token.symbol, .token.deleted { color: #e91e63; } .token.selector, .token.attr-name, .token.string, .token.char, .token.builtin, .token.inserted { color: #4caf50; } .token.operator, .token.entity, .token.url, .language-css .token.string, .style .token.string { color: #795548; } .token.atrule, .token.attr-value, .token.keyword { color: #3f51b5; } .token.function { color: #f44336; } .token.regex, .token.important, .token.variable { color: #ff9800; } .token.important, .token.bold { font-weight: bold; } .token.italic { font-style: italic; } .token.entity { cursor: help; } `; ```

### 相关配置 - 增加 `alias`别名，样例源码展示相对路径不够友好，让用户直接拷贝才够省心新建`gatsby-node.js`，写入以下内容以开启`alias`： ```js const path = require('path'); exports.onCreateWebpackConfig = args => { args.actions.setWebpackConfig({ resolve: { modules: [path.resolve(__dirname, '../src'), 'node_modules'], alias: { 'happy-ui/lib': path.resolve(__dirname, '../components/'), 'happy-ui/esm': path.resolve(__dirname, '../components/'), 'happy-ui': path.resolve(__dirname, '../components/'), }, }, }); }; ``` `tsconfig.json` 打包时需要忽略`demo`，避免组件库打包生成`types`时包含其中，同时增加`paths`属性用于 vscode 自动提示： **tsconfig.json** ```diff { "compilerOptions": { "baseUrl": "./", + "paths": { + "happy-ui": ["components/index.ts"], + "happy-ui/esm/*": ["components/*"], + "happy-ui/lib/*": ["components/*"] + }, "target": "esnext", "module": "commonjs", "jsx": "react", "declaration": true, "declarationDir": "lib", "strict": true, "moduleResolution": "node", "allowSyntheticDefaultImports": true, "esModuleInterop": true, "resolveJsonModule": true }, "include": ["components", "global.d.ts"], - "exclude": ["node_modules"] + "exclude": ["node_modules", "**/demo/**"] } ``` 新的问题出现了，vscode 的 alias 提示依赖 tsconfig.json，忽略 demo 文件夹后，demo 内的文件模块类型找不到声明(paths 失效)，所以不能将 demo 在 tsconfig.json 中移除： ```diff { - "exclude": ["node_modules", "**/demo/**"] + "exclude": ["node_modules"] } ``` 新建一个 tsconfig.build.json 文件： **tsconfig.build.json** ```json { "extends": "./tsconfig.json", "exclude": ["**/demo/**", "node_modules"] } ``` 后续使用 tsc 生成类型声明文件指定`tsconfig.build.json`即可。 ### 改造相关文件 **components/alert/demo/1-demo-basic.tsx** ```diff - import Alert from '../alert'; + import Alert from 'happy-ui/lib/alert'; - import '../style'; + import 'happy-ui/lib/alert/style'; ``` **components/alert/index.mdx** ```diff - import { Playground } from 'docz'; + import { HappyBox } from '../../doc-comps'; + import BasicDemoCode from '!raw-loader!./demo/1-demo-basic.tsx'; ... - - - + + + ``` > `yarn start`卡住时尝试删除根目录`.docz`文件夹，而后重新执行命令。现在可以愉快地开发组件了。代码可以在[仓库](https://github.com/worldzhao/react-ui-library-tutorial)的`chapter-2`分支获取，若存在与本文内容不符的地方，以`master`分支以及文章为准。 ## 组件库打包 **宿主环境各不相同，需要将源码进行相关处理后发布至 npm。** 明确以下目标： 1. 导出类型声明文件； 2. 导出 `umd`/`Commonjs module`/`ES module` 等 3 种形式供使用者引入； 3. 支持样式文件 `css` 引入，而非只有`less`，减少业务方接入成本； 4. 支持按需加载。 ### 导出类型声明文件既然是使用`typescript`编写的组件库，那么使用者应当享受到类型系统的好处。我们可以生成类型声明文件，并在`package.json`中定义入口，如下： **package.json** ```json { "typings": "lib/index.d.ts", // 定义类型入口文件 "scripts": { "build:types": "tsc -p tsconfig.build.json && cpr lib esm" // 执行tsc命令生成类型声明文件 } } ``` > 值得注意的是：此处使用`cpr`(需要手动安装)将`lib`的声明文件拷贝了一份，并将文件夹重命名为`esm`，用于后面存放 ES module 形式的组件。这样做的原因是保证用户手动按需引入组件时依旧可以获取自动提示。 > 最开始的方式是将声明文件单独存放在`types`文件夹，但这样只有通过'happy-ui'引入才可以获取提示，而'happy-ui/esm/xxx'和'happy-ui/lib/xxx'就无法获取提示。 **tsconfig.build.json** ```json { "extends": "./tsconfig.json", "compilerOptions": { "emitDeclarationOnly": true }, // 只生成声明文件 "exclude": ["**/__tests__/**", "**/demo/**", "node_modules", "lib", "esm"] // 排除示例、测试以及打包好的文件夹 } ``` 执行`yarn build:types`，可以发现根目录下已经生成了`lib`文件夹（`tsconfig.json`中定义的`declarationDir`字段）以及`esm`文件夹（拷贝而来），目录结构与`components`文件夹保持一致，如下： **lib** ``` ├── alert │ ├── alert.d.ts │ ├── index.d.ts │ ├── interface.d.ts │ └── style │ └── index.d.ts └── index.d.ts ``` 这样使用者引入`npm` 包时，便能得到自动提示，也能够复用相关组件的类型定义。接下来将`ts(x)`等文件处理成`js`文件。 > 需要注意的是，我们需要输出`Commonjs module`以及`ES module`两种模块类型的文件（暂不考虑`umd`），以下使用`cjs`指代`Commonjs module`，`esm`指代`ES module`。
对此有疑问的同学推荐阅读：[import、require、export、module.exports 混合详解](https://github.com/ShowJoy-com/showjoy-blog/issues/39) ### 导出 Commonjs 模块其实完全可以使用`babel`或`tsc`命令行工具进行代码编译处理（实际上很多工具库就是这样做的），但考虑到还要**样式处理及其按需加载**，我们借助 `gulp` 来串起这个流程。 #### babel 配置首先安装`babel`及其相关依赖 ```bash yarn add @babel/core @babel/preset-env @babel/preset-react @babel/preset-typescript @babel/plugin-proposal-class-properties @babel/plugin-transform-runtime --dev ``` ```bash yarn add @babel/runtime-corejs3 ``` 新建`.babelrc.js`文件，写入以下内容： **.babelrc.js** ```js module.exports = { presets: ['@babel/env', '@babel/typescript', '@babel/react'], plugins: [ '@babel/proposal-class-properties', [ '@babel/plugin-transform-runtime', { corejs: 3, helpers: true, }, ], ], }; ``` 关于`@babel/plugin-transform-runtime`与`@babel/runtime-corejs3`： - 若`helpers`选项设置为`true`，可抽离代码编译过程重复生成的 `helper` 函数（`classCallCheck`,`extends`等），减小生成的代码体积； - 若`corejs`设置为`3`，可引入不污染全局的按需`polyfill`，常用于类库编写（我更推荐：不引入`polyfill`，转而告知使用者需要引入何种`polyfill`，避免重复引入或产生冲突，后面会详细提到）。更多参见[官方文档-@babel/plugin-transform-runtime ](https://babeljs.io/docs/en/next/babel-plugin-transform-runtime) **配置目标环境** 为了避免转译浏览器原生支持的语法，新建`.browserslistrc`文件，根据适配需求，写入支持浏览器范围，作用于`@babel/preset-env`。 **.browserslistrc** ``` >0.2% not dead not op_mini all ``` 很遗憾的是，`@babel/runtime-corejs3`无法在按需引入的基础上根据目标浏览器支持程度再次减少`polyfill`的引入，参见[@babel/runtime for target environment ](https://github.com/zloirock/core-js/blob/master/docs/2019-03-19-core-js-3-babel-and-a-look-into-the-future.md#babelruntime-for-target-environment)。这意味着`@babel/runtime-corejs3` 甚至会在针对现代引擎的情况下注入所有可能的 `polyfill`：不必要地增加了最终捆绑包的大小。对于组件库（代码量可能很大），个人建议将`polyfill`的选择权交还给使用者，在宿主环境进行`polyfill`。若使用者具有兼容性要求，自然会使用`@babel/preset-env + core-js + .browserslistrc`进行全局`polyfill`，这套组合拳引入了最低目标浏览器不支持`API`的全部 `polyfill`。 > 顺带一提，业务开发中，若将`@babel/preset-env`的`useBuiltIns`选项值设置为 `usage`，同时把`node_modules`从`babel-loader`中`exclude`，会导致`babel` 无法检测到`nodes_modules`中所需要的`polyfill`。["useBuiltIns: usage" for node_modules without transpiling #9419](https://github.com/babel/babel/issues/9419)，在未支持该`issue`提到的内容之前，请将`useBuiltIns`设置为`entry`，或者不要把`node_modules`从`babel-loader`中`exclude`。所以组件库不用画蛇添足，引入多余的`polyfill`，写好文档说明，比什么都重要（就像[zent](https://github.com/youzan/zent#required-polyfills)和[antd](https://ant.design/docs/react/getting-started-cn#%E5%85%BC%E5%AE%B9%E6%80%A7)这样）。现在`@babel/runtime-corejs3`更换为`@babel/runtime`，只进行`helper`函数抽离。 ```bash yarn remove @babel/runtime-corejs3 yarn add @babel/runtime ``` **.babelrc.js** ```js module.exports = { presets: ['@babel/env', '@babel/typescript', '@babel/react'], plugins: ['@babel/plugin-transform-runtime', '@babel/proposal-class-properties'], }; ``` > `@babel/transform-runtime`的`helper`选项默认为`true`。 #### gulp 配置再来安装`gulp`相关依赖 ```bash yarn add gulp gulp-babel --dev ``` 新建`gulpfile.js`，写入以下内容： **gulpfile.js** ```js const gulp = require('gulp'); const babel = require('gulp-babel'); const paths = { dest: { lib: 'lib', // commonjs 文件存放的目录名 - 本块关注 esm: 'esm', // ES module 文件存放的目录名 - 暂时不关心 dist: 'dist', // umd文件存放的目录名 - 暂时不关心 }, styles: 'components/**/*.less', // 样式文件路径 - 暂时不关心 scripts: ['components/**/*.{ts,tsx}', '!components/**/demo/*.{ts,tsx}'], // 脚本文件路径 }; function compileCJS() { const { dest, scripts } = paths; return gulp .src(scripts) .pipe(babel()) // 使用gulp-babel处理 .pipe(gulp.dest(dest.lib)); } // 并行任务后续加入样式处理可以并行处理 const build = gulp.parallel(compileCJS); exports.build = build; exports.default = build; ``` 修改`package.json` **package.json** ```diff { - "main": "index.js", + "main": "lib/index.js", "scripts": { ... + "clean": "rimraf lib esm dist", + "build": "npm run clean && npm run build:types && gulp", ... }, } ``` 执行`yarn build`，得到如下内容： **lib** ``` ├── alert │ ├── alert.js │ ├── index.js │ ├── interface.js │ └── style │ └── index.js └── index.js ``` 观察编译后的源码，可以发现：诸多`helper`方法已被抽离至`@babel/runtime`中，模块导入导出形式也是`commonjs`规范。 **lib/alert/alert.js** ![lib/alert/alert.js](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/88a6a40faa544cb58cab3def3ed2cef5~tplv-k3u1fbpfcp-zoom-1.image) ### 导出 ES module 生成`ES module`可以更好地进行[tree shaking](https://webpack.docschina.org/guides/tree-shaking/)，基于上一步的`babel`配置，更新以下内容： 1. 配置`@babel/preset-env`的`modules`选项为`false`，关闭模块转换； 2. 配置`@babel/plugin-transform-runtime`的`useESModules`选项为`true`，使用`ES module`形式引入`helper`函数。 **.babelrc.js** ```js module.exports = { presets: [ [ '@babel/env', { modules: false, // 关闭模块转换 }, ], '@babel/typescript', '@babel/react', ], plugins: [ '@babel/proposal-class-properties', [ '@babel/plugin-transform-runtime', { useESModules: true, // 使用esm形式的helper }, ], ], }; ``` 目标达成，我们再使用环境变量区分`esm`和`cjs`（执行任务时设置对应的环境变量即可），最终`babel`配置如下： **.babelrc.js** ```js module.exports = { presets: ['@babel/env', '@babel/typescript', '@babel/react'], plugins: ['@babel/plugin-transform-runtime', '@babel/proposal-class-properties'], env: { esm: { presets: [ [ '@babel/env', { modules: false, }, ], ], plugins: [ [ '@babel/plugin-transform-runtime', { useESModules: true, }, ], ], }, }, }; ``` 接下来修改`gulp`相关配置，抽离`compileScripts`任务，增加`compileESM`任务。 **gulpfile.js** ```js // ... /** * 编译脚本文件 * @param {string} babelEnv babel环境变量 * @param {string} destDir 目标目录 */ function compileScripts(babelEnv, destDir) { const { scripts } = paths; // 设置环境变量 process.env.BABEL_ENV = babelEnv; return gulp .src(scripts) .pipe(babel()) // 使用gulp-babel处理 .pipe(gulp.dest(destDir)); } /** * 编译cjs */ function compileCJS() { const { dest } = paths; return compileScripts('cjs', dest.lib); } /** * 编译esm */ function compileESM() { const { dest } = paths; return compileScripts('esm', dest.esm); } // 串行执行编译脚本任务（cjs,esm）避免环境变量影响 const buildScripts = gulp.series(compileCJS, compileESM); // 整体并行执行任务 const build = gulp.parallel(buildScripts); // ... ``` 执行`yarn build`，可以发现生成了`lib`/`esm`两个文件夹，观察`esm`目录，结构同`lib`一致，js 文件都是以`ES module`模块形式导入导出。 **esm/alert/alert.js** ![esm/alert/alert.js](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/c412d4c34cf549b5836fd8e4db4a5969~tplv-k3u1fbpfcp-zoom-1.image) 别忘了给`package.json`增加相关入口。 **package.json** ```diff { + "module": "esm/index.js" } ``` ### 处理样式文件 #### 拷贝 less 文件我们会将`less`文件包含在`npm`包中，用户可以通过`happy-ui/lib/alert/style/index.js`的形式按需引入`less`文件，此处可以直接将 less 文件拷贝至目标文件夹。在`gulpfile.js`中新建`copyLess`任务。 **gulpfile.js** ```js // ... /** * 拷贝less文件 */ function copyLess() { return gulp .src(paths.styles) .pipe(gulp.dest(paths.dest.lib)) .pipe(gulp.dest(paths.dest.esm)); } const build = gulp.parallel(buildScripts, copyLess); // ... ``` 观察`lib`目录，可以发现 `less` 文件已被拷贝至`alert/style`目录下。 **lib** ``` ├── alert │ ├── alert.js │ ├── index.js │ ├── interface.js │ └── style │ ├── index.js │ └── index.less # less文件 └── index.js ``` 可能有些同学已经发现问题：若使用者没有使用`less`预处理器，使用的是`sass`方案甚至原生`css`方案，那现有方案就搞不定了。经分析，有以下 4 种预选方案： 1. 告知业务方增加`less-loader`。会导致业务方使用成本增加； 2. 打包出一份完整的 `css` 文件，进行**全量**引入。无法进行按需引入； 3. `css in js`方案； 4. 提供一份`style/css.js`文件，引入组件 `css`样式依赖，而非 `less` 依赖，组件库底层抹平差异。重点看一看方案 3 以及方案 4。 `css in js`除了赋予样式编写更多的可能性之外，在编写第三方组件库时更是利器。如果我们写一个`react-use`这种`hooks`工具库，不涉及到样式，只需要在`package.json`中设置`sideEffects`为`false`，业务方使用 webpack 进行打包时，只会打包被使用到的 hooks（优先使用 ES module）。入口文件`index.js`中导出的但未被使用的其他 hooks 会被`tree shaking`，第一次使用这个库的时候我很好奇，为什么没有按需引入的使用方式，结果打包分析时我傻了，原来人家天生支持按需引入。可能常用的`antd`以及`lodash`都要配一配，导致产生了惯性思维。回到正题。如果将样式使用`javascript`来编写，在某种维度上讲，组件库和工具库一致了，配好`sideEffects`，自动按需引入，美滋滋。而且每个组件都与自己的样式绑定，不需要业务方或组件开发者去**维护样式依赖**，什么是样式依赖，后面会讲到。缺点： 1. 样式无法单独缓存； 2. styled-components 自身体积较大； 3. 复写组件样式需要使用属性选择器或者使用`styled-components`自带方法。需要看取舍了，偷偷说一句`styled-components`做主题定制也极其方便。方案 4 是`antd`使用的这种方案。在搭建组件库的过程中，有一个问题困扰了我很久：为什么需要`alert/style/index.js`引入`less`文件或`alert/style/css.js`引入`css`文件？答案是**管理样式依赖**。因为我们的组件是没有引入样式文件的，需要使用者去手动引入。假设存在以下场景：使用者引入`