Bundlib

A javascript library bundler powered by Rollup.js and optionally Typescript.

⚠️ Bundlib is under active development, please file a new issue if you find any issue or bug, suggestions are welcome as well.

In this guide

• Install
• First steps
• Build
• Configuration
• CLI
• API
• Types
• Known Issues
• Features

Install

npm i -D bundlib

First steps

Bundlib will use src/index.ts as entry file for your library by default, it can be configured using the input option. Add the corresponding scripts to your package.json and run them. see below for CLI options.

Build

CommonJS module

Building a CommonJS Module is as simple as adding a "main" field to your package.json pointing to the output file, and bundlib will build it for you. see the configuration section for extra options.

ES module

To build a ES Module simply 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 or browser option, see the configuration section for more info.

Configuration

Configuration is done through the "bundlib" field in your package.json. See the list of options below.

example

// package.json
{
  "version": "1.0.0",
  "name": "my-lib",
  "browser" : "dist/my-lib.amd.js",
  // ...
  "bundlib": {
    "format": "amd"
  }
  // ...
}

Options

The "bundlib" field in package.json 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 | InputOptions;

interface InputOptions {
  api?: string;
  bin?: string;
}

default {
  api: "src/index.ts";
  bin: "src-bin/index.ts";
};

The path to the file(s) to be used as entry point(s) for modules and binary. If a string is provided, it will be used as API entry point and Binary entry point will be set to the default value.

sourcemap

sourcemap: boolean | "inline";

default true;

Whether or not to generate source maps. Anything other than false or "inline" will default to true.

This option can be overridden using per-build options. See main, module, browser and bin options.

esModule

esModule: BuildType | BuildType[] | boolean;

type BuildType = "main" | "browser" | "min";

default false;

Whether or not to add a __esModule: true property to your non ES Module build. If esModule = true it will affect all supported builds.

This option can be overridden using per-build options. See main, browser and bin options.

interop

interop: BuildType | BuildType[] | boolean;

type BuildType = "main" | "browser" | "min";

default false;

Whether or not to add an interop block. If interop = true it will affect all supported builds.

This option can be overridden using per-build options. See main, browser and bin options.

format

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

default "umd";

Defines the format to be used for the Browser build.

This option can be overridden using the browser option.

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.

This option can be overridden using the browser option.

id

id: string;

Optional amd id for AMD or UMD build.

This option can be overridden using the browser option.

If not present, AMD module will be defined with no id.

extend

extend: boolean;

default false;

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

This option can be overridden using the browser option.

globals

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

default {};

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

This option can be overridden using the browser option.

equals

equals: boolean;

default false;

Transforms type export for CommonJS module using export = ... instead of export default ....

This option can be overridden using the types option.

⚠️ 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.

min

min: BuildType | BuildType[] | boolean;

type BuildType = "main" | "module" | "browser" | "min";

default false;

Defines which files should be used to build an aditional 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 can be overridden using per-build options. See main, module, browser and bin options.

cache

cache: string;

default "node_modules/.cache/bundlib"

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

main

main: CommonJSOptions | false;

interface CommonJSOptions {
  sourcemap?: boolean | "inline";
  esModule?: boolean | null;
  interop?: boolean | null;
  min?: boolean | null;
}

Specific options to be used in the CommonJS build. They will override any corresponding option set in the top-level options. See sourcemap, esModule, interop and min options.

If it's set to false, it will prevent CommonJS build altogether, even if there is a "main" field in package.json.

module

module: ESModuleOptions | false;

interface ESModuleOptions {
  sourcemap?: boolean | "inline";
  min?: boolean;
}

Specific options to be used in the ES Module build. They will override any corresponding option set in the top-level options. See sourcemap and min options.

If it's set to false, it will prevent ES Module build altogether, even if there is a "module" or "jsnext:main" field in package.json.

browser

browser: BrowserOptions | false;

interface BrowserOptions {
  sourcemap?: boolean | "inline";
  esModule?: boolean;
  interop?: boolean;
  min?: boolean;
  format?: "iife" | "amd" | "umd" ;
  name?: string;
  id?: string;
  extend?: boolean;
  globals?: { [name: string]: string } | string[];
}

