快上車！從零開始搭建一個屬于自己的組件庫！
組件在前端開發(fā)中越來越重要了，開發(fā)者更細(xì)分、聚焦于組件層面的開發(fā)，然后像搭積木一樣完成應(yīng)用功能。組件庫可以統(tǒng)一管理組件，輸出文檔，能提升組件復(fù)用性、避免重復(fù)造輪子。趕快搭建自己的組件庫吧，這瓜保甜！
需求背景
為什么要搭建組件庫？
雖然業(yè)界已經(jīng)有很多成熟優(yōu)秀的ui庫可以供我們使用，也為我們解決了很多問題。但是基礎(chǔ)的東西總是不能滿足所有業(yè)務(wù)場景，更多時候我們需要擴展功能來滿足業(yè)務(wù)的需求，好比 table 需要自定列這樣的～相信這也是很多小伙伴開發(fā)時候的場景。
跨項目復(fù)用。很多時候為了方便，只是基于當(dāng)前項目對組件進行二次封裝（反正我是這樣干的哈哈），然后做其他項目遇到同樣場景時，要么copy（經(jīng)常忘記之前封裝在哪個項目里了??）、要么重新干一個...總是缺少一個統(tǒng)籌的地方，復(fù)用很不方便。 組件使用文檔。文檔產(chǎn)出對于一線開發(fā)來說可能相對比較欠缺，因為大家都忙于擼業(yè)務(wù)，文檔這種奢侈品能省一點是一點。這樣導(dǎo)致一個問題就是自己封裝的組件別人不會用、不知道在哪里用，甚至不知道有這么個東西。 跨團隊共建發(fā)展。大多B端系統(tǒng)都是以 element、antd等ui框架為主，基于各種業(yè)務(wù)場景，基本都會有自己團隊的二次封裝。其實類似的功能擴展肯定會有的，如果有組件庫把組件都集中起來，就能減少很多重復(fù)造輪子的勞動力了！
筆者之前就經(jīng)常有這樣的痛點，在某個項目里二次封裝了 el-select ，實現(xiàn) filterable 的時搜索輸入框移到下拉列表中，避免多選時多個tag擠壓了搜索框的空間。當(dāng)時是寫在一個項目里，然后其他項目也遇到了這樣的需求...我在十幾個項目里面尋找、回憶，找回當(dāng)年封裝的組件，人都麻了......
正好最近在搞云產(chǎn)品，需要提供給各中后臺統(tǒng)一的樣式、布局規(guī)范以接入，還需要統(tǒng)一擴展基礎(chǔ)組件的能力。于是組件庫的需求的就這么出來了！基本想做成的就是對 element-ui/plus 、 antd 一些組件進行二次封裝、擴展，并集成到組件庫中，筆者當(dāng)仁不讓把需求從大佬手上搶過來做。
目前初步搭建起來了一個簡易的組件庫了，可對 element-plus 、 element-ui 的組件進行開發(fā)調(diào)試，且目前已經(jīng)實現(xiàn)幾個組件的擴展了～當(dāng)然，第一版還是有很多工作沒做完、做好，不過沒關(guān)系，畢竟不能一下吃成一個胖子。更多實現(xiàn)、優(yōu)化、還會慢慢迭代做，到時候有空會繼續(xù)分享相關(guān)的干貨～
本文會從組件庫的工程架構(gòu)、文檔、組件開發(fā)環(huán)境準(zhǔn)備、打包、發(fā)布進行分享，組件開發(fā)環(huán)境主要是 element-ui/plus 的??，因為本期需求只要滿足 vue2 、 vue3 的中臺，所以 antd 的還沒有投入，只好等下期了。與其說分享，其實更是做一個記錄沉淀一下，也是回顧總結(jié)～事不宜遲！開始進入主題吧，從0-1搭建一個組件庫！
一、項目架構(gòu)
第一次搞組件庫，仿佛走進一個新的空白領(lǐng)域了。作為一個沒經(jīng)驗的小白，當(dāng)然是得抄作業(yè)啦，不不不，應(yīng)該是“借鑒”??。這時候搞個開源的項目來參照參照還是挺香的，于是筆者就去“學(xué)習(xí)了” element-plus項目[1]的架構(gòu)、代碼組織方式，再結(jié)合自己的需求場景就開始干了。
1. Monorepo
整個工程的代碼組織采用 Monorepo 的組織方式，使用工具 pnpm + workspace 來實現(xiàn)。所以全部項目都是放在一個倉庫里的，包括文檔、組件。
工程具體分為以下幾塊，以文檔和組件庫為兩大類進行分塊：
文檔工程（docs） 安裝指引 組件使用文檔（ elm、elp、antd）組件開發(fā)文檔 組件庫（packages） element-pluselement-uiant-designvoice-components
其中 voice-components 筆者是打算用來做 adapt層 用的，因為文檔工具用了 VitePress（后面會講），它只能支持 vue3 的組件，所以 vue2 、 react 的組件需要做一層適配，這一塊是預(yù)留的，暫時可以不關(guān)注。
第一版比較簡單，后續(xù)如果沉淀出一些工具、打包腳本等，也會再擴展幾個項目放進去 workspace 里。所以目前就先這樣吧，用著先～
2. 文檔項目結(jié)構(gòu)
抄作業(yè)抄作業(yè)，這部分跟 element-plus 基本是一致的。
index.md。?。☆櫭剂x，文檔首頁～.vitepress目錄：文檔站點工具配置相關(guān)，這個后面再展開～zh-CN目錄：文檔md文件 components： 組件使用文檔.md。組件的使用demo及案例代碼，相關(guān)配置說明guide： 組件庫指引文檔.md。包括組件的安裝指南、開發(fā)指南public目錄：相關(guān)靜態(tài)資源目錄。 css、image等build目錄：放點自己實現(xiàn)的構(gòu)建腳本、vite插件啥的
3. 組件庫結(jié)構(gòu)
這部分跟 element-plus 也是基本一致的，具體大家可以參照他們的實現(xiàn)，這里就記錄個大概，粗略帶過吧。
每一個ui框架的結(jié)構(gòu)都一樣，以其中一個為例記錄：
組件項目入口—— 根index。導(dǎo)出當(dāng)前項目需要導(dǎo)出的所有模塊（可按需引入）。并導(dǎo)出全局安裝方法。（Vue.use(VcComponents)）可全局注冊export * from './components'
export default {
install
}
復(fù)制代碼2. components：- 入口文件：index。導(dǎo)出所有組件。js
export * from '...'
export * from '...'
export * from '...'
復(fù)制代碼
```
- 存放全部組件，以組件名作為文件夾名。3. 組件文件夾（以button為例）：- 入口文件：index。導(dǎo)出當(dāng)前組件，并包裝 install 方法（主要用于Vue.use調(diào)用時進行全局注冊）。- 組件文件。實現(xiàn)組件擴展的二次封裝。（這里建議擴展組件時保留組件的原來用法，這樣可以降低使用時候的學(xué)習(xí)成本）
二、組件庫工具
這里不會面面俱到，只記錄一些用到的核心工具以及核心的用法～就算不是特別細(xì)粒度，相信大家要自己動手搞的時候也難不倒你們的?。」P者這么菜都一樣搞，你們肯定都行！
1. 文檔站點工具——VitePress
對于組件庫來說，文檔可以說是最關(guān)鍵的一環(huán)了，沒有文檔的組件庫不是真的組件庫～這里筆者用了幾分鐘去調(diào)研（根本就沒怎么調(diào)研），最終決定使用 VitePress[2] 作為文檔站點工具，目前用的版本是 1.0.0-alpha.4。（哈哈哈大家不要害怕alpha版，用著沒啥毛病）
使用下來基本配置用法在官方文檔[3]中都能找到，已經(jīng)滿足當(dāng)前的使用場景了～大家也要采用的話，花點時間去搓一搓就好，整個文檔站點搭建不算難，畢竟只要能跑起來就可以慢慢調(diào)整慢慢搞。
核心配置（都放在 .vitepress 目錄下）：
配置文件：
.vitepress根目錄的config文件。其實沒有特別多的配置，主要就是導(dǎo)航欄和菜單欄而已。export default defineConfig({
title: 'voice-ui', description: '', base, head: [ [ 'link', { rel: 'icon', href: '/images/favicon.ico' } ] ], themeConfig: { logo: '/images/favicon.ico', nav, // 配置導(dǎo)航欄 sidebar, // 配置側(cè)邊菜單欄 footer // 配置頁腳 } }) 復(fù)制代碼 ```
nav 配置導(dǎo)航欄配置（文檔鏈接[4]）
export default [
{ text: '指南', link: '', activeMatch: '' }, { text: 'element-plus', link: '', activeMatch: '' }, { text: 'element-ui', link: '', activeMatch: '' }, { text: 'ant-design', link: '', activeMatch: '' } ] 復(fù)制代碼 ```
sidebar 配置側(cè)邊菜單欄（文檔鏈接[5]）。具體配置太多就不全貼出來了，這里的配置在文檔中都能找到。如下這樣配置就是一個
nav路由對應(yīng)一個sidebar菜單。export default {
'/zh-CN/guide/': [ { text: '安裝', items: [ { text: 'element-plus', link: '' }, ... ] }, { text: '開發(fā)者指南', items: ... } ] } 復(fù)制代碼 ```
大概的效果如下，不同nav對應(yīng)各自的側(cè)邊欄菜單：
/theme/index中自定義主題 & 全局注冊vue3組件
具體配置參照文檔[6]。這里的僅是筆者的基本配置～ import { App } from 'vue'
import Theme from 'vitepress/theme'
import '../../public/css/customStyle.css' // 自定義的主題色文件
import 'element-plus/dist/index.css'
import 'element-plus/theme-chalk/dark/css-vars.css'
import VcComponent from '@voice-ui/voice-components' // 上文提到的adapt層，導(dǎo)出vue3的組件
export default {
...Theme,
enhanceApp ({ app }: {app: App}) {
app.use(VcComponent) // 進行組件注冊，這樣我們可以直接在 markdown 中使用組件啦！
}
}
復(fù)制代碼customStyle.css文件其實就是對VitePress的一些 css變量 進行自定義重寫??:root {
--vc-primary-color: #295dfa;
...
}
:root {
--vp-c-brand: var(--vc-primary-color); /* 自定義 VitePress 的主題色 */
...
}
復(fù)制代碼
2. 打包工具——Vite
提到這個必須提一嘴：開發(fā)真絲滑！是的，包括各項目的 dev 、 build 都是使用 Vite 完成。其實這個沒什么好說的，大家可能用得比我都熟～所以這里只簡單帶一帶用了什么功能～
用到的 vue2、 vue3 插件（官方文檔戳[7]）： underfin/vite-plugin-vue2@vitejs/plugin-vue打包配置——庫模式?；镜亩加辛?。 es、cjs、umd、iife。（官方文檔戳[8]，具體下文會講）配置 alias。各模塊在dev、prod環(huán)境中相互引用（官方文檔戳[9]，具體下文會講）配置 external。（vite配置[10]；rollup配置[11]）
第一版差不多就這些了，配置上還是比較簡單的?；究梢詽M足 dev開發(fā)、build打包 需求。
三、開發(fā)環(huán)境
因為使用的 VitePress 支持在 markdown 中直接使用 vue3 組件，所以 vue2 、 vue3 、 react 相關(guān)的開發(fā)環(huán)境有所不同。基于此， element-plus 的開發(fā)環(huán)境就沒有單獨搞了，直接在 docs 項目中進行組件開發(fā)。
1. vue3 + element-plus 開發(fā)環(huán)境
這里也是直接抄作業(yè)的，模仿 element-plus 的實現(xiàn)。核心做法：
包裝 element-plus組件一層install方法在 VitePress中進行全局注冊在 md文件中直接使用注冊好的組件，可以直接在文檔中進行開發(fā)調(diào)試
大概的代碼思路：
給組件對象添加
install方法import { withInstall } from '../../utils'
import Button from './button.vue'
export const VcButton = withInstall(Button)
export default VcButton
export * from './'
復(fù)制代碼install方法：接收一個
Vue3對象，用Vue.component進行組件注冊export const withInstall = comp => {
comp.install = app => { app.component(comp.name, comp) } return comp } 復(fù)制代碼 ```
文檔項目中，在
.vitepress/theme/index.ts中進行全局注冊（上文也有提到）export default {
enhanceApp ({ app }: {app: App}) { // 這里能拿到 app ，也就是Vue3的app // VcButton在這里進行全局注冊 app.use(VcButton) // app.use 就會調(diào)用 VcButton的install方法 } } 復(fù)制代碼 ```
md中直接使用注冊好的組件
# Button 按鈕
這是一個按鈕
# Element-plus
## Button
<vc-button />
復(fù)制代碼
然后就能在頁面上看到了，并且是有熱更新的！這樣我們直接開發(fā)調(diào)試即可了。
2. vue2 + element-ui 開發(fā)環(huán)境
vue2 、 react 的開發(fā)環(huán)境實現(xiàn)思路大致相同（react的這次還沒搞，以vue2為例就好），就是在當(dāng)前項目中用vite啟動一個devServer進行開發(fā)，就跟普通的項目開發(fā)是一樣的。
根目錄建一個
index.html，指定入口搞個demo目錄，其實就是Vue項目，newVue完后掛載到dom上。如下：
在 demo-xxx的vue文件中導(dǎo)入開發(fā)的組件進行試用、調(diào)試。頁面效果如下：
react的雖然還沒做，但是具體思路也是跟vue2一樣的，在react自己的項目中起服務(wù)進行組件的開發(fā)調(diào)試～后續(xù)做了的話會補充進這里～
四、組件打包、發(fā)布
目前的打包、發(fā)布實現(xiàn)得比較簡單。大概是統(tǒng)一打包，然后進到每個目錄中去進去npm發(fā)布，目前也是只發(fā)布在內(nèi)部的npm中。
1. 統(tǒng)一打包
為了打包方便，且契合當(dāng)前發(fā)布平臺的特性，在整個項目的根目錄中 package.json 的 scripts 中進行了命令整合。這里后續(xù)可能會用腳本的方式去實現(xiàn)，因為可能在打包的時候要處理一些其他的邏輯。目前第一版大概如下：
{
"scripts": {
"build": "pnpm run build:elp && pnpm run build:elu && pnpm run build:shared",
"build:elp": "pnpm run -C packages/element-plus build",
"build:elu": "pnpm run -C packages/element-ui build",
"build:shared": "pnpm run -C packages/shared build",
"release": "node scripts/release.ts"
}
}
復(fù)制代碼
2. 組件庫的打包配置
上文打包工具哪里有提到過，目前是最簡單版的，打出 es、cjs、umd、iife 格式的包，而且要external掉第三方庫。大概配置：
export default defineConfig(async ({ command, mode }) => {
return {
plugins: [ createVuePlugin() ],
build: {
rollupOptions: {
external: ['element-ui', 'vue']
},
lib: {
entry: path.resolve(__dirname, './components/index.js'),
name: 'voiceUi',
fileName: 'vc-element-ui',
formats: ['es', 'cjs', 'umd', 'iife']
}
},
resolve: {
alias: await alias()
}
}
})
復(fù)制代碼
3. npm發(fā)布
其實 npm包 安裝只是其中一種方式，該組件庫后續(xù)還會新增模塊聯(lián)邦——MF的接入方式，這個會在后續(xù)進行擴展，到時候做了的話再補充一下或者再寫一篇文章吧～
目前的npm發(fā)包時候用了個腳本，基本就是進到每個目錄下去執(zhí)行以下更新版本好，然后執(zhí)行 npm publish。（這里的腳本會結(jié)合自己發(fā)布平臺的一些能力去寫的，所以就不貼出來了，大致思路就是這樣）
五、開發(fā)時一些注意點
1. Vue版本沖突導(dǎo)致啟動服務(wù)、打包失敗
因為是使用 Monorepo 代碼組織方式，所以整個項目難免會出現(xiàn)依賴包重合（版本不同）的問題。就好比這整個項目中既裝了 Vue3 、也裝了 Vue2 ，可能起項目時會報錯：
Vue packages version mismatch:
- [email protected]
- [email protected]
復(fù)制代碼
但是仔細(xì)檢查發(fā)現(xiàn)當(dāng)前項目的 node_modules 中的 vue 和 vue-compiler 是同版本的，而且是在當(dāng)前工程中執(zhí)行的啟動、打包。查了個 issus ，在pnpm文檔中找到了相關(guān)的解決方案：
具體文檔地址：pnpm—shared-workspace-lockfile[12]
配置了這個文件后問題就解決了～
2. 配置alias解決入口問題
組件庫打包后的入口跟開發(fā)時的入口其實是有點不一致的，所以如果我們開發(fā)中直接 import xxx from 組件庫名稱 這樣導(dǎo)入組件是會有問題的，畢竟一般情況下我們的入口是配置打包完之后的產(chǎn)物的入口的（一般是dist、lib目錄下的index）。
出于這點，配置個alias就很好解決問題了，因為很多地方用到，筆者直接就封成了個函數(shù)：
export async function alias (): Promise<Array<Alias>> {
const projectPath = packagesPath()
const dirArr = await fsPromises.readdir(projectPath)
return dirArr.map(packagePath => {
return {
find: new RegExp(`^@voice-ui\/${packagePath}(\/(dist))?$`),
replacement: path.join(projectPath, `/${packagePath}/index`)
}
})
}
復(fù)制代碼
大概作用就是把入口從 dist 下面換到當(dāng)前工程的對應(yīng)項目下的index入口。
3. 樣式隔離
docs項目中用的 VitePress ，他會有一些自己的樣式控制，可能會影響到我們需要在文檔中展示的組件。剛好筆者就遇到了這么一個情況：
如圖所示，table的樣式變得很奇怪。筆者并沒有對樣式有做什么處理，就是element-plus的table。用審查元素看了下，主要是 VitePress 也有自己的table的樣式，影響到 el-table 的表現(xiàn)了。
我們可以通過重寫樣式解決，但這樣在其他的如 antd、element-ui 的組件放進來的時候也會有問題。所以最好還是把樣式進行隔離。哈哈哈，其實寫到這里的時候，筆者還沒有實現(xiàn)樣式隔離，畢竟給大伙寫文章更重要嘛！！
筆者有個大概想法是用 webComponent 去隔離，這只好做完了再寫出來了??，讓大家留個念想。
寫在最后
其實組件庫這個東西真是早有早好，如果當(dāng)前團隊還沒有的話，趕緊搞一個吧。筆者以前也沒意識去搞這個東西（還是太菜了），所以做了很多重復(fù)的勞動。每做一些新項目，或者參與別人的項目，經(jīng)常想用一些自己之前封裝的組件，都很麻煩，有時候為了不想切來切去，直接就動手寫了。現(xiàn)在想想，要是那時候就做了個組件庫該多好啊～其實做個簡單版的也不是很難，如果是只需要關(guān)注一種前端框架的那就更簡單了，要考慮的東西更少。把整個組件庫搭出來之后，還能找其他小伙伴一起共建，一起維護，不斷強大自己團隊的組件庫，大家一起受益～
真的！還沒有的趕緊搭！這瓜保甜。
作者：井柏然
https://juejin.cn/post/7120893568553582622