Miss any of our Open RFC calls?Watch the recordings here! »

bundlib

0.12.4 • Public • Published

Bundlib

CircleCI dependabot npm dependencies Status devDependencies Status install size Known Vulnerabilities codecov License

An automatic javascript library bundler using Rollup.js and optionally Typescript.

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

In this guide

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

inputstring | 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 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 default value.

sourcemap

sourcemapboolean | "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

esModuleBuildType | 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 builds.

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

interop

interopBuildType | BuildType[] | boolean;
 
type BuildType = "main" | "browser" | "min";
 
default false;

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

This option can be overridden using per-build options. See main, browser & 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

namestring;

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

idstring;

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

extendboolean;
 
default false;

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

This option can be overridden using the browser option.

globals

globals{ [namestring]string } | string[];
 
default {};

Object or array to map names to globals in browser builds.

This option can be overridden using the browser option.

equals

equalsboolean;
 
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

minBuildType | 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 & bin options.

cache

cachestring;
 
default "node_modules/.cache/bundlib"

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

main

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

Specific options to be used in CommonJS build. They will override any corresponding option set in the top-level options. See sourcemap, esModule, interop & 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

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

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

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

browser

browserBrowserOptions | 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 Browser build. They will override any corresponding option set in the top-level options. See sourcemap, esModule, interop, min, format, name, id, extend & 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

binCommonJSOptions | 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 & 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

typesTypesOptions | 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 -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.

⚠️ The return of this function changed drastically from v0.9.x to v0.10.x. This only affects you if you are using this method, if you are using configsFromPkg or the cli, you are safe to update.

configsFromPkg

function configsFromPkg(
  cwd: string,
  options: { devboolean, 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

Features

  • Creates a CommonJS Module based on the "main" field in package.json
  • Creates an ES Module based on the "module" or "jsnext:main" field in package.json
  • Creates an Browser build based on the "browser" field in package.json (only if "browser" field value is a string)
  • Creates an CLI Binary build based on the "bin" field in package.json (only if "bin" field value is a string)
  • 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,* ES Module and Bynary modules
  • 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
  • Tranforms 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

Install

npm i [email protected]

Version

0.12.4

License

MIT

Unpacked Size

251 kB

Total Files

36

Last publish

Collaborators

  • avatar