An automatic library bundler powered by Rollup.js.
⚠️ Bundlib is under development, please file a new issue if you find any issue or bug, suggestions are welcome as well.
- Install
- Build
- Configuration
- Advanced Configuration
- Options
- Selective Options
- Using the CLI tool
- Using Bundlib programmatically
- Types
- Features
npm i -D bundlib
Bundlib will try to find your entry point file in the src
folder. You can manually set your entry points using the input
option.
To build a CommonJS Module
simply add a "main"
field to your package.json
pointing to the output file, see the configuration section for extra options.
To build a ES Module
add a "module"
field to your package.json
pointing to the output file, see the configuration section for extra options.
For IIFE
, AMD
or UMD
builds, add a "browser"
field to your package.json
. The default format is "umd"
but it can be changed to "iife"
or "amd"
using the format
option, see the configuration section for more info and extra options.
Bundlib will configure Rollup according to you package.json
data, see Advanced Configuration for more information.
The "main"
field will be used as your CommonJS module output, if not present, CommonJS Module build will be skipped. You can skip the build manually using the skip
option.
The "module"
field will be used as your ES Module output, if not present, ES Module build will be skipped. You can skip the build manually using the skip
option. "jsnext:main"
field will also be honored if "module"
field is not present, but it is recommended to use the "module"
field.
The "browser"
field will be used as your Browser build output, if not present, Browser build will be skipped. You can skip the build manually using the skip
option. Bundlib only supports string
type "browser"
field, it will throw otherwise.
The "bin"
field will be used as your Binary build output, if not present, Binary build will be skipped. You can skip the build manually using the skip
option. Bundlib only supports string
type "bin"
field, it will throw otherwise.
The "types"
field will be used as your Types output if you are using typescript
. You can skip types generation using the skip
option. "typings"
field will also be honored if "types"
field is not present.
The "dependencies"
field will be used to detect installed packages, it will also be used to set external dependencies for your CommonJS module, ES module, and Binary builds, for Browser build dependencies will be bundled into the output file unless otherwise specified using the "globals"
option.
The "devDependencies"
field will be used to detect installed packages.
The "peerDependencies"
field will be used as external dependencies for your CommonJS module,, ES module, and Binary builds.
The "bundlib"
field can be used for advanced configuration, see Advanced Configuration for more information.
Advanced configuration can be done using the "bundlib"
field in your package.json
or by using one of the supported configuration files.
Set "bundlib"
field in your package.json
to an object
with your configuration. See options for more information.
example
// package.json
{
"name": "my-lib",
"version": "1.0.0",
"browser" : "dist/my-lib.amd.js",
"bundlib": {
"format": "amd"
}
...
}
You can also set "bundlib"
field in package.json
to a string
as a path, relative to the project root, pointing to a .json
, .yaml
, .yml
or .js
configuration file.
example
// package.json
{
"name": "my-lib",
"version": "1.0.0",
"browser" : "dist/my-lib.amd.js",
"bundlib": "custom-options.yaml"
// ...
}
then...
# custom-options.yaml
format: amd
If "bundlib"
field not present in your package.json
, Bundlib will try to find your configuration file using the following order...
- .bundlibrc (json or yaml format)
- .bundlibrc.json
- .bundlibrc.yaml
- .bundlibrc.yml
- .bundlibrc.js
- bundlib.config.js
- bundlib.config.cjs
- bundlib.config.mjs
- bundlib.config.ts
See the list of options below.
The option object may contain any of the following properties. Any invalid or unknown option will cause Bundlib to throw at build time. Any option or sub-option set to null
will be ignored.
input: string | SelectiveOption;
The path to the files to be used as entry points for each of your builds.
This option supports object
based selective format
. See Selective Options for more information.
sourcemap: boolean | 'inline' | 'hidden' | SelectiveOption;
default true;
Whether or not to generate source maps, See Rollup documentation for more information. If not specified or set to null
it will default to true
.
This option supports object
based and string
based selective format
. See Selective Options for more information.
esModule: boolean | SelectiveOption;
default false;
Whether or not to add a __esModule: true
property to your module. If esModule = true
it will affect all builds.
This option supports object
based and string
based selective format
. See Selective Options for more information.
interop: boolean | SelectiveOption;
default false;
Whether or not to add an interop block. If interop = true
it will affect all builds.
This option supports object
based and string
based selective format
. See Selective Options for more information.
chunks: Record<string, string>;
A map of chunks to be built as CommonJS
modules. The object key
represents the input file and the value
represents the output file, relative to the project root.
Files created using this option won't be bundled into the CommonJS
and Binary
builds and will be imported (required) instead.
format: "iife" | "amd" | "umd";
default "umd";
Defines the format to be used for the Browser
build.
name: string;
The name to be used to expose your library to the global scope in a IIFE
or UMD
browser build. If not provided it will default to the camelcased, unscoped "name"
field in package.json
or the camelcased directory name. If none of those can be obtained, it will throw at build time.
id: string;
Optional amd id for AMD
or UMD
build.
If not present, AMD
define
method will use no id.
extend: boolean;
default false;
Whether or not to extend the globally exposed name on a IIFE
or UMD
build.
globals: { [name: string]: string } | string[];
default {};
Object
or array
to map names to globals in Browser
build.
min: boolean | SelectiveOption;
default false;
Defines which files should be used to build an additional minified version, if true
will affect all modules. The minified file will be renamed from *.ext
to *.min.ext
. This option will override the default behavior of the --dev
, -d
cli option , which means only the minified version will be actually minified, the normal version will NOT be minified even if you don't set the --dev
, -d
cli option.
This option supports object
based and string
based selective format
. See Selective Options for more information.
equals: boolean;
default false;
Transforms type export for CommonJS module using export = ...
instead of export default ...
.
⚠️ Note that this option should only be used when your library has adefault
export and nonamed
exports, otherwise it may cause the type declarations to become invalid.
cache: string;
default "node_modules/.cache/bundlib";
Defines the directory to be used for cache, relative to the project root.
project: string | SelectiveOption;
default "tsconfig.json"
Defines the location of typescript tsconfig.json
file, relative to the project root.
This option supports object
based selective format
. See Selective Options for more information.
min: boolean | SelectiveOption;
default false;
Defined which build Bundlib should skip.
This option supports object
based and string
based selective format
. See Selective Options for more information.
Some options support a selective format to allow for a more flexible configuration. See SelectiveOption
type for more information.
Note that some options support different selective formats. Boolean
type options support string
based format and object
based format while others support only object
based format.
See input, sourcemap, esModule, interop, min and project options.
object
based format works by preserving the default value and overriding it with the provided configuration.
example
// assuming default = false...
{
main: true
}
// ... will resolve to
/*
{
main: true,
...others: false
}
*/
You can override the default value as well using the "default"
object key.
example
// assuming default = false
{
default: true,
bin: false
}
// ... will resolve to
/*
{
bin: false,
...others: true
}
*/
The "api"
object key represents main
, module
and browser
.
example
// assuming default = false...
{
api: true
}
// ... will resolve to
/*
{
main: true,
module: true,
browser: true,
...others: false
}
*/
string
based format works in a different way, it does not preserve the default value, included build types will be set to true
and the others will be set to false
. It can be a string
or an string array
.
example
'module'
// ... will resolve to
/*
{
module: true,
...others: false
}
*/
example
['main', 'module']
// ... will resolve to
/*
{
main: true,
module: true,
...others: false
}
*/
example
'api'
// ... will resolve to
/*
{
main: true,
module: true,
browser: true,
...others: false
}
*/
bundlib [options]
Combine options according to your needs. Run bundlib --help
or bundlib -h
for a detailed help.
Create development, not minified builds. Builds affected by the min
option will ignore this option.
Run Bundlib in watch mode.
Prevent messages from showing in the console.
Show Bundlib version.
Show detailed help about the CLI tool.
example
// rollup.config.js
import { configsFromPkg } from "bundlib";
const dev = !process.env.production;
export default configsFromPkg(
process.cwd(),
{ dev },
);
function readPkg(cwd: string): Promise<BundlibPkgJson>;
Reads the content of package.json
(it will throw a TypeError if its not an object) and return it.
function analyzePkg(
cwd: string,
pkg: PkgJson = read(cwd + "/package.json"),
): Promise<PkgAnalyzed>;
Analyzes package.json
and returns a Promise
that resolves to useful normalized information, see PkgAnalyzed
. If pkg
not provided it will be read from the current working directory cwd
.
function configsFromPkg(
cwd: string,
options: { dev? boolean, watch?: boolean } | null | false,
pkg: PkgJson = read(cwd + "/package.json"),
): Promise<RollupOptions[]>;
Returns a Promise
that resolves to an array of Rollup configs based on the content of package.json
. If pkg
not provided it will be read from the current working directory cwd
.
interface PkgAnalyzed {
cwd: string;
pkg: PkgJson;
main: ModuleBuildOptions | null;
module: ModuleBuildOptions | null;
browser: BrowserBuildOptions | null;
bin: ModuleBuildOptions | null;
types: TypesBuildOptions | null;
chunks: Record<string, string> | null;
dependencies: {
runtime: { [name: string]: string } | null;
dev: { [name: string]: string } | null;
peer: { [name: string]: string } | null;
};
cache: string | null;
}
see also: ModuleBuildOptions
, BrowserBuildOptions
and TypesBuildOptions
.
interface ModuleBuildOptions {
input: string | null;
output: string;
sourcemap: boolean | 'inline' | 'hidden';
esModule: boolean;
interop: boolean;
min: boolean;
project: string | null;
}
interface BrowserBuildOptions extends ModuleBuildOptions {
format: "iife" | "amd" | "umd";
name: string | null;
id: string | null;
globals: Record<string, string> | null;
extend: boolean;
}
interface TypesBuildOptions {
output: string;
equals: boolean;
}
interface ObjectBasedSelectiveOption<T> {
default: T;
[K: BuildType]: T;
}
type StringBasedSelectiveOption = BuildType | BuildType[];
type BuildType = 'main' | 'module' | 'browser' | 'bin' | 'api' | ...others;
- Uses
"main"
field in yourpackage.json
to build aCommonJS Module
. - Uses
"module"
field in yourpackage.json
(or"jsnext:main"
field) to build anES Module
. - Uses
"browser"
field in yourpackage.json
to build aBrowser
module. It only supports"browser"
field asstring
,object
format not supported. - Uses
"bin"
field in yourpackage.json
to build aBinary
module. It only supports"bin"
field asstring
,object
format not supported. - Uses
"types"
field in yourpackage.json
(or"typings"
field) as path for types declarations. - Uses
"dependencies"
and"peerDependencies"
to set external modules forCommonJS Module
,ES Module
andBinary
builds. Dependencies will be bundled by default inBrowser
builds, unless otherwise specified using theglobal
option. - Skip any build based on options.
- Uses
rollup-plugin-typescript2
iftypescript
installed as runtime or dev dependency. - Uses
@rollup/plugin-babel
if@babel/core
installed as runtime or dev dependency, otherwise it uses@rollup/plugin-buble
. - Uses
rollup-plugin-strip-shebang
androllup-plugin-add-shebang
to ensure a shebang on binary build. - Uses
@rollup/plugin-json
to import JSON files. - Uses
@rollup/plugin-eslint
ifeslint
installed as runtime or dev dependency. - Uses
@rollup/plugin-terser
to minify production build. - Uses
chokidar
for file watch if installed.
- Honor
"type"
field inpackage.json
- Honor
"exports"
field inpackage.json
- Support
package.json
"bin"
field as an object for multiple cli commands
- Type declarations for chunks created using the
chunks
options may not work properly.
MIT © 2019 Manuel Fernández