@absolunet/library-builder 中文文档教程
@absolunet/library-builder
JS library builder via webpack
编写您的 JS 库并将其导出到 Node.js、浏览器或 kafe (ES5/ES6+) 通过 webpack 和 Babel
Install
$ npm install @absolunet/library-builder
Usage
强加一些约定以更好地工作
Project structure
index.js
webpack.config.js
dist/
↳ browser.js
↳ browser-es5.js
↳ kafe.js
↳ kafe-es5.js
↳ node.js
lib/
- Each build will be outputted in a
dist
folder with a predefined name. - Main script would be under
index.js
with its subfiles underlib
.
Code conventions
- Internal dependencies (which will be outputted in the final built file) are dealt with the
ES6 modules (import / export)
syntax. - External dependencies (which will be referenced in the final built file) are dealt with the
Node.js modules (require)
syntax. index.js
should end with a defaultexport
statement representing the whole library.
Node.js build
- External dependencies will be left untouched in the final built file thus making classic
require()
Node.js statements. (See webpack configuration) - Final usage will look like this
const mylibrary = require('@organisation/my-library'); // dist/node.js
Browser build
- External dependencies will be transform to a variable assignation, assuming that the dependencies are already loaded elsewhere. (See webpack configuration)
const cl = require('cool-lib');
// Becomes
const cl = window.coolLib;
- Final usage will look like this
console.log(window.mylibrary); // dist/browser.js
- The
dist/browser.js
is a pure ES6+ built and thedist/browser-es5.js
is the same but with a Babel compilation to ES5 syntax.
kafe build
- Is the same as the browser build but with the output scoped under
window.kafe
- Final usage will look like this
console.log(window.kafe.mylibrary); // dist/kafe.js
- The
dist/kafe.js
is a pure ES6+ built and thedist/kafe-es5.js
is the same but with a Babel compilation to ES5 syntax.
webpack Configuration
你的 webpack.config.js
应该看起来像这样
const LibraryBuilder = require('@absolunet/library-builder');
const builder = new LibraryBuilder({
name: 'mylibrary',
root: __dirname
});
//-- Node.js
const nodeExternals = {
externals: [
'cool-lib', // Dependencies to reference and not include
'meaningful-helper'
]
};
//-- Browser
const browserExternals = {
externals: {
'cool-lib': 'window.coolLib', // Dependencies to reference and their variable counterpart
'meaningful-helper': 'window.mnfHelper'
}
};
module.exports = [
builder.config.mergeWithNode(nodeExternals), // If you want a Node.js build
builder.config.mergeWithBrowser(browserExternals), // If you want a browser ES6+ build
builder.config.mergeWithBrowserES5(browserExternals), // If you want a browser ES5 build
builder.config.mergeWithKafe(browserExternals), // If you want a kafe ES6+ build
builder.config.mergeWithKafeES5(browserExternals) // If you want a kafe ES5 build
];
package.json
你的 package.json
应该包含这些条目
{
"main": "dist/node.js",
"browser": "dist/browser.js -OR- dist/kafe.js",
"scripts": {
"build": "node node_modules/@absolunet/library-builder/bin/build.js"
},
"devDependencies": {
"@absolunet/library-builder": "1.1.0",
"lodash.merge": "4.6.1"
},
"dependencies": {
"cool-lib": "^1.2.3",
"meaningful-helper": "^4.5.6"
}
}
这种构建方式你只需要运行 npm 运行构建
API
constructor(options)
options.name
必需
类型:字符串
包名称(用于 kafe 构建)
options.root
必需
类型:字符串
根文件夹的路径(通常是__dirname
)
API - Configuration
config.node
Node.js 导出的
基本 webpack 配置
config.browser
浏览器 ES6+ 导出的
基本 webpack 配置
config.browserES5
用于 ES6+的基本 webpack 配置浏览器 ES5 导出(通过 Babel)
config.kafe
kafe ES6+ 导出的
基本 webpack 配置
config.kafeES5
kafe ES5 导出的基本 webpack 配置(通过 Babel)
config.mergeWithNode(config)
返回 Object
webpack 配置
将自定义配置添加到基本配置
config
必需
类型:对象
要与 Node.js 配置合并的 webpack 配置
config.mergeWithBrowser(config)
返回 Object
webpack 配置
将自定义配置添加到基本配置
config
必需
类型:对象
webpack 配置与浏览器 ES6+ 配置合并
config.mergeWithBrowserES5(config)
返回 Object
webpack 配置
将自定义配置添加到基本配置
config
必需
类型:对象
要与浏览器 ES5 配置合并的 webpack 配置
config.mergeWithKafe(config)
返回 Object
webpack 配置
将自定义配置添加到基本配置
config
必需
类型:对象
webpack 配置与 kafe ES6+ 配置合并
config.mergeWithKafeES5(config)
返回 Object
webpack 配置
将自定义配置添加到基本配置
config
必需
类型:对象
webpack 配置与 kafe ES5 配置合并
License
麻省理工学院 © Absolunet
@absolunet/library-builder
JS library builder via webpack
Write your JS library and export it for Node.js, browser or kafe (ES5/ES6+) via webpack and Babel
Install
$ npm install @absolunet/library-builder
Usage
Imposes some conventions to work well
Project structure
index.js
webpack.config.js
dist/
↳ browser.js
↳ browser-es5.js
↳ kafe.js
↳ kafe-es5.js
↳ node.js
lib/
- Each build will be outputted in a
dist
folder with a predefined name. - Main script would be under
index.js
with its subfiles underlib
.
Code conventions
- Internal dependencies (which will be outputted in the final built file) are dealt with the
ES6 modules (import / export)
syntax. - External dependencies (which will be referenced in the final built file) are dealt with the
Node.js modules (require)
syntax. index.js
should end with a defaultexport
statement representing the whole library.
Node.js build
- External dependencies will be left untouched in the final built file thus making classic
require()
Node.js statements. (See webpack configuration) - Final usage will look like this
const mylibrary = require('@organisation/my-library'); // dist/node.js
Browser build
- External dependencies will be transform to a variable assignation, assuming that the dependencies are already loaded elsewhere. (See webpack configuration)
const cl = require('cool-lib');
// Becomes
const cl = window.coolLib;
- Final usage will look like this
console.log(window.mylibrary); // dist/browser.js
- The
dist/browser.js
is a pure ES6+ built and thedist/browser-es5.js
is the same but with a Babel compilation to ES5 syntax.
kafe build
- Is the same as the browser build but with the output scoped under
window.kafe
- Final usage will look like this
console.log(window.kafe.mylibrary); // dist/kafe.js
- The
dist/kafe.js
is a pure ES6+ built and thedist/kafe-es5.js
is the same but with a Babel compilation to ES5 syntax.
webpack Configuration
Your webpack.config.js
should look like this
const LibraryBuilder = require('@absolunet/library-builder');
const builder = new LibraryBuilder({
name: 'mylibrary',
root: __dirname
});
//-- Node.js
const nodeExternals = {
externals: [
'cool-lib', // Dependencies to reference and not include
'meaningful-helper'
]
};
//-- Browser
const browserExternals = {
externals: {
'cool-lib': 'window.coolLib', // Dependencies to reference and their variable counterpart
'meaningful-helper': 'window.mnfHelper'
}
};
module.exports = [
builder.config.mergeWithNode(nodeExternals), // If you want a Node.js build
builder.config.mergeWithBrowser(browserExternals), // If you want a browser ES6+ build
builder.config.mergeWithBrowserES5(browserExternals), // If you want a browser ES5 build
builder.config.mergeWithKafe(browserExternals), // If you want a kafe ES6+ build
builder.config.mergeWithKafeES5(browserExternals) // If you want a kafe ES5 build
];
package.json
Your package.json
should contain these entries
{
"main": "dist/node.js",
"browser": "dist/browser.js -OR- dist/kafe.js",
"scripts": {
"build": "node node_modules/@absolunet/library-builder/bin/build.js"
},
"devDependencies": {
"@absolunet/library-builder": "1.1.0",
"lodash.merge": "4.6.1"
},
"dependencies": {
"cool-lib": "^1.2.3",
"meaningful-helper": "^4.5.6"
}
}
This way to build you only need to run npm run build
API
constructor(options)
options.name
Required
Type: String
Package name (for kafe build)
options.root
Required
Type: String
Path to root folder (typically __dirname
)
API - Configuration
config.node
Base webpack configuration for Node.js export
config.browser
Base webpack configuration for browser ES6+ export
config.browserES5
Base webpack configuration for browser ES5 export (via Babel)
config.kafe
Base webpack configuration for kafe ES6+ export
config.kafeES5
Base webpack configuration for kafe ES5 export (via Babel)
config.mergeWithNode(config)
Returns Object
webpack configuration
Add custom configuration to base configuration
config
Required
Type: Object
webpack configuration to merge with Node.js configuration
config.mergeWithBrowser(config)
Returns Object
webpack configuration
Add custom configuration to base configuration
config
Required
Type: Object
webpack configuration to merge with browser ES6+ configuration
config.mergeWithBrowserES5(config)
Returns Object
webpack configuration
Add custom configuration to base configuration
config
Required
Type: Object
webpack configuration to merge with browser ES5 configuration
config.mergeWithKafe(config)
Returns Object
webpack configuration
Add custom configuration to base configuration
config
Required
Type: Object
webpack configuration to merge with kafe ES6+ configuration
config.mergeWithKafeES5(config)
Returns Object
webpack configuration
Add custom configuration to base configuration
config
Required
Type: Object
webpack configuration to merge with kafe ES5 configuration
License
MIT © Absolunet