公司目前有不少後臺管理系統，目前代碼量都愈來愈大，在開發的過程當中，咱們也秉承着提取公共組件，經過複用組件來減小開發工做量，隨着公共組件數量的增長，新同事想要快速瞭解公共組件如何使用，須要到具體的業務頁面中去看，這樣子學習組件的成本太大，因而就想給每一個組件提供一個文檔，來解釋組件如何使用。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◢