公司目前有不少后台管理系统，目前代码量都愈来愈大，在开发的过程当中，咱们也秉承着提取公共组件，经过复用组件来减小开发工做量，随着公共组件数量的增长，新同事想要快速了解公共组件如何使用，须要到具体的业务页面中去看，这样子学习组件的成本太大，因而就想给每一个组件提供一个文档，来解释组件如何使用。css

恰巧以前有同事分享过storybook，听闻效果不错，就准备尝试一下~~前端

storybook

storybook，人如其名，它将实例化的组件称之为story，不一样组件的不一样实例化组成了一本 ◤故事书◢。每一个组件能够有多个故事，故事之间不一样通常是由于入参不一样，幻化出的组件不一样功能。厉害的它还支持不少插件，来扩展这本故事书。node

React项目集成storybook

在现有的项目集成storybook，最大的问题是须要将已有的webpack配置和storybook本身的webpack配置集成到一块儿。react

安装storybook

有两种方式（手动和自动），具体能够参考官方文档。webpack

我是采用的手动的方式，以为比较可控一些。git

npm install @storybook/react --save-dev

增长配置文件

在根目录建立文件夹.storybook，而后建立config.js，这个配置文件主要是为了告诉storybook哪些文件是story文件。github

import { configure } from '@storybook/react';
// 查找src目录下后缀是.stories.js的文件，就是story
configure(require.context('../src', true, /\.stories\.js$/), module);

合并webpack.config.js

storybook要加载你写的组件，须要依赖你的webpack.config.js来编译代码，参考具体文档。web

由于咱们的项目是使用的ant.desgin pro搭建的，查找了一下竟然有人解决过这个问题，就参考了github issues中的解决方法。shell

写一个story

story其实就是引入组件，并实例化组件的过程，具体的代码以下。npm

import React from 'react';
import {storiesOf} from '@storybook/react';
import { Button } from '@storybook/react/demo'; 

const stories = storiesOf('Button', module);

stories.add(
    'withText',
    () => {
        return <Button>Hello Button</Button>;
    }
).add(
    'withEmoji',() => {
        return <Button><span role="img" aria-label="so cool">😀 😎 👍 💯</span></Button>
    }
);

引入须要的插件

storybook提供的插件有不少，必需要说想要有野心的框架，必定是能够扩展的。story经常使用的组件有notes，source，knobs等。使用插件的资料以下，参考资料。引入插件的步骤以下：

1）安装npm包

<!--"@storybook/addon-notes": "^5.2.5"-->
yarn add -D @storybook/addons @storybook/addon-notes

2）增长配置文件addons.js

import '@storybook/addon-notes/register-panel';

3）story文件中增长内容

import React from 'react';
import {storiesOf} from '@storybook/react';
import { Button } from '@storybook/react/demo'; 

// notes插件展现的内容
import readme from './readme.md';

const stories = storiesOf('Button', module);
 
stories.add(
    'withText',
    () => {
        return <Button>Hello Button</Button>;
    }
).add(
    'withEmoji',() => {
        return <Button><span role="img" aria-label="so cool">😀 😎 👍 💯</span></Button>
    },
    {
        notes: {markdown: readme},
    }
);

到此为止，storybook集成算是完成了，可是这种展现的形式有点不太方便，对比ant.design的文档页面，组件和说明文档混合在一个页面的效果，更方便，因而手贱的去尝试了docz，结果就被，坑了,坑了,坑了......

docz

docz的宣传语是◤It's never been easier to document your things!◢ 听起来仍是蛮诱惑的，并且它只能使用在React技术栈，效果图以下，感受仍是很完美的。

安装docz

咱们是在已有项目中集成docz，很简单安装docz的包便可，但也是正是这里致使了一个大坑。

yarn add docz

启动docz，也能够在scripts中增长命令，参考官方文档。

npx docz dev

配置docz

默认docz会去加载mdx文件渲染，可是也提供了一个doczrc.js文件，用来配置差别化的需求。

// doczrc.js
export default {
  // 哪些文件能够被认为是doc文件被加载渲染
  files: '**/*.{md,markdown,mdx}'
  // or files: ['**/*.{md,markdown,mdx}']
}

存在问题

在已有的项目中安装docz会有一个问题，react会出现版本冲突。

由于docz的package.json中，包含peerDependencies，会从新安装react和react-dom，参考issues。

"peerDependencies": {
    "react": "^16.8.0",
    "react-dom": "^16.8.0"
},

到此，崩殂...虽然能够用土办法，修复问题，可是咱们还有CI工具要去作线上打包部署等，实在是不优雅，放弃了

father

本觉得到docz，一切就到此为止了，偶然的机会发现了蚂蚁金服的前端大佬云谦的一次分享，提到了他们本身基于docz和storybook封装了一个组件开发工具，father。名字起得也这么霸气，总有一种被占了便宜的感受，o(╥﹏╥)o，因而便拿来试了试了，果真痛并快乐着...

须要提一句的是，father的本职不是作文档的，而是包含组件开发、打包、发布和文档生成的集成方案，因此其实单独使用其文档功能，有点大材小用了。

安装

yarn add father

可是，你观察一下安装完以后father和father-build的package.json，就会发现和你当前项目类似的依赖是在是太多了，甚至连ant.design都从新安装了，不知道什么缘由，反正项目就是启动不起来了。

因此只能采起骚操做，在src目录下建立package.json，而后执行yarn add father，指望的是不要影响项目的node_modules。

可是仍是失望了，由于node_modules是能够按照层级获取的，仍是会影响到根目录的node_modules。

因而骚操做再次尝试，在运行yarn start的时候，将src/node_modules移动到根目录，并命名为fatherlibs；运行组件开发的时候，将fatherlibs移动到src目录下，并更名为node_modules。

这里使用到了一个库shelljs，能够模拟shell命令。

启动

启动father，或者一样增长scripts命令。

npx father doc dev

配置文件

father提供了一个.fatherrc.js配置文件，主要是帮助配置打包方法和调整docz文档配置。

export default {
    esm: 'rollup',
    cjs: 'rollup',
    umd: false,
    doc: {
        title: '**项目组件库',
        files: ['components/**/*.mdx'], 
    },
    cssModules: true,
};

到此为止，虽然能够跑起来，可是每次切换本地开发和组件开发的方式，真的也是不太友好！云谦老师的这个库是真好用，只是这里的场景实在不合适，真不怪大佬。

既然在已有项目中集成这些文档工具，如此麻烦，为何不将组件开发独立出来呢，哈哈，下一次，我将考虑如何使用现有的工具，进行组件库开发，已经作一些简单的脚手架辅助开发。使用docz和father遇到的问题，若是您有好的方法，不吝赐教...

从组件文档引起的惨案 ◤1◢