@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 under lib.

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 default export 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 the dist/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 the dist/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