Bundlib

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.

In this guide

• Install
• Build
• Configuration
• Advanced Configuration
• Options
  • input
  • sourcemap
  • esModule
  • interop
  • chunks
  • format
  • name
  • id
  • extend
  • globals
  • min
  • equals
  • cache
  • project
  • skip
• Selective Options
  • Object based selective format
  • String based selective format
• Using the CLI tool
• Using Bundlib programmatically
• Types
• Features

Install

npm i -D bundlib

Build

Bundlib will try to find your entry point file in the src folder. You can manually set your entry points using the input option.

CommonJS module

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.

ES module

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.

IIFE, AMD and UMD build

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.

Configuration

Automatic Configuration

Bundlib will configure Rollup according to you package.json data, see Advanced Configuration for more information.

"main"

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.

"module" or "jsnext:main"

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.

"browser"

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.

"bin"

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.

"types" or "typings"

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.

"dependencies"

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.

"devDependencies"

The "devDependencies" field will be used to detect installed packages.

"peerDependencies"

The "peerDependencies" field will be used as external dependencies for your CommonJS module,, ES module, and Binary builds.

"bundlib"

The "bundlib" field can be used for advanced configuration, see Advanced Configuration for more information.

Advanced Configuration

Advanced configuration can be done using the "bundlib" field in your package.json or by using one of the supported configuration files.

Configuration in package.json

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

Configuration files

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

See the list of options below.

Options

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

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

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

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

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

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

format: "iife" | "amd" | "umd";

default "umd";

Defines the format to be used for the Browser build.

name

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

id: string;

Optional amd id for AMD or UMD build.

If not present, AMD define method will use no id.

extend

extend: boolean;

default false;

Whether or not to extend the globally exposed name on a IIFE or UMD build.

globals

globals: { [name: string]: string } | string[];

default {};

Object or array to map names to globals in Browser build.

min

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

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 a default export and no named exports, otherwise it may cause the type declarations to become invalid.

cache

cache: string;

default "node_modules/.cache/bundlib";

Defines the directory to be used for cache, relative to the project root.

project

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.

skip

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.

Selective Options

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 selective format

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
}
*/

The special default property

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 special api property

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 selective format

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.

As string

example

'module'

// ... will resolve to

/*
{
  module: true,
  ...others: false
}
*/

As array of strings

example

['main', 'module']

// ... will resolve to

/*
{
  main: true,
  module: true,
  ...others: false
}
*/

The special api build type

example

'api'

// ... will resolve to

/*
{
  main: true,
  module: true,
  browser: true,
  ...others: false
}
*/

Using the CLI tool

bundlib [options]

CLI Options

Combine options according to your needs. Run bundlib --help or bundlib -h for a detailed help.

--dev, -d

Create development, not minified builds. Builds affected by the min option will ignore this option.

--watch, -w

Run Bundlib in watch mode.

--silent, -s

Prevent messages from showing in the console.

--version, -v

Show Bundlib version.

--help, -h

Show detailed help about the CLI tool.

Using Bundlib programmatically

example

// rollup.config.js

import { configsFromPkg } from "bundlib";

const dev = !process.env.production;

export default configsFromPkg(
  process.cwd(),
  { dev },
);

analyzePkg

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.

configsFromPkg

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.

Types

PkgAnalyzed

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.

ModuleBuildOptions

interface ModuleBuildOptions {
  input: string | null;
  output: string;
  sourcemap: boolean | 'inline' | 'hidden';
  esModule: boolean;
  interop: boolean;
  min: boolean;
  project: string | null;
}

BrowserBuildOptions

interface BrowserBuildOptions extends ModuleBuildOptions {
  format: "iife" | "amd" | "umd";
  name: string | null;
  id: string | null;
  globals: Record<string, string> | null;
  extend: boolean;
}

TypesBuildOptions

interface TypesBuildOptions {
  output: string;
  equals: boolean;
}

SelectiveOption

interface ObjectBasedSelectiveOption<T> {
  default: T;
  [K: BuildType]: T;
}

type StringBasedSelectiveOption = BuildType | BuildType[];

type BuildType = 'main' | 'module' | 'browser' | 'bin' | 'api' | ...others;

Features

• Uses "main" field in your package.json to build a CommonJS Module.
• Uses "module" field in your package.json (or "jsnext:main" field) to build an ES Module.
• Uses "browser" field in your package.json to build a Browser module. It only supports "browser" field as string, object format not supported.
• Uses "bin" field in your package.json to build a Binary module. It only supports "bin" field as string, object format not supported.
• Uses "types" field in your package.json (or "typings" field) as path for types declarations.
• Uses "dependencies" and "peerDependencies" to set external modules for CommonJS Module, ES Module and Binary builds. Dependencies will be bundled by default in Browser builds, unless otherwise specified using the global option.
• Skip any build based on options.
• Uses rollup-plugin-typescript2 if typescript 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 and rollup-plugin-add-shebang to ensure a shebang on binary build.
• Uses @rollup/plugin-json to import JSON files.
• Uses@rollup/plugin-eslint if eslint installed as runtime or dev dependency.
• Uses rollup-plugin-terser to minify production build.
• Uses chokidar for file watch if installed.

Future Features

• Honor "type" field in package.json
• Honor "exports" field in package.json
• Support package.json "bin" field as an object for multiple cli commands

Known issues

• Type declarations for chunks created using the chunks options may not work properly.

License

MIT © 2019 Manuel Fernández