從組件文檔引發的慘案 ◤1◢

公司目前有很多后台管理系統，目前代碼量都越來越大，在開發的過程中，我們也秉承着提取公共組件，通過復用組件來減少開發工作量，隨着公共組件數量的增加，新同事想要快速了解公共組件如何使用，需要到具體的業務頁面中去看，這樣子學習組件的成本太大，於是就想給每個組件提供一個文檔，來解釋組件如何使用。

恰巧之前有同事分享過storybook，聽聞效果不錯，就准備嘗試一下~~

storybook

storybook，人如其名，它將實例化的組件稱之為story，不同組件的不同實例化組成了一本 ◤故事書◢。每個組件可以有多個故事，故事之間不同一般是因為入參不同，幻化出的組件不同功能。厲害的它還支持很多插件，來擴展這本故事書。

React項目集成storybook

在現有的項目集成storybook，最大的問題是需要將已有的webpack配置和storybook自己的webpack配置集成到一起。

安裝storybook

有兩種方式（手動和自動），具體可以參考官方文檔。

我是采用的手動的方式，覺得比較可控一些。

npm install @storybook/react --save-dev

 

增加配置文件

在根目錄創建文件夾.storybook，然后創建config.js，這個配置文件主要是為了告訴storybook哪些文件是story文件。

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

 

合並webpack.config.js

storybook要加載你寫的組件，需要依賴你的webpack.config.js來編譯代碼，參考具體文檔。

因為我們的項目是使用的ant.desgin pro搭建的，查找了一下居然有人解決過這個問題，就參考了github issues中的解決方法。

寫一個story

story其實就是引入組件，並實例化組件的過程，具體的代碼如下。

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遇到的問題，如果您有好的方法，不吝賜教...