从零开始构建一个属于自己的 React Hooks 库（一）

目的

这篇文章主要是带领大家从零开始免费构建一个属于你自己的自定义 React Hooks 库，并生成使用文档和 npm 包。

整体流程

使用 dumi 搭建自定义 React Hooks 库的使用文档，并且发布到 Github 上，利用 Github Action 触发自动部署发布流水线，制品再通过 Github Pages 免费生成静态网站，供大家访问。最后再生成 npm 包供大家下载使用。

一、dumi 搭建文档模式开发脚手架

dumi，中文发音嘟米，是一款为组件开发场景而生的文档工具，与 father 一起为开发者提供一站式的组件开发体验，father 负责构建，而 dumi 负责组件开发及组件文档生成。

本阶段成果

本阶段会生成一个基本的文档模式站点。如图所示：

1. 搭建 dumi 工程

环境要求

首先得有 node，并且 node 版本是 10.13 或以上。

$ node -v
v10.13.0

脚手架初始化

创建一个空文件夹，在该文件夹下打开命令行。

$ mkdir diy-hooks && cd diy-hooks

初始化一个文档模式的组件库开发脚手架（想要更多功能的可以初始化一个站点模式的脚手架，本文以文档模式为例）。

$ npx @umijs/create-dumi-lib        # 初始化一个文档模式的组件库开发脚手架
# or
$ yarn create @umijs/dumi-lib

安装依赖

$ yarn install
# or
$ npm install

启动

$ yarn run dev
# or
$ npm run dev

详细的 dumi 脚手架初始化方案可以参考 dumi 官方文档。

二、编写自定义 hooks

1. 梳理 hooks 目录

安装完脚手架后，生成的项目结构目录应该是和下图所示差不多的。

通过观察 src/Foo/index.md 这个文件可以发现，dumi 中支持直接在 md 文件中书写 tsx 类型代码，且自动生成代码视图区块。
src/Foo/index.md 代码如下：

## Foo

Demo:

	```tsx
	import React from 'react';
	import { Foo } from 'diy-hooks';
	
	export default () => <Foo title="First Demo" />;
	```

More skills for writing demo: https://d.umijs.org/guide/basic#write-component-demo

生成的视图如下：

因此我们可以这样管理我们的 hooks 代码和视图代码：**src 目录下作为 hooks 源代码，doc 目录下作为文档展示。**文档展示引用 src/hooks 下的自定义 hooks。例：

2. 编写第一个自定义 hook

划定好了目录以后，我们可以开始编写我们的第一个自定义 hooks，这里以 useMount 这个 hook 为例。
在 src/hooks 目录下新建一个名为 useMount 的文件夹，在该文件夹下新建一个 index.ts 文件，编码 useMount 的代码。
useMount 代码如下：

import { useEffect } from 'react';

const useMount = (fn: () => void) => {
  useEffect(() => {
    fn();
  }, []);
};

export default useMount;

useMount 代表仅在组件挂载阶段执行。
之后在 src/hooks 目录下新建一个 index.ts 文件，作为一个入口文件，导出我们刚刚新建的 hook。
index.ts 代码如下：

import useMount from './useMount';

export default {
  useMount,
};

形成的目录如下图所示。

三、编写 Hooks 使用文档

1. 梳理 doc 目录

文档的编写统一在 doc 目录下进行。

1. doc 目录下新建第一个 index.md 文件，该文件作为首页默认进入页面。在此处可以编写使用指南等欢迎内容。
2. doc 目录下新建一个 lifeCycle 文件夹，这个文件夹代表分组，表明我们刚刚编写的 hook 属于哪一类 hooks 类型。比如 useMouse 属于 生命周期相关的 hooks，所以我们新建了一个名为 lifeCycle 的文件夹。
3. doc/lifeCycle 下新建一个 index.md 文件，这个文件代表点击这个分组展示的分组简介内容。dumi 默认会以文件名作为目录名，如果我们想改这个目录名为中文，可以在该分组下的 index.md 文件中自定义分组标题。通过在 Markdown 文件顶部编写 FrontMatter 实现：

---
title: 简介
order: 0
group:
  title: 生命周期 # 注意缩进
---

# 简介
本章主要收录与生命周期相关 hooks

## 相关 hooks
 - `useMount` 组件挂载阶段执行

4. doc/lifeCycle 下新建一个 useMount.md 文件夹，该文件夹下主要编写 useMount 这个 hook 的使用示例和 API 参数说明。
   useMount.md 内容如下：

---
title: useMount
---

# useMount

在组件挂载阶段执行。

## 使用示例
### 基本用法
	```tsx
	import React, { useState, useCallback } from 'react';
	import useMount from '../../src/hooks/useMount';
	
	export default () => {
	  const [isMount, setIsMount] = useState(false);
	
	  const handleClick = useCallback(() => {
	    setIsMount(v => !isMount)
	  }, [isMount])
	
	  return (
	    <div>
	      <button onClick={handleClick}>
	        点击{isMount ? '卸载' : '挂载'} mount 组件
	      </button>
	      {isMount && <MountComponent />}
	    </div>
	  )
	};
	
	const MountComponent = () => {
	  useMount(() => {
	    alert('mount 阶段被执行了')
	  })
	  return <div>新组件挂载了</div>
	}
	```