Specific options to be used in the Browser build. They will override any corresponding option set in the top-level options. See sourcemap, esModule, interop, min, format, name, id, extend and globals options.

If it's set to* false, it will prevent Browser build altogether, even if there is a "browser" field in package.json.

bin

bin: CommonJSOptions | false;

interface CommonJSOptions {
  sourcemap?: boolean | "inline";
  esModule?: boolean;
  interop?: boolean;
  min?: boolean;
}

Specific options to be used in Binary build. They will override any corresponding option set in the top-level options. See sourcemap, esModule, interop and min options.

If it's set to false, it will prevent Binary build altogether, even if there is a "bin" field in package.json.

⚠️ This option was used to set entry point for Binary build. For compatibility reasons it still works if you set this option as string. This behavior will be removed in the future and therefore should not be used. Use input option instead.

types

types: TypesOptions | false;

interface TypesOptions {
  equals: boolean;
}

Specific options to be used for types generation. They will override any corresponding option set in the top-level options. See equals option.

If it's set to false, it will prevent type declarations generation altogether, even if there is a "types" or "typings" field in package.json.

CLI

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.

API

example

// rollup.config.js

import { configsFromPkg } from "bundlib";

const dev = !process.env.production;

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

analizePkg

function analizePkg(
  cwd: string,
  pkg: PkgJson = read(cwd + "/package.json"),
): Promise<PkgAnalized>;

Analizes package.json and returns a Promise that resolves to useful normalized information, see PkgAnalized. 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

PkgAnalized

interface PkgAnalized {
  cwd: string;
  pkg: PkgJson;
  input: {
    api: string;
    bin: string;
  };
  output: {
    main: CommonJSBuildOptions | null;
    module: ESModuleBuildOptions | null;
    browser: BrowserBuildOptions | null;
    bin: CommonJSBuildOptions | null;
    types: TypesBuildOptions | null;
  };
  dependencies: {
    runtime: string[] | null;
    peer: string[] | null;
    optional: string[] | null;
  };
  cache: string;
}

see also: CommonJSBuildOptions, ESModuleBuildOptions, BrowserBuildOptions & TypesBuildOptions

CommonJSBuildOptions

interface CommonJSBuildOptions {
  path: string;
  sourcemap: boolean | "inline";
  esModule: boolean;
  interop: boolean;
  min: boolean;
}

ESModuleBuildOptions

interface ESModuleBuildOptions {
  path: string;
  sourcemap: boolean | "inline";
  min: boolean;
}

BrowserBuildOptions

interface BrowserBuildOptions {
  path: string;
  sourcemap: boolean | "inline";
  esModule: boolean;
  interop: boolean;
  min: boolean;
  format: "iife" | "amd" | "umd";
  name: string | null;
  id: string | null;
  globals: Record<string, string> | null;
  extend: boolean;
}

TypesBuildOptions

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

Known Issues

• Issue #7

Features

• Creates a CommonJS Module build based on the "main" field in your package.json
• Creates an ES Module build based on the "module" or "jsnext:main" field in your package.json
• Creates a Browser build based on the "browser" field in your package.json
• Creates an CLI Binary build based on the "bin" field in your package.json
• Exports type declarations based on the "types" or "typings" field in your package.json
• Skip any build based on options
• Sets "dependencies", "peerDependencies" and "optionalDependencies" as external for CommonJS Module, ES Module and Binary builds
• Uses the user copy of typescript if installed
• Uses chokidar if installed
• Importing an internal file from a package Ex: lodash/core will be treated as external if lodash is included in your "dependencies", peerDependencies or optionalDependencies
• Transforms async/await using Babel and babel-plugin-transform-async-to-promises for ES5 support
• Dynamic Import support through @babel/plugin-syntax-dynamic-import
• Transforms Object.assign using @babel/plugin-transform-object-assign
• React JSX support through @babel/preset-react
• Uses @babel/preset-env
• Minifies build using Terser

License

MIT © Manuel Fernández