多是最詳細的React組件庫搭建總結

時間  2020-05-15
標籤 詳細 react 組件 搭建 總結 欄目 React 简体版
原文   原文鏈接

概覽

本文包含如下內容：javascript

  • prepare: 組件庫前期開發準備工做。eslint/commit lint/typescript等等；
  • dev: 使用docz進行開發調試以及文檔編寫；
  • build: umd/cjs/esm、types、polyfill 以及按需加載；
  • test: 組件測試；
  • release: 組件庫發佈流程；
  • deploy: 使用now部署文檔站點，待補充；
  • other: 使用plop.js快速建立組件模板。

若是本文幫助到了你請給倉庫 一顆 ✨✨。css

若是有錯誤煩請在評論區指正交流，謝謝。java

倉庫地址node

準備工做

初始化項目

新建一個happy-ui文件夾，並初始化。react

mkdir happy-ui

cd happy-ui

npm init --y

mkdir components && cd components && touch index.ts # 新建源碼文件夾以及入口文件

複製代碼

代碼規範

此處直接使用@umijs/fabric的配置。webpack

yarn add @umijs/fabric --dev

yarn add prettier --dev # 由於@umijs/fabric沒有將prettier做爲依賴 因此咱們須要手動安裝
複製代碼

.eslintrc.jsgit

module.exports = {
  extends: [require.resolve('@umijs/fabric/dist/eslint')],
};
複製代碼

.prettierrc.jsgithub

const fabric = require('@umijs/fabric');

module.exports = {
  ...fabric.prettier,
};
複製代碼

.stylelintrc.jsweb

module.exports = {
  extends: [require.resolve('@umijs/fabric/dist/stylelint')],
};
複製代碼

想自行配置的同窗能夠參考如下文章：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
複製代碼

這些依賴都是服務於文檔站點應用，和組件庫自身毫無關聯。

最終效果以下：

最終效果

根目錄下新建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。

明確如下目標：

  1. 導出類型聲明文件
  2. 導出 umd/Commonjs module/ES module 等 3 種形式供使用者引入
  3. 支持樣式文件 css 引入，而非只有less
  4. 支持按需加載

導出類型聲明文件

既然是使用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。
對此有疑問的同窗推薦閱讀：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

lib/alert/alert.js

導出 ES module

生成ES module能夠更好地進行tree shaking，基於上一步的babel配置，更新如下內容：

  1. 配置@babel/preset-env的modules選項爲false，關閉模塊轉換；
  2. 配置@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

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 種預選方案：

  1. 告知用戶增長less-loader；
  2. 打包出一份完整的 css 文件，進行全量引入；
  3. 單獨提供一份style/css.js文件，引入的是組件 css樣式文件依賴，而非 less 依賴，組件庫底層抹平差別；
  4. 使用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，自動按需引入，美滋滋。

並且每一個組件都與本身的樣式綁定，不須要業務方或組件開發者去維護樣式依賴，什麼是樣式依賴，後面會講到。

缺點：

  1. 樣式沒法單獨緩存；
  2. styled-components 自身體積較大；
  3. 複寫組件樣式須要使用屬性選擇器或者使用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'？🙃

能夠，業務方爽了，組件開發方不爽。

因此咱們要找一個你們都爽的方案：

  1. 開發方可以開心的使用預處理器；
  2. 業務方不須要額外的使用成本。

答案就是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，而不會深刻單元測試的學習。

若是你對下列問題感興趣：

  1. What-單元測試是什麼？
  2. Why-爲何要寫單元測試？
  3. How-編寫單元測試的最佳實踐？

那麼能夠看看如下文章：

相關配置

安裝依賴：

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分支以及文章爲準。

標準化發佈流程

本節主要是講解如何經過一行命令完成如下六點內容：

  1. 版本更新
  2. 生成 CHANGELOG
  3. 推送至 git 倉庫
  4. 組件庫打包
  5. 發佈至 npm
  6. 打 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中編寫相關步驟，無非是：

  1. 基於inquirer.js詢問一些基本組件信息
  2. 結合信息，渲染模板（填空）至組件文件夾
  3. 向 components/index.ts 插入導出語句

你覺得我會寫new.ts嗎，不，我不會（雖然我真寫過）。

主要是使用metalsmith進行數據與模板結合，寫腳手架的同窗可能比較熟悉。

自從我知道了plop.js這個庫，那麼又能夠偷懶了（爲何以前沒有人告訴我有這麼多好用的工具？？？）

"scripts": {
- "new": "ts-node ./scripts/new.ts",
+ "new": "plop --plopfile ./scripts/plopfile.ts",
},
複製代碼

因而上述流程能夠大大簡化，不須要寫代碼去詢問，不須要手動渲染模板，咱們要作的就是寫好模板，而且配置好問題以及渲染目的地。

詳情可見：

結語

文章很長，也是我我的學習中的總結，若是本文幫助到了你請給倉庫一顆 ✨✨ 和本文一個贊。

若是有錯誤煩請在評論區指正交流，謝謝。

倉庫地址

相關文章
相關標籤/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公眾號
   歡迎關注本站公眾號,獲取更多信息
聯繫我們 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程