## API
	```ts
	useMount(fn: () => void );
	```

### 参数

| 参数 | 说明               | 类型         | 默认值 |
|------|--------------------|--------------|--------|
| fn   | mount 时执行的函数 | `() => void` | -      |

形成的文档视图如下图所示：

形成的文档视图中的代码视图区块不仅能展示使用示例的代码，还能展示 useMount 编写的源码，这样免去了查看 hooks 还得翻阅 GitHub 源码的麻烦。如图所示：

2. 引入外部组件库

在我们的 dumi 文档库中，可能有些自定义 hooks 涉及到和外部组件库的交互或者想让我们的使用示例更加美观，我们需要引入例如 antd 之类的组件库。我们需要在项目工程的根目录下添加组件库的 npm 依赖。

$ yarn add antd --dev

这时候就可以直接在文件里用了，但是发现组件库样式并没有被引入。需要在根目录的 .umirc.ts 配置文件下，添加按需加载配置。配置如下：

export default defineConfig({
 // ......其他的配置
  extraBabelPlugins: [
    [
      'babel-plugin-import',
      {
        libraryName: 'antd',
        libraryDirectory: 'es',
        style: true,
      },
    ],
  ],
})

还需要安装 babel-plugin-import 依赖。

$ yarn add babel-plugin-import --dev

做完以上配置，就能在 dumi 中使用 antd 等外部组件库。

四、发布到 GitHub

首先得有自己的 GitHub 账号，然后创建一个空的公共仓库，例如：

对本地代码进行 git 初始化，然后 git 远程指向刚刚新建的 GitHub 仓库地址。

$ git init
$ git remote add [origin name] [url]

提交本地代码到远程

$ git add .
$ git commit -m '你的描述信息'
$ git push -u origin master

五、构建 GitHub 自动打包流水线

GitHub 自动部署主要是基于 Github Action 技术实现。

1. 新建流水线

在项目根目录下新建 .github/workflows/gh-pages.yml 文件。
文件内容如下：

name: github pages

on:
  push:
    branches:
      - master # default branch

jobs:
  deploy:
    runs-on: ubuntu-18.04
    steps:
      - uses: actions/checkout@v2
      - run: npm install
      - run: npm run docs:build
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs-dist

该流水线脚本指定 master 分支为构建分支，一旦 master 分支有新的提交就自动触发流水线构建。同时会为项目新建一个分支 gh-pages。这个分支存放打包成功后的制品，也就是我们接下来部署到 GitHub 上的静态网站内容。
提交代码后，可以在项目的 GitHub 仓库地址里点击 Action 查看构建进度。

六、构建 GitHub Pages

修改 .umirc.ts 的配置项，把导出地址指向仓库名地址。例：

export default {
  base: '/diy-hooks', // 文档起始路由
  publicPath: '/diy-hooks/', // 静态资源起始路径
  exportStatic: {}, // 将所有路由输出为 HTML 目录结构，以免刷新页面时 404
  // 其他配置
};

回到项目的 GitHub 仓库， 点击 Settings 选项，然后左侧列选择 Pages 。这时候要关注两个东西。

1. 本仓库的静态网站地址，会显示出来。例如： http://hzm0321.github.io/diy-hooks/
2. 如果你的上一轮构建已经完成，这时候 Source 里就可以选择静态地址的分支（gh-pages），路径选择根路径（/），然后点击保存。之后 git 提交本次修改项到远程，触发流水线。

等流水线执行完成，访问你的静态网站地址，如果能出现页面，就大功告成了！！！

七、发布 hooks 到 npm

进入项目的 src/hooks 目录，在该目录下打开终端，执行 npm 初始化命令，依据情况填入信息。

$ npm init

入口指定为 index.ts。

"main": "index.ts",

peerDependencies 指定 react 版本 在 16.8 以上。

  "peerDependencies": {
    "react": "^16.8.6 || ^17.0"
  }

package.json 参考示例：

{
  "name": "diy-hooks",
  "version": "1.0.0",
  "description": "一个个人自定义 React Hooks 库。",
  "main": "index.ts",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [
    "react",
    "hooks"
  ],
  "repository": "https://github.com/hzm0321/diy-hooks",
  "homepage": "https://hzm0321.github.io/diy-hooks/",
  "author": "hzm",
  "license": "ISC",
  "peerDependencies": {
    "react": "^16.8.6 || ^17.0"
  }
}

执行 npm install 然后 npm login 登录你的 npm 账号。登录完成后，执行 npm publish，发布该包。

本文中使用的案例已经发布到 github 上了，如果不明白的地方可直接在 github 上 learn 分支 查看该项目。
https://github.com/hzm0321/diy-hooks