用 rollup + gulp 造個輪子，別說還挺香
前戲
我是16年入了前端的坑，17年知道了gulp和rollup這兩個玩意兒。由於那時webpack勢頭很猛，便一直沒有正眼瞧過它一眼。
直到20年進了一家小公司，做了很多類似的小專案，相同的程式碼拷來拷去，出現一個bug一堆專案都要改，實在噁心到我了。
於是不得不開始考慮將一些公共的方法和元件提取出來，做成一個第三方庫來維護。而在庫的封裝方面，rollup相對於webpack具有一定的優勢。
在此，便和大家分享一下如何自己造輪子，封裝一個前端庫併發布到npm倉庫中去。
原始碼
這是我自己封裝的3個庫，有興趣可以看看：
https://github.com/moohng/dan;
https://github.com/moohng/dui;
https://github.com/moohng/tui;
第一個是工具函式庫，後面兩個是UI庫，目前已全部使用TypeScript重寫。dui是基於Vue 3封裝的，tui無任何依賴，通過tsx語法實現的。
由於後面沒多久就離職了，也就沒有封裝更多方法和元件進去了，但還是具有一定的學習參考價值，尤其對於新手朋友。
每一個庫從目錄結構、打包命令、匯出方式、ts型別支援、單元測試、自動釋出等，幾乎所有細節知識都涵蓋到了。
實操
瀏覽百遍，不如實操一遍（文章基於tui來做介紹）。
目錄結構
另外，還有lib和dist兩個打包輸出的目錄沒有列出來。
從上到下：
-
.github：GitHub自動打包釋出的腳步配置目錄； -
packages：存放tui元件庫的原始碼； -
src：tui元件庫演示demo目錄； -
test：測試相關程式碼； -
webpack：暫時忽略，用於測試webpack打包用的；
後面的babel.config.json、gulpfile.esm.js、rollup.config.js、tsconfig.json分別是babel、gulp、rollup、ts的配置檔案。
環境配置
tsconfig.json配置如下：
{ "compilerOptions": { "jsx": "preserve", // 支援jsx "module": "esnext", "target": "esnext", "declaration": true, // 生成相應的 .d.ts檔案 "declarationDir": "lib", // 生成宣告檔案的輸出路徑 "noEmitOnError": true, // "strict": true, "strictFunctionTypes": true, "strictBindCallApply": true, "strictNullChecks": true, "strictPropertyInitialization": true, "skipLibCheck": true, "moduleResolution": "node" }, "include": ["packages/**/*"], }
在配置檔案中，需要開啟jsx的支援，因為tui的html是基於jsx語法來實現的；同時啟用生成.d.ts檔案功能，這個功能可以在ts編譯的時候根據我們的原始碼自動生成.d.ts型別宣告檔案。
babel的配置相對要複雜一些，主要是對tsx的支援上。
部分配置原始碼如下：
{
"presets": [
"@babel/preset-env",
[
"@babel/preset-react",
{
"pragma": "Tan.createElement", // 類似於 React.createElement 方法
"pragmaFrag": "Tan.Fragment", // 類似於 React.Fragment 片段
"importSource": false,
"useSpread": true
}
],
[
"@babel/preset-typescript",
{
"isTSX": true,
"jsxPragma": "Tan",
"allExtensions": true
}
]
]
}
-
@babel/preset-react：用於解析jsx語法，生成Tan.createElement('div', {})這種js函式結構； -
@babel/preset-typescript：將ts轉成js，替代tsc命令；
元件的實現
以最簡單的Toast元件為例。
功能：
- 提供通用、成功、失敗、通知、警告、載入中等幾種狀態；
- 支援上、下、居中等位置彈出；
- 支援普通呼叫和快捷呼叫多種呼叫方式；
元件結構設計（非完整程式碼）：
// packages/Toast/index.tsx
/** 元件入參 */
interface ToastOptions {
text?: string; // 字串 或 html模板
type?: 'success' | 'error' | 'info' | 'warn' | 'loading' | 'toast';
margin?: string;
duration?: number;
position?: 'top' | 'bottom' | 'center';
}
/** 元件物件（支援函式呼叫和快捷方式呼叫） */
interface ToastObject {
(options: string | ToastOptions): ToastHide;
info: ToastFunction;
success: ToastFunction;
error: ToastFunction;
warn: ToastFunction;
loading: ToastFunction;
}
interface ToastFunction {
(text: string): ToastHide;
}
interface ToastHide {
(): void;
}
/** 函式實現 */
const Toast: ToastObject = (options) => {
// ...
}
/** 元件匯出 */
Toast.info = (text: string) => Toast({ text, type: 'info' });
Toast.success = (text: string) => Toast({ text, type: 'success' });
Toast.error = (text: string) => Toast({ text, type: 'error' });
Toast.warn = (text: string) => Toast({ text, type: 'warn' });
Toast.loading = (text: string = '正在載入') => Toast({ text, type: 'loading' });
export default Toast;
元件結構有了，現在主要就是Toast函式的實現了。
開始無外乎就是對引數的判斷，然後就是生成對應的DOM結構，最後插入到真實的DOM文件中去。
這裡主要說一下jsx的實現，下面是Toast元件的jsx原始碼：
// 建立 DOM
let $toast = options.type === 'loading' ? (
<>
<div className="mask loading"></div>
<div className="tui-toast" dataType={options.type} dataPosition={options.position}>
<i className="tui-icon__loading"></i>
<span>{options.text ?? ''}</span>
</div>
</>
) : <div className="tui-toast" dataType={options.type} dataPosition={options.position}>{options.text ?? ''}</div>;
是不是看起來跟React很像？沒錯，這就是我們需要的。
還記得上面babel中配置的Tan.createElement嗎？它就是為了將我們這裡的jsx語法轉成Tan.createElement的函式形式。
看看編譯後的程式碼（部分）：
Tan.createElement(
Tan.Fragment,
null,
Tan.createElement('div', {
className: 'mask loading',
}),
Tan.createElement(
'div',
{
className: 'tui-toast',
dataType: options.type,
dataPosition: options.position,
},
Tan.createElement('i', {
className: 'tui-icon__loading',
}),
Tan.createElement(
'span',
null,
(_options$text = options.text) !== null && _options$text !== void 0 ? _options$text : ''
)
)
)
其實React也是一樣，它也是通過babel將jsx語法轉成了React.createElement函式形式。同樣的，我們也可以將React.createElement換成我們自己實現的函式。jsx並非React獨有，Vue同樣也支援，誰都可以使用，關鍵在於如何轉換的問題。
Tan.createElement 的實現
我實現的比較簡單，一共也才幾十行程式碼，滿足一些基本常用的語法。
全部原始碼如下：
// packages/core/index.ts
import { flat } from '@moohng/dan';
interface FragmentTag {
Fragment: DocumentFragment;
}
type TagMap = HTMLElementTagNameMap & FragmentTag;
function createFragment() {
return document.createDocumentFragment();
}
export const Fragment: keyof FragmentTag = 'Fragment';
const hasOwnProperty = Object.prototype.hasOwnProperty;
const toString = Object.prototype.toString;
function classnames(className: string | Record<string, boolean> | (Record<string, boolean> | string)[]): string[] {
if (typeof className === 'string') {
const splitter = /\s+|\s*,\s*/;
return className.split(splitter).filter(item => item);
}
if (Array.isArray(className)) {
const r: string[] = [];
className.forEach(item => {
r.push.apply(r, classnames(item));
});
return r;
}
if (toString.call(className) === '[object Object]') {
return classnames(Object.keys(className).filter(item => className[item]));
}
return [];
}
export function createElement<K extends keyof TagMap>(node: K | TagMap[K] | HTMLElement, props?: Record<string, unknown>, ...children: (HTMLElement | string | HTMLElement[] | string[])[]) {
// 建立 DOM
if (typeof node === 'string') {
if (node === Fragment) {
(node as unknown as DocumentFragment) = createFragment();
} else {
node = document.createElement(node);
}
}
// 設定屬性
props && Object.keys(props).forEach(key => {
// 如果是 on 開頭，則為事件監聽
const eventType = key.match(/^on(\w+)$/)?.[1];
if (eventType && typeof props[key] === 'function') {
(node as TagMap[K]).addEventListener(eventType.toLocaleLowerCase(), props[key] as EventListenerOrEventListenerObject, false);
} else if (key === 'style' && typeof props[key] !== 'string') {
const style = props[key] as any
for (const k in style) {
if (hasOwnProperty.call(style, k)) {
(node as HTMLElement).style[k] = style[k];
}
}
} else if (key === 'className') {
const className = classnames(props[key] as any);
(node as HTMLElement).classList.add.apply((node as HTMLElement).classList, className);
} else {
const _key = key.replace(/[A-Z0-9]/g, v => '-' + v.toLocaleLowerCase());
if ((node as any).setAttribute) {
(node as HTMLElement).setAttribute(_key, props[key] as string || '');
}
}
});
// 新增子節點
const childNodes = flat(children.filter(item => item || typeof item === 'number'));
(node as TagMap[K]).append.apply((node as TagMap[K]), childNodes as Node[])
return node;
}
createElement 函式很簡單，主要就是建立DOM節點，正確的解析props引數。
有了createElement，只需要在對應的jsx檔案中引入就行了。
import * as Tan from '../core/index';
這也是為什麼React元件都需要在檔案頭部引入import * as React from 'react';的原因。
編譯打包
先看package.json中定義的scripts：
"scripts": {
"serve": "parcel serve index.html --dist-dir build/cache --no-cache",
"build:css": "gulp css",
"build:types": "tsc --emitDeclarationOnly",
"build:es": "babel packages -d es -x \".ts,.tsx\" --env-name es",
"build:lib": "babel packages -d lib -x \".ts,.tsx\"",
"build:dist": "rollup -c",
"build": "npm run build:types && npm run build:es && npm run build:lib && npm run build:dist && npm run build:css",
"type-check": "tsc --noEmit",
"test": "jest"
},
-
tsc --emitDeclarationOnly命令就是生成.d.ts檔案； -
babel packages -d lib -x \".ts,.tsx\"命令就是將packages目錄中的元件編譯到lib目錄；
通過這兩條命令元件的js部分就算是搞定了。
元件的css樣式我是放在全域性的，其實大部分的UI框架的樣式檔案也都是在全域性定義的，這跟我們開發專案不同。
樣式的編譯，其實也就是將scss轉成css和一些其他轉換、壓縮等操作，這裡，我是通過gulp將這些操作組合起來的。
gulpfile.esm.js部分配置原始碼：
import { src, dest, parallel } from 'gulp';
import sass from 'gulp-sass';
import postCSS from 'gulp-postcss';
import autoprefixer from 'autoprefixer';
export function css_lib(cb) {
src(['packages/**/style/*.scss'], {
base: 'packages',
})
.pipe(sass({
outputStyle: 'expanded',
}))
.pipe(postCSS([autoprefixer()]))
.pipe(dest('lib'));
cb();
}
到這裡為止，我們的元件庫的lib輸出目錄就算完成了，lib目錄主要是為了方便我們對單個元件的引入。但通常，一個元件庫還需要支援script標籤引入（一次性引入）。
所以我們還需要將所有的元件庫程式碼進行打包，提到打包，rollup便就派上用場了。
// rollup.config.js
import path from 'path';
import resolve from '@rollup/plugin-node-resolve';
import babel from '@rollup/plugin-babel';
import { terser } from 'rollup-plugin-terser';
const extensions = ['.js', '.jsx', '.ts', '.tsx'];
module.exports = {
input: path.resolve('packages/index.ts'),
plugins: [
resolve({ extensions }),
babel({
extensions,
include: ['packages/**/*'],
}),
],
output: [
{
file: 'dist/tui.js',
format: 'umd',
name: 'tui',
// https://rollupjs.org/guide/en#output-globals-g-globals
globals: {},
},
{
file: 'dist/tui.min.js',
format: 'umd',
name: 'tui',
// https://rollupjs.org/guide/en#output-globals-g-globals
globals: {},
plugins: [
terser(),
],
},
],
};
這個就和我們開發專案時用的webpack打包工具一樣，可以指定匯出方式，以及對程式碼進行壓縮混淆。
到這裡，一個基本的UI庫才算完成。
注意打包和編譯的概念，編譯僅僅是通過babel或sass將原始碼轉換成瀏覽器能支援的js或css程式碼；而打包是在編譯的基礎之上，再將原始檔進行整合，輸出一個或多個檔案。rollup和webpack一樣，都是打包工具，gulp是任務（流程）管理工具。
單元測試
最後，還有“不那麼重要”的測試。
說實話，自己設計元件自己寫的程式碼然後自己寫測試，有點像“脫褲子放屁——多此一舉”了。也許是我對測試的理解還不夠深入吧，畢竟大佬們都說測試有多重要，咱不懂、咱也不敢問，暫且裝模作樣地寫上吧。
測試框架選用的是jest，據說是很強大的東西。
在專案根目錄下建立一個test目錄，裡面寫的測試檔案以.test.ts字尾命名，測試的時候就可以自動執行了。
比如（部分原始碼）：
// createElement.test.tsx
import * as Tan from '../lib/core';
test('jsx', () => {
const text = 'Hello World';
const handleClick = (e: MouseEvent) => {
(e.target as HTMLDivElement).innerText = '你好';
}
const test = <div dataType="success" onClick={handleClick}>{text}</div>;
expect(test.textContent).toBe(text);
expect(test.getAttribute('data-type')).toBe('success');
test.click();
expect(test.innerText).toBe('你好');
});
// import { Toast } from '../lib';
import { Toast } from '../lib';
test('toast loading', done => {
const text = '玩命載入中...';
const hide = Toast.loading(text);
expect(document.querySelector('.tui-toast span').textContent).toBe(text);
setTimeout(() => {
hide();
setTimeout(() => {
expect(document.querySelector('.tui-toast')).toBeNull();
expect(document.querySelector('.mask')).toBeNull();
}, 100);
done();
}, 1000);
});
自動釋出
如果每次提交程式碼後，會自動釋出到npm倉庫，是不是省了很多事兒。以前，這種事大多都是通過Travis CI去做的，不過現在，Github本身就支援該功能了，是不是很贊。
# .github/workflows/npmpublish.yml
name: npm
on:
release:
types: [created]
jobs:
publish-npm:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- uses: actions/setup-node@v1
with:
node-version: 12
registry-url: https://registry.npmjs.org/
- run: yarn --frozen-lockfile
- run: yarn build
- run: npm publish
env:
NODE_AUTH_TOKEN: ${{secrets.npm_token}}
上面這個配置就是在每次建立一個release版本的時候，會自動將我們的程式碼編譯打包，釋出到npm倉庫中去。需要提前配置好NODE_AUTH_TOKEN變數，npm_token可以去npm平臺獲取，然後在GitHub倉庫的Settings裡面配置就行了。
完事
如果你喜歡造輪子，這篇文章應該會對你有幫助，這是我踩了很多坑才摸索出來的。文章只能說個大概流程，強烈建議去GitHub上看原始碼。
最後，歡迎去我的公眾號【末日碼農】，獲取更多技術知識。