使用typescript+webpack構建一個js庫的示例詳解
記錄使用typescript配合webpack打包一個javascript library的配置過程.
目標是構建一個可以同時支持CommonJs, esm, amd這個幾個js模塊系統(tǒng)的javascript庫, 然后還有一個單獨打包出一個css的樣式文件的需求.
為此以構建一個名為loaf的javascript庫為例; 首先新建項目文件目錄loaf, 并進入此文件目錄執(zhí)行npm init命令, 然后按照控制臺的提示輸入對應的信息, 完成后就會在loaf目錄下得到一個package.json文件
然后使用npm i命令安裝所需的依賴
npm i -D webpack webpack-cli typescript babel-loader @babel/core @babel/preset-env @babel/preset-typescript ts-node @types/node @types/webpack mini-css-extract-plugin css-minimizer-webpack-plugin less less-loader terser-webpack-plugin
依賴說明
- webpack webpack-cli: webpack打包工具和webpack命令行接口
- typescript: 用于支持typescript語言
- babel-loader @babel/core @babel/preset-env @babel/preset-typescript: babel相關的東西, 主要是需要babel-loader將編寫的typescript代碼轉譯成es5或es6已獲得更好的瀏覽器兼容性
- ts-node @types/node @types/webpack: 安裝這幾個包是為了能用typescript編寫webpack配置文件(webpack.config.ts)
- mini-css-extract-plugin less less-loader: 編譯提取less文件到單獨的css文件的相關依賴
- css-minimizer-webpack-plugin terser-webpack-plugin: 用于最小化js和css文件尺寸的webpack插件
入口文件
通常使用index.ts作為入口, 并將其放到src目錄下, 由于有輸出樣式文件的需求, 所以還要新建styles/index.less
mkdir src && touch src/index.ts mkdir src/styles && touch src/styles/index.less
tsconfig配置
新建tsconfig.json文件
touch tsconfig.json
填入以下配置(部分選項配有注釋):
{
"compilerOptions": {
"outDir": "dist/lib",
"sourceMap": false,
"noImplicitAny": true,
"module": "commonjs",
// 開啟這個選項, 可以讓你直接通過`import`的方式來引用commonjs模塊
// 這樣你的代碼庫中就可以統(tǒng)一的使用import導入依賴了, 而不需要另外再使用require導入commonjs模塊
"esModuleInterop": true,
// 是否允許合成默認導入
// 開啟后, 依賴的模塊如果沒有導出默認的模塊
// 那么typescript會幫你給該模塊自動合成一個默認導出讓你可以通過默認導入的方式引用該模塊
"allowSyntheticDefaultImports": true,
// 是否生成`.d.ts`的類型聲明文件
"declaration": true,
// 輸出的目標js版本, 這里用es6, 然后配和babel進行轉譯才以獲得良好的瀏覽器兼容
"target": "es6",
"allowJs": true,
"moduleResolution": "node",
"lib": ["es2015", "dom"],
"declarationMap": true,
// 啟用嚴格的null檢查
"strictNullChecks": true,
// 啟用嚴格的屬性初始化檢查
// 啟用后類屬性必須顯示標注為可空或賦一個非空的初始值
"strictPropertyInitialization": true
},
"exclude": ["node_modules"],
"include": ["src/**/*"]
}webpack配置文件
創(chuàng)建webpack.config.ts
touch webpack.config.ts
webpack.config.ts
import path from "path";
import { Configuration, Entry } from "webpack";
import MiniCssExtractPlugin from 'mini-css-extract-plugin';
import CssMinimizer from 'css-minimizer-webpack-plugin';
import TerserPlugin from 'terser-webpack-plugin'
const isProd = process.env.NODE_ENV === 'production';
/**
* 這里用到了webpack的[Multiple file types per entry](https://webpack.js.org/guides/entry-advanced/)特性
* 注意`.less`入口文件必須放在`.ts`文件前 */
const entryFiles: string[] = ['./src/styles/index.less', './src/index.ts'];
const entry: Entry = {
index: entryFiles,
'index.min': entryFiles,
};
const config: Configuration = {
entry,
optimization: {
minimize: true,
minimizer: [
new TerserPlugin({ test: /.min.js$/ }),
new CssMinimizer({
test: /.min.css$/,
}),
],
},
module: {
rules: [
{
test: /.ts$/,
loader: 'babel-loader',
exclude: /node_modules/,
options: {
presets: ['@babel/env', '@babel/typescript'],
},
},
{
test: /.less$/,
use: [
isProd ? MiniCssExtractPlugin.loader : 'style-loader',
{
loader: 'css-loader',
},
'postcss-loader',
'less-loader',
],
},
],
},
output: {
path: path.resolve(__dirname, 'dist/umd'),
library: {
type: 'umd',
name: {
amd: 'loaf',
commonjs: 'loaf',
root: 'loaf',
},
},
},
resolve: {
extensions: ['.ts', '.less'],
},
devtool: 'source-map',
plugins: [
new MiniCssExtractPlugin({
filename: '[name].css',
}),
],
};
export default config;webpack入口文件配置
...
const isProd = process.env.NODE_ENV === 'production';
/**
* 這里用到了webpack的[Multiple file types per entry](https://webpack.js.org/guides/entry-advanced/)特性
* 注意`.less`入口文件必須放在`.ts`文件前 */
const entryFiles: string[] = ['./src/styles/index.less', './src/index.ts'];
const entry: Entry = {
index: entryFiles,
'index.min': entryFiles,
};
const config: Configuration = {
entry,
...
}
...在上面的webpack.config.json中，我們配置了兩個入口分別是index和index.min，不難看出，多出的一個index.min入口是為了經(jīng)過壓縮后js和css文件，在生產(chǎn)環(huán)境使用一般都會使用.min.js結尾的文件以減少網(wǎng)絡傳輸時的尺寸; 實現(xiàn)這個還需要結合optimization相關配置, 如下:
optimization: {
minimize: true,
minimizer: [
new TerserPlugin({ test: /.min.js$/ }),
new CssMinimizer({
test: /.min.css$/,
}),
],
},另外，index和index.min的值都是相同的entryFiles對象，這個對象是一個字符串數(shù)組，里面放的就是我們的入口文件相對路徑，這里一定要注意把./src/styles/index.less置于./src/index.ts之前。
webpack為typescript和less文件配置各自的loader
配置完入口后, 就需要為typescript和less代碼配置各自的loader
module: {
rules: [
{
test: /.ts$/,
loader: 'babel-loader',
exclude: /node_modules/,
options: {
presets: ['@babel/env', '@babel/typescript'],
},
},
{
test: /.less$/,
use: [
isProd ? MiniCssExtractPlugin.loader : 'style-loader',
{
loader: 'css-loader',
},
'postcss-loader',
'less-loader',
],
},
],
},mini-css-extract-plugin less less-loader: 編譯提取less文件到單獨的css文件的相關依賴
上面的配置為.ts結尾的文件配置了babel-loader; 為.less結尾的文件配置一串loader, 使用了use, use中的loader的執(zhí)行順序是從后往前的, 上面less的配置就是告訴webpack遇到less文件時, 一次用less-loader->postcss-loader->css-loader->生產(chǎn)環(huán)境用 MiniCssExtractPlugin.loader() 否則用 style-loader;
MiniCssExtractPlugin.loader使用前要先在plugins進行初始化
...
const config = {
...
plugins: [
new MiniCssExtractPlugin({
filename: '[name].css',
}),
],
...
}
...webpack的output配置
...
const config = {
...
output: {
path: path.resolve(__dirname, 'dist/umd'),
library: {
type: 'umd',
name: {
amd: 'loaf',
commonjs: 'loaf',
root: 'loaf',
},
},
},
...
}
...這里配置webpack以umd的方式輸出到相對目錄dist/umd目錄中, umd是Universal Module Definition(通用模塊定義)的縮寫, umd格式輸出library允許用戶通過commonjs, AMD, <script src="...">的方式對library進行引用config.library.name可以為不同的模塊系統(tǒng)配置不同的導出模塊名供客戶端來進行引用; 由于這里的導出模塊名都是loaf, 所以也可以直接config.library.name設置成loaf.
運行webpack進行打包
現(xiàn)在回到最開始通過npm init生成的package.json文件, 在修改其內(nèi)容如下
{
"name": "loaf",
"version": "1.0.0",
"description": "A demo shows how to create & build a javascript library with webpack & typescript",
"main": "index.js",
"scripts": {
"build:umd": "webpack -c webpack.config.ts --node-env production --env NODE_ENV=production",
"test": "npm run test"
},
"keywords": [
"demo"
],
"author": "laggage",
"license": "MIT",
"devDependencies": {
"@babel/core": "^7.18.6",
"@babel/preset-env": "^7.18.6",
"@babel/preset-typescript": "^7.18.6",
"@types/node": "^18.0.0",
"@types/webpack": "^5.28.0",
"babel-loader": "^8.2.5",
"css-loader": "^6.7.1",
"css-minimizer-webpack-plugin": "^4.0.0",
"less": "^4.1.3",
"less-loader": "^11.0.0",
"mini-css-extract-plugin": "^2.6.1",
"postcss-loader": "^7.0.0",
"style-loader": "^3.3.1",
"terser-webpack-plugin": "^5.3.3",
"ts-node": "^10.8.2",
"typescript": "^4.7.4",
"webpack": "^5.73.0",
"webpack-cli": "^4.10.0"
}
}新增了一個腳本命令 "build:umd": "webpack -c webpack.config.ts --node-env production --env NODE_ENV=production", 然后命令行到項目目錄下執(zhí)行npm run build:umd, 不出意外應該就構建成功了, 此時生成的dist目錄結構如下
dist
└── umd
├── index.css
├── index.js
├── index.js.map
├── index.min.css
├── index.min.js
└── index.min.js.map
1 directory, 6 files測試驗證
新建demo.html進行測試
mkdir demo && touch demo/demo.html
demo/demo.html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Document</title>
</head>
<body>
<script src="../dist/umd/index.js"></script>
<script type="text/javascript">
console.log(loaf, '\n', loaf.Foo)
</script>
</body>
</html>用瀏覽器打開demo.html, 然后F12打開控制臺, 可以看到如下輸出則說明初步達成了目標:
Module {__esModule: true, Symbol(Symbol.toStringTag): 'Module'}
demo.html:13 ? Foo() {
var _bar = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : new Bar();
src_classCallCheck(this, Foo);
this._bar = _bar;
}輸出esm模塊
完成上面的步驟后, 我們已經(jīng)到了一個umd模塊的輸出, 相關文件都在dist/umd目錄下; 其中包含可供CommonJs ESM AMD模塊系統(tǒng)和script標簽使用的umd格式的javascript文件和一個單獨的css樣式文件.
已經(jīng)輸出了umd格式的js了, 為什么還要輸出esm模塊? ----TreeShaking
Tree shaking is a term commonly used in the JavaScript context for dead-code elimination. It relies on the static structure of ES2015 module syntax, i.e. import and export. The name and concept have been popularized by the ES2015 module bundler rollup.
此庫的使用者也使用了類似webpack之類的支持Tree Shaking
的模塊打包工具,需要讓使用者的打包工具能對這個js庫loaf進行死代碼優(yōu)化Tree Shaking
從webpack文檔中看出, tree-shaking依賴于ES2015(ES2015 module syntax, ES2015=ES6)的模塊系統(tǒng), tree-shaking可以對打包體積有不錯優(yōu)化, 所以為了支持使用者進行tree-shaking, 輸出esm模塊(esm模塊就是指 ES2015 module syntax)是很有必要的.
用tsc輸出esm和類型聲明文件
tsc -p tsconfig.json --declarationDir ./dist/typings -m es6 --outDir dist/lib-esm
上面的命令使用typescript編譯器命令行接口tsc輸出了ES6模塊格式的javascript文件到dist/lib-esm目錄下
將這個目錄加入到package.json的scripts配置中:
package.json
{
"name": "loaf",
"version": "1.0.0",
"description": "A demo shows how to create & build a javascript library with webpack & typescript",
"main": "index.js",
"scripts": {
"build:umd": "webpack -c webpack.config.ts --node-env production --env NODE_ENV=production",
"build:lib-esm": "tsc -p tsconfig.json --declarationDir ./dist/typings -m es6 --outDir dist/lib-esm",
"test": "npm run test"
},
"keywords": [
"demo"
],
"author": "laggage",
"license": "MIT",
"devDependencies": {
"@babel/core": "^7.18.6",
"@babel/preset-env": "^7.18.6",
"@babel/preset-typescript": "^7.18.6",
"@types/node": "^18.0.0",
"@types/webpack": "^5.28.0",
"babel-loader": "^8.2.5",
"css-loader": "^6.7.1",
"css-minimizer-webpack-plugin": "^4.0.0",
"less": "^4.1.3",
"less-loader": "^11.0.0",
"mini-css-extract-plugin": "^2.6.1",
"postcss-loader": "^7.0.0",
"style-loader": "^3.3.1",
"terser-webpack-plugin": "^5.3.3",
"ts-node": "^10.8.2",
"typescript": "^4.7.4",
"webpack": "^5.73.0",
"webpack-cli": "^4.10.0"
}
}然后運行: npm run build:lib-esm, 此時dist目錄結構如下:
dist
├── lib-esm
│ ├── bar.js
│ └── index.js
├── typings
│ ├── bar.d.ts
│ ├── bar.d.ts.map
│ ├── index.d.ts
│ └── index.d.ts.map
└── umd
├── index.css
├── index.js
├── index.js.map
├── index.min.css
├── index.min.js
└── index.min.js.map
3 directories, 12 files多出了兩個子目錄分別為lib-esm和typings, 分別放著es6模塊格式的javascript輸出文件和typescript類型聲明文件.
完善package.json文件
到目前為止, package.json的scripts配置中, 已經(jīng)有了build:umd和build:lib-esm用于構建umd格式的輸出和esm格式的輸出, 現(xiàn)在我們再向添加一個build用來組合build:umd和build:lib-esm并進行最終的構建, 再次之前先安裝一個依賴shx, 用于跨平臺執(zhí)行一些shell腳本: npm i -D shx;
更新package.json文件:
package.json
{
"name": "loaf",
"version": "1.0.0",
"description": "A demo shows how to create & build a javascript library with webpack & typescript",
"main": "index.js",
"scripts": {
"build": "shx rm -rf dist/** && npm run build:umd && npm run build:lib-esm",
"build:umd": "webpack -c webpack.config.ts --node-env production --env NODE_ENV=production",
"build:lib-esm": "tsc -p tsconfig.json --declarationDir ./dist/typings -m es6 --outDir dist/lib-esm",
"test": "npm run test"
},
"keywords": [
"demo"
],
"author": "laggage",
"license": "MIT",
"devDependencies": {
"@babel/core": "^7.18.6",
"@babel/preset-env": "^7.18.6",
"@babel/preset-typescript": "^7.18.6",
"@types/node": "^18.0.0",
"@types/webpack": "^5.28.0",
"babel-loader": "^8.2.5",
"css-loader": "^6.7.1",
"css-minimizer-webpack-plugin": "^4.0.0",
"less": "^4.1.3",
"less-loader": "^11.0.0",
"mini-css-extract-plugin": "^2.6.1",
"postcss-loader": "^7.0.0",
"shx": "^0.3.4",
"style-loader": "^3.3.1",
"terser-webpack-plugin": "^5.3.3",
"ts-node": "^10.8.2",
"typescript": "^4.7.4",
"webpack": "^5.73.0",
"webpack-cli": "^4.10.0"
}
}package.json文件生成typescript聲明文件所在的路徑(可以參考typescript官網(wǎng):Including declarations in your npm package):
package.json
{
"name": "loaf",
"version": "1.0.0",
"description": "A demo shows how to create & build a javascript library with webpack & typescript",
"main": "index.js",
"typings": "./typings",
"scripts": {
"build": "shx rm -rf dist/** && npm run build:umd && npm run build:lib-esm",
"build:umd": "webpack -c webpack.config.ts --node-env production --env NODE_ENV=production",
"build:lib-esm": "tsc -p tsconfig.json --declarationDir ./dist/typings -m es6 --outDir dist/lib-esm",
"test": "npm run test"
},
"keywords": [
"demo"
],
"author": "laggage",
"license": "MIT",
"devDependencies": {
"@babel/core": "^7.18.6",
"@babel/preset-env": "^7.18.6",
"@babel/preset-typescript": "^7.18.6",
"@types/node": "^18.0.0",
"@types/webpack": "^5.28.0",
"babel-loader": "^8.2.5",
"css-loader": "^6.7.1",
"css-minimizer-webpack-plugin": "^4.0.0",
"less": "^4.1.3",
"less-loader": "^11.0.0",
"mini-css-extract-plugin": "^2.6.1",
"postcss-loader": "^7.0.0",
"shx": "^0.3.4",
"style-loader": "^3.3.1",
"terser-webpack-plugin": "^5.3.3",
"ts-node": "^10.8.2",
"typescript": "^4.7.4",
"webpack": "^5.73.0",
"webpack-cli": "^4.10.0"
}
}package.json中添加exports配置聲明模塊導出路徑
package.json中的exports字段用于告訴使用者引用此庫時從哪里尋找對應的模塊文件. 比如使用者可能通過esm模塊引用此庫:
import { Foo } from 'loaf';
const foo = new Foo();此時如果我們的package.json中沒有指定exports字段, 那么模塊系統(tǒng)會去尋找node_modules/index.js, 結果肯定是找不到的, 因為我們真正的esm格式的輸出文件應該是在node_modules/loaf/lib-esm中的
于是我們可以這樣來配置exports:
package.json
{
"name": "loaf",
"version": "1.0.0",
"description": "A demo shows how to create & build a javascript library with webpack & typescript",
"main": "index.js",
"typings": "./typings",
"exports": {
"./*": "./lib-esm/*",
"./umd/*": "./umd"
},
"scripts": {
"build": "shx rm -rf dist/** && npm run build:umd && npm run build:lib-esm",
"build:umd": "webpack -c webpack.config.ts --node-env production --env NODE_ENV=production",
"build:lib-esm": "tsc -p tsconfig.json --declarationDir ./dist/typings -m es6 --outDir dist/lib-esm",
"test": "npm run test"
},
"keywords": [
"demo"
],
"author": "laggage",
"license": "MIT",
"devDependencies": {
"@babel/core": "^7.18.6",
"@babel/preset-env": "^7.18.6",
"@babel/preset-typescript": "^7.18.6",
"@types/node": "^18.0.0",
"@types/webpack": "^5.28.0",
"babel-loader": "^8.2.5",
"css-loader": "^6.7.1",
"css-minimizer-webpack-plugin": "^4.0.0",
"less": "^4.1.3",
"less-loader": "^11.0.0",
"mini-css-extract-plugin": "^2.6.1",
"postcss-loader": "^7.0.0",
"shx": "^0.3.4",
"style-loader": "^3.3.1",
"terser-webpack-plugin": "^5.3.3",
"ts-node": "^10.8.2",
"typescript": "^4.7.4",
"webpack": "^5.73.0",
"webpack-cli": "^4.10.0"
}
}用api-extractor提取出干凈的.d.ts
在上面的用tsc輸出esm和類型聲明文件這一段中, 我們通過tsc命令輸出了typescript了類型聲明文件到dist/types目錄下, 這個目錄下有兩個.d.ts文件, 分別是bar.d.ts和foo.d.ts, 通常是希望這些聲明文件都在一個文件index.d.ts中的, 如果他們分散開了, 以本庫為例, 如果我要使用本庫中的Bar類, 那么我可能需要這樣來導入:
import { Bar } from 'loaf/typings/bar';我不覺得的這種導入方式是好的做法, 理想的導入方式應該像下面這樣:
import { Bar } from 'loaf';所以接下來, 還要引入微軟提供的api-extractor
配置使用API extractor
安裝依賴:
npm install -D @microsoft/api-extractor
再全局安裝下:
npm install -g @microsoft/api-extractor
生成api-extractor.json
api-extractor init
稍微修改下api-extractor.json
<
api-extractor.json
{
...
"scripts": {
"build": "shx rm -rf dist/** && npm run build:umd && npm run build:lib-esm && npm run build:extract-api",
"build:umd": "webpack -c webpack.config.ts --node-env production --env NODE_ENV=production",
"build:lib-esm": "tsc -p tsconfig.json --declarationDir ./dist/typings-temp -m es6 --outDir dist/lib-esm",
"build:extract-api": "api-extractor run && shx rm -rf dist/typings-temp",
"build:extract-api-local": "shx mkdir -p ./etc && npm run build:lib-esm && api-extractor run -l",
"test": "npm run test"
},
...
}更新package.json
/**
*
* @internal
*/
export class Bar {
bar() {}
}注意, 這里處理新增了一個build:extract-api到scripts配置中, 還修改了build:lib-esm的配置, 將其輸出的typescript類型聲明文件放到了, typings-temp目錄中, 最后這個目錄是要刪除; 還要注意, 每次提交代碼到版本管理工具前, 要先運行npm run build:extract-api-local, 這個命令會生成./etc/<libraryName>.api.md文件, 這個文件是api-extractor生成的api文檔, 應該要放到版本管理工具中去的, 以便可以看到每次提交代碼時API的變化.
用@internal標注只希望在內(nèi)部使用的class
比如, 我希望Bar類不能被此庫的使用者使用, 我可以加上下面這段注釋
/**
*
* @internal
*/
export class Bar {
bar() {}
}然后來看看生成的index.d.ts文件:
/**
*
* @internal
*/
declare class Bar {
bar(): void;
}
export declare class Foo {
private _bar;
constructor(_bar?: Bar);
foo(): void;
loaf(): void;
}
export { }可以看出index.d.ts文件中雖然declare了Bar, 但是并未導出Bar
這個特性是由api-extractor提供的, 更多api-extractor的內(nèi)容移步官方文檔
小結
至此, 我們就可以構建一個可以通過諸如AMD CommonJs esm等js模塊系統(tǒng)或是使用script標簽的方式引用的js庫了, 主要用到了webpack typescript api-extractor這些工具. 完整的示例代碼可以訪問github-laggage/loaf查看.
到此這篇關于typescript+webpack構建一個js庫的文章就介紹到這了,更多相關webpack構建js庫內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關文章希望大家以后多多支持腳本之家！
相關文章
JS創(chuàng)建或填充任意長度數(shù)組的小技巧匯總
在JavaScript 中,我們往往會遇到需要使用某些默認值來填充數(shù)組的情況,那么都有哪些方式可以完成這樣的任務呢?這篇文章主要給大家介紹了關于JS創(chuàng)建或填充任意長度數(shù)組的小技巧,需要的朋友可以參考下2021-10-10
開始接觸這門語言時，可能都會覺得這門語言缺少訪問控制符(如public、private、protected)，從而導致不能定義私有變量和私有方法。但經(jīng)過進一步了解就會知道javascript同樣可以有私有變量。2010-02-02
javascript 動態(tài)創(chuàng)建表格
這篇文章主要介紹了javascript 動態(tài)創(chuàng)建表格,需要的朋友可以參考下2015-01-01
這篇文章主要介紹了json 字符串之間的相互轉換 ,通過eval()函數(shù)可以將JSON字符串轉化為對象，本需要的朋友可以參考下2014-08-08
這篇文章主要為大家詳細介紹了JS組件Bootstrap Table使用方法，具有一定的實用性和參考價值，感興趣的小伙伴們可以參考一下2016-10-10
axios是一個基于Promise用于瀏覽器和nodejs的HTTP客戶端,下面這篇文章主要給大家介紹了關于axios概念介紹和基本使用的相關資料,文中通過實例代碼介紹的非常詳細,需要的朋友可以參考下2022-06-06
這篇文章主要介紹了原生js實現(xiàn)會動的小球，碰撞檢測功能，文中示例代碼介紹的非常詳細，具有一定的參考價值，感興趣的小伙伴們可以參考一下2020-12-12
[紅色]如何實現(xiàn)iframe(嵌入式幀)的自適應高度...2006-07-07
web-view組件是一個可以用來承載網(wǎng)頁的容器,會自動鋪滿整個小程序頁面,這篇文章主要介紹了微信小程序中的webview組件的基本使用方法、應用場景、通信機制以及注意事項,需要的朋友可以參考下2025-03-03
這篇文章主要介紹了JS去掉字符串前后空格、阻止表單提交的實現(xiàn)代碼，代碼簡單易懂，非常不錯，具有參考借鑒價值,需要的朋友可以參考下2017-06-06