概覽
本文包含以下內容:
- prepare: 元件庫前期開發準備工作。
eslint
/commit lint
/typescript
等等; - dev: 使用docz進行開發除錯以及文件編寫;
- build:
/umd
cjs
/esm
、types、polyfill 以及按需載入; - test: 元件測試;
- release: 元件庫釋出流程;
- deploy: 使用now部署文件站點,待補充;
- other: 使用plop.js快速建立元件模板。
如果本文幫助到了你請給倉庫 一顆 ✨✨。
如果有錯誤煩請在評論區指正交流,謝謝。
準備工作
初始化專案
新建一個happy-ui
資料夾,並初始化。
mkdir happy-ui
cd happy-ui
npm init --y
mkdir components && cd components && touch index.ts # 新建原始碼資料夾以及入口檔案
程式碼規範
此處直接使用@umijs/fabric的配置。
yarn add @umijs/fabric --dev
yarn add prettier --dev # 因為@umijs/fabric沒有將prettier作為依賴 所以我們需要手動安裝
.eslintrc.js
module.exports = {
extends: [require.resolve('@umijs/fabric/dist/eslint')],
};
.prettierrc.js
const fabric = require('@umijs/fabric');
module.exports = {
...fabric.prettier,
};
.stylelintrc.js
module.exports = {
extends: [require.resolve('@umijs/fabric/dist/stylelint')],
};
想自行配置的同學可以參考以下文章:
- Linting Your React+Typescript Project with ESLint and Prettier!
- 使用 ESLint+Prettier 規範 React+Typescript 專案
Commit Lint
進行pre-commit
程式碼規範檢測。
yarn add husky lint-staged --dev
package.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 檢測。
yarn add @commitlint/cli @commitlint/config-conventional commitizen cz-conventional-changelog --dev
新增.commitlintrc.js
寫入以下內容
module.exports = { extends: ['@commitlint/config-conventional'] };
package.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
yarn add typescript --dev
新建tsconfig.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
相關依賴:
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
export type Kind = 'info' | 'positive' | 'negative' | 'warning';
export type KindMap = Record<Kind, string>;
export interface AlertProps {
/**
* Set this to change alert kind
* @default info
*/
kind?: 'info' | 'positive' | 'negative' | 'warning';
}
components/alert/alter.tsx
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<AlertProps> = ({ children, kind = 'info', ...rest }) => (
<div
className={prefixCls}
style={{
background: kinds[kind],
}}
{...rest}
>
{children}
</div>
);
Alert.propTypes = {
kind: t.oneOf(['info', 'positive', 'negative', 'warning']),
};
export default Alert;
components/alert/index.ts
import Alert from './alert';
export default Alert;
export * from './interface';
components/alert/style/index.less
@popupPrefix: happy-alert;
.@{popupPrefix} {
padding: 20px;
background: white;
border-radius: 3px;
color: white;
}
components/alert/style/index.ts
import './index.less';
components/index.ts
export { default as Alert } from './alert';
此處元件參考的docz
專案typescript
以及less
示例。
git 一把梭,可以看到控制檯已經進行鉤子檢測了。
git add .
yarn commit # 或 git commit -m'feat: chapter-1 準備工作'
git push
準備工作完成。程式碼可以在倉庫的chapter-1
分支獲取,若存在與本文內容不符的地方,以master
分支以及文章為準。
開發與除錯
本節解決開發元件時的預覽以及除錯問題,順路解決文件編寫。
此處選擇docz來輔助預覽除錯。
docz
基於MDX
(Markdown + JSX),可以在 Markdown 中引入 React 元件,使得一邊編寫文件,一邊預覽除錯成為了可能。而且得益於 React 元件生態,我們可以像編寫應用一般編寫文件,不僅僅是枯燥的文字。docz
也內建了一些元件,比如<Playground>
。
安裝 docz 以及自定義配置
yarn add docz --dev
yarn add rimraf --dev # 清空目錄的一個輔助庫
增加 npm scripts
至 package.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
export default {
files: './components/**/*.{md,markdown,mdx}', // 識別的檔案字尾
dest: 'doc-site', // 打包出來的檔案目錄名
title: 'happy-ui', // 站點標題
typescript: true, // 元件原始檔是通過typescript開發,需要開啟此選項
};
由於使用了less
作為樣式前處理器,故需要安裝 less 外掛。
yarn add less gatsby-plugin-less --dev
新建gatsby-config.js
,並寫入以下內容:
gatsby-config.js
module.exports = {
plugins: ['gatsby-theme-docz', 'gatsby-plugin-less'],
};
編寫文件
新建components/alert/index.mdx
,並寫入以下內容:
---
name: Alert 警告提示
route: /Alert
menu: 元件
---
import { Playground } from 'docz'; import Alert from './alert'; // 引入元件 import './style'; // 引入元件樣式
# Alert 警告提示
警告提示,展現需要關注的資訊。
## 程式碼演示
### 基本用法
<Playground>
<Alert kind="warning">這是一條警告提示</Alert>
</Playground>
## API
| 屬性 | 說明 | 型別 | 預設值 |
| ---- | -------- | -------------------------------------------- | ------ |
| kind | 警告型別 | 'info'/'positive'/'negative'/'warning'非必填 | 'info' |
執行指令碼命令:
yarn start # or yarn dev
可以在localhost:3000
看到如下頁面 :
現在可以在index.mdx
中愉快地進行文件編寫和除錯了!
倘若本文到了這裡就結束(其實也可以結束了(_^▽^_)
),那我只是官方文件的翻譯復讀機罷了,有興趣的同學可以繼續向下看。
優化文件編寫
如果程式碼演示
部分的demo
較多(比如基本用法、高階用法以及各種用法等等),在元件複雜的情況下(畢竟<Alert/>
著實太簡單了),會導致文件很長難以維護,你到底是在寫文件呢還是在寫程式碼呢?
那就抽離吧。
在components/alert/
資料夾下新建demo
資料夾,存放我們在編寫文件時需要引用的 demo
。
components/alert/demo/1-demo-basic.tsx
import React from 'react';
import Alert from '../alert';
import '../style';
export default () => <Alert kind="warning"></Alert>;
components/alert/index.mdx
- import Alert from './alert'; // 引入元件
- import './style'; // 引入元件樣式
+ import BasicDemo from './demo/1-demo-basic';
...
<Playground>
- <Alert kind="warning">這是一條警告提示</Alert>
+ <BasicDemo />
</Playground>
這樣我們就將 demo 與文件進行了分隔。預覽如下:
等等,下面顯示的是<BasicDemo />
,而非demo
原始碼。
<Playground />
元件暫時無法支援上述形式的展示:自定義下方展示的程式碼,而非<Playground />
內部的程式碼。相關討論如下:
其實第一條 PR
已經解決了問題,但是被關閉了,無奈。
不過既然都能引入 React 元件了,在MDX
的環境下自定義一個Playground
元件又有何難呢,無非就是渲染元件(MDX 自帶)和展示原始碼,簡單開放的東西大家都是喜聞樂見的,就叫HappyBox
吧。
優化程式碼展示
編寫 <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 - 2020 年了,當然要用
hooks
- react-simple-code-editor - 程式碼展示區域
- prismjs - 程式碼高亮
- raw-loader - 將原始碼轉成字串
- react-copy-to-clipboard - 讓使用者爸爸們能夠 copy demo 程式碼
- react-tooltip/react-feather 輔助元件
- styled-components 方便在文件示例中讓使用者看到樣式,也用作文件元件的樣式處理
這些依賴都是服務於文件站點應用,和元件庫自身毫無關聯。
最終效果如下:
根目錄下新建doc-comps
資料夾,存放文件中使用的一些工具元件,比如<HappyBox />
。
doc-comps
├── happy-box
│ ├── style.ts
│ └── index.tsx
└── index.ts
components/doc-comps/happy-box/index.tsx
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<Props> = ({ code, title, desc, children }) => {
const [isEditVisible, toggleEditVisible] = useToggle(false);
return (
<StyledContainer>
<section className="code-box-demo"> {children}</section>
<section className="code-box-meta">
<div className="text-divider">
<span>{title || '示例'}</span>
</div>
<div className="code-box-description">
<p>{desc || '暫無描述'}</p>
</div>
<div className="divider" />
<div className="code-box-action">
<CopyToClipboard text={code} onCopy={() => alert('複製成功')}>
<IconCopy data-place="top" data-tip="複製程式碼" />
</CopyToClipboard>
<StyledIconWrapper onClick={toggleEditVisible}>
<IconCode data-place="top" data-tip={isEditVisible ? '收起程式碼' : '顯示程式碼'} />
</StyledIconWrapper>
</div>
</section>
{renderEditor()}
<ReactTooltip />
</StyledContainer>
);
function renderEditor() {
if (!isEditVisible) return null;
return (
<div className="container_editor_area">
<Editor
readOnly
value={code}
onValueChange={() => {}}
highlight={code => highlight(code, languages.jsx)}
padding={10}
className="container__editor"
style={{
fontFamily: '"Fira code", "Fira Mono", monospace',
fontSize: 14,
}}
/>
</div>
);
}
};
export default HappyBox;
相關配置變更
- 增加
alias
別名,樣例原始碼展示相對路徑不夠友好,讓使用者直接拷貝才夠省心
新建gatsby-node.js
,寫入以下內容以開啟alias
:
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
{
"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 中移除:
{
- "exclude": ["node_modules", "**/demo/**"]
+ "exclude": ["node_modules"]
}
新建一個 tsconfig.build.json 檔案:
tsconfig.build.json
{
"extends": "./tsconfig.json",
"exclude": ["**/demo/**", "node_modules"]
}
後續使用 tsc 生成型別宣告檔案指定tsconfig.build.json
即可。
改造相關檔案
components/alert/demo/1-demo-basic.tsx
- import Alert from '../alert';
+ import Alert from 'happy-ui/lib/alert';
- import '../style';
+ import 'happy-ui/lib/alert/style';
components/alert/index.mdx
- import { Playground } from 'docz';
+ import { HappyBox } from '../../doc-comps';
+ import BasicDemoCode from '!raw-loader!./demo/1-demo-basic.tsx';
...
- <Playground>
- <BasicDemo />
- </Playground>
+ <HappyBox code={BasicDemoCode} title="基本用法" desc="使用kind控制Alert型別">
+ <BasicDemo />
+ </HappyBox>
yarn start
卡住時嘗試刪除根目錄.docz
資料夾,而後重新執行命令。
現在可以愉快地開發元件了。程式碼可以在倉庫的chapter-2
分支獲取,若存在與本文內容不符的地方,以master
分支以及文章為準。
元件庫打包
宿主環境各不相同,需要將原始碼進行相關處理後釋出至 npm。
明確以下目標:
- 匯出型別宣告檔案
- 匯出
umd
/Commonjs module
/ES module
等 3 種形式供使用者引入 - 支援樣式檔案
css
引入,而非只有less
- 支援按需載入
匯出型別宣告檔案
既然是使用typescript
編寫的元件庫,那麼使用者應當享受到型別系統的好處。
我們可以生成型別宣告檔案,並在package.json
中定義入口,如下:
package.json
{
"typings": "types/index.d.ts", // 定義型別入口檔案
"scripts": {
"build:types": "tsc -p tsconfig.build.json" // 執行tsc命令生成型別宣告檔案
}
}
tsconfig.build.json
{
"extends": "./tsconfig.json",
"compilerOptions": { "emitDeclarationOnly": true }, // 只生成宣告檔案
"exclude": ["**/__tests__/**", "**/demo/**", "node_modules", "lib", "esm", "types"] // 排除示例、測試以及打包好的資料夾
}
執行yarn build:types
,可以發現根目錄下已經生成了lib
資料夾(tsconfig.json
中定義的outDir
欄位),目錄結構與components
資料夾保持一致,如下:
types
├── 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
。<br/> 對此有疑問的同學推薦閱讀:import、require、export、module.exports 混合詳解
匯出 Commonjs 模組
其實完全可以使用babel
或tsc
命令列工具進行程式碼編譯處理(實際上很多工具庫就是這樣做的),但考慮到還要處理樣式及其按需載入,我們藉助 gulp
來串起這個流程。
babel 配置
首先安裝babel
及其相關依賴
yarn add @babel/core @babel/preset-env @babel/preset-react @babel/preset-typescript @babel/plugin-proposal-class-properties @babel/plugin-transform-runtime --dev
yarn add @babel/runtime-corejs3
新建.babelrc.js
檔案,寫入以下內容:
.babelrc.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
配置目標環境
為了避免轉譯瀏覽器原生支援的語法,新建.browserslistrc
檔案,根據適配需求,寫入支援瀏覽器範圍,作用於@babel/preset-env
。
.browserslistrc
>0.2%
not dead
not op_mini all
很遺憾的是,@babel/runtime-corejs3
無法在按需引入的基礎上根據目標瀏覽器支援程度再次減少polyfill
的引入,參見@babel/runtime 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
掉的同學可能想要這個特性:"useBuiltIns: usage" for node_modules without transpiling #9419,在未支援該issue
提到的內容之前,還是乖乖地將useBuiltIns
設定為entry
,或者不要把node_modules
從babel-loader
中exclude
。
所以元件庫不用畫蛇添足,引入多餘的polyfill
,寫好文件說明,比什麼都重要(就像zent和antd這樣)。
現在@babel/runtime-corejs3
更換為@babel/runtime
,只進行helper
函式抽離。
yarn remove @babel/runtime-corejs3
yarn add @babel/runtime
.babelrc.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
相關依賴
yarn add gulp gulp-babel --dev
新建gulpfile.js
,寫入以下內容:
gulpfile.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
{
- "main": "index.js",
+ "main": "lib/index.js",
"scripts": {
...
+ "clean": "rimraf types 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
匯出 ES module
生成ES module
可以更好地進行tree shaking,基於上一步的babel
配置,更新以下內容:
- 配置
@babel/preset-env
的modules
選項為false
,關閉模組轉換; - 配置
@babel/plugin-transform-runtime
的useESModules
選項為true
,使用ES module
形式引入helper
函式。
.babelrc.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
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
// ...
/**
* 編譯指令碼檔案
* @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
,可以發現生成了types
/lib
/esm
三個資料夾,觀察esm
目錄,結構同lib
/types
一致,js 檔案都是以ES module
模組形式匯入匯出。
esm/alert/alert.js
別忘了給package.json
增加相關入口。
package.json
{
+ "module": "esm/index.js"
}
處理樣式檔案
拷貝 less 檔案
我們會將less
檔案包含在npm
包中,使用者可以通過happy-ui/lib/alert/style/index.js
的形式按需引入less
檔案,此處可以直接將 less 檔案拷貝至目標資料夾。
在gulpfile.js
中新建copyLess
任務。
gulpfile.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
方案,那現有方案就搞不定了。經分析,有以下 3 種預選方案:
- 告知使用者增加
less-loader
; - 打包出一份完整的
css
檔案,進行全量引入; - 單獨提供一份
style/css.js
檔案,引入的是元件css
樣式檔案依賴,而非less
依賴,元件庫底層抹平差異; - 使用
css in js
方案。
方案 1 會導致業務方使用成本增加。
方案 2 無法進行按需引入。
方案 4 需要詳細聊聊。
css in js
除了賦予樣式編寫更多的可能性之外,在編寫第三方元件庫時更是利器。
如果我們寫一個react-use
這種hooks
工具庫,不涉及到樣式,只需要在package.json
中設定sideEffects
為false
,業務方使用 webpack 進行打包時,只會打包被使用到的 hooks(優先使用 ES module)。
入口檔案index.js
中匯出的但未被使用的其他 hooks 會被tree shaking
,第一次使用這個庫的時候我很好奇,為什麼沒有按需引入的使用方式,結果打包分析時我傻了,原來人家天生支援按需引入。
可能常用的antd
以及lodash
都要配一配,導致產生了慣性思維。
回到正題。如果將樣式使用javascript
來編寫,在某種維度上講,元件庫和工具庫一致了,配好sideEffects
,自動按需引入,美滋滋。
而且每個元件都與自己的樣式繫結,不需要業務方或元件開發者去維護樣式依賴,什麼是樣式依賴,後面會講到。
缺點:
- 樣式無法單獨快取;
- styled-components 自身體積較大;
- 複寫元件樣式需要使用屬性選擇器或者使用
styled-components
,麻煩了點。
需要看取捨了,偷偷說一句styled-components
做主題定製也極其方便。
方案 3 是antd
使用的這種方案。
在搭建元件庫的過程中,有一個問題困擾了我很久:為什麼需要alert/style/index.js
引入less
檔案或alert/style/css.js
引入css
檔案?
答案是管理樣式依賴。
因為我們的元件是沒有引入樣式檔案的,需要使用者去手動引入。
假設存在以下場景:引入<Button />
,<Button />
依賴了<Icon />
,使用者需要手動去引入呼叫的元件的樣式(<Button />
)及其依賴的元件樣式(<Icon />
),遇到複雜元件極其麻煩,所以元件庫開發者可以提供一份這樣的js
檔案,使用者手動引入這個js
檔案,就能引入對應元件及其依賴元件的樣式。
那麼問題又來了,為什麼元件不能自己去import './index.less'
呢?
可以,不過業務方要配置less-loader
,什麼,業務方不想配,要你import './index.css'
??
可以,業務方爽了,元件開發方不爽。
所以我們要找一個大家都爽的方案:
- 開發方能夠開心的使用前處理器;
- 業務方不需要額外的使用成本。
答案就是css in js單獨提供一份style/css.js
檔案,引入的是元件 css
樣式檔案依賴,而非 less
依賴,元件庫底層抹平差異。
之前瞭解到father可以在打包的時候將index.less
轉成index.css
,這倒是個好法子,但是一些重複引入的樣式模組(比如動畫樣式),會被重複打包,不知道有沒有好的解決方案。
生成 css 檔案
安裝相關依賴。
yarn add gulp-less gulp-autoprefixer gulp-cssnano --dev
將less
檔案生成對應的css
檔案,在gulpfile.js
中增加less2css
任務。
// ...
/**
* 生成css檔案
*/
function less2css() {
return gulp
.src(paths.styles)
.pipe(less()) // 處理less檔案
.pipe(autoprefixer()) // 根據browserslistrc增加字首
.pipe(cssnano({ zindex: false, reduceIdents: false })) // 壓縮
.pipe(gulp.dest(paths.dest.lib))
.pipe(gulp.dest(paths.dest.esm));
}
const build = gulp.parallel(buildScripts, copyLess, less2css);
// ...
執行yarn build
,元件style
目錄下已經存在css
檔案了。
接下來我們需要一個alert/style/css.js
來幫使用者引入css
檔案。
生成 css.js
此處參考antd-tools的實現方式:在處理scripts
任務中,截住style/index.js
,生成style/css.js
,並通過正則將引入的less
檔案字尾改成css
。
安裝相關依賴。
yarn add through2 --dev
gulpfile.js
// ...
/**
* 編譯指令碼檔案
* @param {*} babelEnv babel環境變數
* @param {*} destDir 目標目錄
*/
function compileScripts(babelEnv, destDir) {
const { scripts } = paths;
process.env.BABEL_ENV = babelEnv;
return gulp
.src(scripts)
.pipe(babel()) // 使用gulp-babel處理
.pipe(
through2.obj(function z(file, encoding, next) {
this.push(file.clone());
// 找到目標
if (file.path.match(/(\/|\\)style(\/|\\)index\.js/)) {
const content = file.contents.toString(encoding);
file.contents = Buffer.from(cssInjection(content)); // 檔案內容處理
file.path = file.path.replace(/index\.js/, 'css.js'); // 檔案重新命名
this.push(file); // 新增該檔案
next();
} else {
next();
}
}),
)
.pipe(gulp.dest(destDir));
}
// ...
cssInjection
的實現:
gulpfile.js
/**
* 當前元件樣式 import './index.less' => import './index.css'
* 依賴的其他元件樣式 import '../test-comp/style' => import '../test-comp/style/css.js'
* 依賴的其他元件樣式 import '../test-comp/style/index.js' => import '../test-comp/style/css.js'
* @param {string} content
*/
function cssInjection(content) {
return content
.replace(/\/style\/?'/g, "/style/css'")
.replace(/\/style\/?"/g, '/style/css"')
.replace(/\.less/g, '.css');
}
再進行打包,可以看見元件style
目錄下生成了css.js
檔案,引入的也是上一步less
轉換而來的css
檔案。
lib/alert
├── alert.js
├── index.js
├── interface.js
└── style
├── css.js # 引入index.css
├── index.css
├── index.js
└── index.less
按需載入
在 package.json 中增加sideEffects
屬性,配合ES module
達到tree shaking
效果(將樣式依賴檔案標註為side effects
,避免被誤刪除)。
// ...
"sideEffects": [
"dist/*",
"esm/**/style/*",
"lib/**/style/*",
"*.less"
],
// ...
使用以下方式引入,可以做到js
部分的按需載入,但需要手動引入樣式:
import { Alert } from 'happy-ui';
import 'happy-ui/esm/alert/style';
也可以使用以下方式引入:
import Alert from 'happy-ui/esm/alert'; // or import Alert from 'happy-ui/lib/alert';
import 'happy-ui/esm/alert/style'; // or import Alert from 'happy-ui/lib/alert';
以上引入樣式檔案的方式不太優雅,直接入口處引入全量樣式檔案又和按需載入的本意相去甚遠。
使用者可以藉助babel-plugin-import來進行輔助,減少程式碼編寫量(說好的不加入其他使用成本的呢~)。
import { Alert } from 'happy-ui';
⬇️
import Alert from 'happy-ui/lib/alert';
import 'happy-ui/lib/alert/style';
生成 umd
沒用上,這一塊標記為 todo 吧。
本節程式碼可以在倉庫的chapter-3
分支獲取,若存在與本文內容不符的地方,以master
分支以及文章為準。
元件測試
與軟體操作行為越接近的測試,越能給予你信心。
本節主要講述如何在元件庫中引入jest以及@testing-library/react,而不會深入單元測試的學習。
如果你對下列問題感興趣:
- What-單元測試是什麼?
- Why-為什麼要寫單元測試?
- How-編寫單元測試的最佳實踐?
那麼可以看看以下文章:
-
Test React apps with React Testing Library:通過一個
<Counter />
的例子延伸,闡述了選擇React Testing Library
而非Enzyme
的理由,並對其進行了一些入門教學; -
React Testing Library:
@testing-library/react
的官方文件,該庫提供的 API 在某個程度上就是在指引開發者進行單元測試的最佳實踐; -
React Testing Library-examples:
@testing-library/react
的一些例項,提供了各種常見場景的測試; - React 單元測試策略及落地:如標題所示,值得一看。
相關配置
安裝依賴:
yarn add jest ts-jest @testing-library/react @testing-library/jest-dom identity-obj-proxy @types/jest @types/testing-library__react --dev
- jest: JavaScript 測試框架,專注於簡潔明快;
-
ts-jest:為
TypeScript
編寫jest
測試用例提供支援; -
@testing-library/react:簡單而完整的
React DOM
測試工具,鼓勵良好的測試實踐; -
@testing-library/jest-dom:自定義的
jest
匹配器(matchers
),用於測試DOM
的狀態(即為jest
的except
方法返回值增加更多專注於DOM
的matchers
); -
identity-obj-proxy:一個工具庫,此處用來
mock
樣式檔案。
新建jest.config.js
,並寫入相關配置,更多配置可參考jest 官方文件-配置,只看幾個常用的就可以。
jest.config.js
module.exports = {
verbose: true,
roots: ['<rootDir>/components'],
moduleNameMapper: {
'\\.(css|less|scss)$': 'identity-obj-proxy',
'^components$': '<rootDir>/components/index.tsx',
'^components(.*)$': '<rootDir>/components/$1',
},
testRegex: '(/test/.*|\\.(test|spec))\\.(ts|tsx|js)$',
moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx'],
testPathIgnorePatterns: ['/node_modules/', '/lib/', '/esm/', '/dist/'],
preset: 'ts-jest',
testEnvironment: 'jsdom',
};
修改package.json
,增加測試相關命令,並且程式碼提交前,跑測試用例,如下:
package.json
"scripts": {
...
+ "test": "jest", # 執行jest
+ "test:watch": "jest --watch", # watch模式下執行
+ "test:coverage": "jest --coverage", # 生成測試覆蓋率報告
+ "test:update": "jest --updateSnapshot" # 更新快照
},
...
"lint-staged": {
"components/**/*.ts?(x)": [
"prettier --write",
"eslint --fix",
+ "jest --bail --findRelatedTests",
"git add"
],
...
}
修改gulpfile.js
以及tsconfig.json
,避免打包時,把測試檔案一併處理了。
gulpfile.js
const paths = {
...
- scripts: ['components/**/*.{ts,tsx}', '!components/**/demo/*.{ts,tsx}'],
+ scripts: [
+ 'components/**/*.{ts,tsx}',
+ '!components/**/demo/*.{ts,tsx}',
+ '!components/**/__tests__/*.{ts,tsx}',
+ ],
};
tsconfig.json
{
- "exclude": ["components/**/demo"]
+ "exclude": ["components/**/demo", "components/**/__tests__"]
}
編寫測試用例
<Alert />
比較簡單,此處只作示例用,簡單進行一下快照測試。
在對應元件的資料夾下新建__tests__
資料夾,用於存放測試檔案,其內新建index.test.tsx
檔案,寫入以下測試用例:
components/alert/tests/index.test.tsx
import React from 'react';
import { render } from '@testing-library/react';
import Alert from '../alert';
describe('<Alert />', () => {
test('should render default', () => {
const { container } = render(<Alert>default</Alert>);
expect(container).toMatchSnapshot();
});
test('should render alert with type', () => {
const kinds: any[] = ['info', 'warning', 'positive', 'negative'];
const { getByText } = render(
<>
{kinds.map(k => (
<Alert kind={k} key={k}>
{k}
</Alert>
))}
</>,
);
kinds.forEach(k => {
expect(getByText(k)).toMatchSnapshot();
});
});
});
更新一下快照:
yarn test:update
可以看見同級目錄下新增了一個__snapshots__
資料夾,裡面存放對應測試用例的快照檔案。
再執行測試用例:
yarn test
可以發現我們通過了測試用例。。。額,這裡當然能通過,主要是後續我們進行迭代重構時,都會重新執行測試用例,與最近的一次快照進行比對,如果與快照不一致(結構發生了改變),那麼相應的測試用例就無法通過。
對於快照測試,褒貶不一,這個例子也著實簡單得很,甚至連擴充套件的 jest-dom
提供的 matchers
都沒用上。
如何編寫優秀的測試用例,我也是一個新手,只能說多看多寫多嘗試,前面推薦的文章很不錯。
本節程式碼可以在倉庫的chapter-4
分支獲取,若存在與本文內容不符的地方,以master
分支以及文章為準。
標準化釋出流程
本節主要是講解如何通過一行命令完成以下六點內容:
- 版本更新
- 生成 CHANGELOG
- 推送至 git 倉庫
- 元件庫打包
- 釋出至 npm
- 打 tag 並推送至 git
如果你不想程式碼,很好,用np(如果我一開始就知道這個工具,我也不會去寫程式碼,我真傻,真的)。
package.json
"scripts": {
+ "release": "ts-node ./scripts/release.ts"
},
直接甩程式碼吧,實在不復雜。
/* eslint-disable import/no-extraneous-dependencies,@typescript-eslint/camelcase, no-console */
import inquirer from 'inquirer';
import fs from 'fs';
import path from 'path';
import child_process from 'child_process';
import util from 'util';
import chalk from 'chalk';
import semverInc from 'semver/functions/inc';
import { ReleaseType } from 'semver';
import pkg from '../package.json';
const exec = util.promisify(child_process.exec);
const run = async (command: string) => {
console.log(chalk.green(command));
await exec(command);
};
const currentVersion = pkg.version;
const getNextVersions = (): { [key in ReleaseType]: string | null } => ({
major: semverInc(currentVersion, 'major'),
minor: semverInc(currentVersion, 'minor'),
patch: semverInc(currentVersion, 'patch'),
premajor: semverInc(currentVersion, 'premajor'),
preminor: semverInc(currentVersion, 'preminor'),
prepatch: semverInc(currentVersion, 'prepatch'),
prerelease: semverInc(currentVersion, 'prerelease'),
});
const timeLog = (logInfo: string, type: 'start' | 'end') => {
let info = '';
if (type === 'start') {
info = `=> 開始任務:${logInfo}`;
} else {
info = `✨ 結束任務:${logInfo}`;
}
const nowDate = new Date();
console.log(
`[${nowDate.toLocaleString()}.${nowDate
.getMilliseconds()
.toString()
.padStart(3, '0')}] ${info}
`,
);
};
/**
* 獲取下一次版本號
*/
async function prompt(): Promise<string> {
const nextVersions = getNextVersions();
const { nextVersion } = await inquirer.prompt([
{
type: 'list',
name: 'nextVersion',
message: `請選擇將要釋出的版本 (當前版本 ${currentVersion})`,
choices: (Object.keys(nextVersions) as Array<ReleaseType>).map(level => ({
name: `${level} => ${nextVersions[level]}`,
value: nextVersions[level],
})),
},
]);
return nextVersion;
}
/**
* 更新版本號
* @param nextVersion 新版本號
*/
async function updateVersion(nextVersion: string) {
pkg.version = nextVersion;
timeLog('修改package.json版本號', 'start');
await fs.writeFileSync(path.resolve(__dirname, './../package.json'), JSON.stringify(pkg));
await run('npx prettier package.json --write');
timeLog('修改package.json版本號', 'end');
}
async function generateChangelog() {
timeLog('生成CHANGELOG.md', 'start');
await run(' npx conventional-changelog -p angular -i CHANGELOG.md -s -r 0');
timeLog('生成CHANGELOG.md', 'end');
}
/**
* 將程式碼提交至git
*/
async function push(nextVersion: string) {
timeLog('推送程式碼至git倉庫', 'start');
await run('git add package.json CHANGELOG.md');
await run(`git commit -m "v${nextVersion}" -n`);
await run('git push');
timeLog('推送程式碼至git倉庫', 'end');
}
/**
* 元件庫打包
*/
async function build() {
timeLog('元件庫打包', 'start');
await run('npm run build');
timeLog('元件庫打包', 'end');
}
/**
* 釋出至npm
*/
async function publish() {
timeLog('釋出元件庫', 'start');
await run('npm publish');
timeLog('釋出元件庫', 'end');
}
/**
* 打tag提交至git
*/
async function tag(nextVersion: string) {
timeLog('打tag並推送至git', 'start');
await run(`git tag v${nextVersion}`);
await run(`git push origin tag v${nextVersion}`);
timeLog('打tag並推送至git', 'end');
}
async function main() {
try {
const nextVersion = await prompt();
const startTime = Date.now();
// =================== 更新版本號 ===================
await updateVersion(nextVersion);
// =================== 更新changelog ===================
await generateChangelog();
// =================== 程式碼推送git倉庫 ===================
await push(nextVersion);
// =================== 元件庫打包 ===================
await build();
// =================== 釋出至npm ===================
await publish();
// =================== 打tag並推送至git ===================
await tag(nextVersion);
console.log(`✨ 釋出流程結束 共耗時${((Date.now() - startTime) / 1000).toFixed(3)}s`);
} catch (error) {
console.log('? 釋出失敗,失敗原因:', error);
}
}
main();
初始化元件
每次初始化一個元件就要新建許多檔案以及資料夾,複製貼上也可,不過還可以使用更高階一點的偷懶方式。
常規思路,新建一個元件模板資料夾,裡面包含一個元件所需要的所有檔案,同時寫好檔案內容。
至於一些動態內容,譬如元件中英文名稱,選一個你喜歡的模板語言(如 handlebars),用其方式留空{{componentName}}
。
package.json
"scripts": {
+ "new": "ts-node ./scripts/new.ts"
},
接下來我們在new.ts
中編寫相關步驟,無非是:
- 基於
inquirer.js
詢問一些基本元件資訊 - 結合資訊,渲染模板(填空)至元件資料夾
- 向 components/index.ts 插入匯出語句
你以為我會寫new.ts
嗎,不,我不會(雖然我真寫過)。
主要是使用metalsmith進行資料與模板結合,寫腳手架的同學可能比較熟悉。
自從我知道了plop.js這個庫,那麼又可以偷懶了(為什麼之前沒有人告訴我有這麼多好用的工具???)
"scripts": {
- "new": "ts-node ./scripts/new.ts",
+ "new": "plop --plopfile ./scripts/plopfile.ts",
},
於是上述流程可以大大簡化,不需要寫程式碼去詢問,不需要手動渲染模板,我們要做的就是寫好模板,並且配置好問題以及渲染目的地。
詳情可見:
- 配置檔案:scripts/plopfile.ts
- 模板檔案:templates/component
結語
文章很長,也是我個人學習中的總結,如果本文幫助到了你請給倉庫一顆 ✨✨ 和本文一個贊。
如果有錯誤煩請在評論區指正交流,謝謝。