Get unlimited public & private packages + package-based permissions with npm Pro.Get started »

bundlib

0.15.5 • Public • Published

Bundlib

CircleCI dependabot npm codecov dependencies dev dependencies packagephobia types Known Vulnerabilities license

An automatic configuration manager for Rollup.js.

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

BREAKING CHANGES in version 0.15.x

  • Rollup has to be installed separately
  • analizePkg paths are not longer resolved
  • find input files and default to index.js instead of index.ts

In this guide

Install

npm i -D bundlib

⚠️ Rollup is a peer dependency and it has to be installed as well.

First steps

Bundlib will use src/index.ts or src/index.tsx as entry file for your library if you are using typescript (see Plugins for more information) or src/index.js otherwise, 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, 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

Automatic Configuration

Bundlib will try to configure Rollup according to you package.json data, other advanced options can be set using "bundlib" field in your package.json, 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 "main" advanced 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 "module" advanced 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 "browser" advanced 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 "bin" advanced 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 "types" advanced 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 added as external dependencies for your CommonJS Module, ES Module, and Binary builds, for Browser build dependencies will be bundled into the output unless otherwise specified using the "globals" advanced 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 will be used for advanced configuration, see Advanced Configuration for more information.

Advanced Configuration

Advanced 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

inputstring | InputOptions;
 
interface InputOptions {
  api?: string;
  bin?: string;
}
 
default {
  api"src/index.js";
  bin"src-bin/index.js";
};

The path to the file (or files) to be used as entry point(s) for API and Binary modules. 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

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

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

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 or 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 build.

This option can be overridden using the browser option.

equals

equalsboolean;
 
default false;

As of version 0.15.2 this option has no effect, It won't throw to keep compatibility with previous version but it will be ignored. Install rollup-plugin-export-equals Plugin instead.

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 and bin options.

cache

cachestring;
 
default "node_modules/.cache/bundlib"

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

project

cachestring;
 
default "tsconfig.json"

Defines the location of typescript tsconfig.json file.

main

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

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

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

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

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.

Supported Plugins

Any of the following plugins will be automatically configured if they are installed as "dependencies" or "devDependencies" in package.json.

The following plugins will be supported in the future.

Any plugin suggestion will be well received, please file a new issue.

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: { 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 | null;
    bin: string | null;
  };
  output: {
    main: CommonJSBuildOptions | null;
    module: ESModuleBuildOptions | null;
    browser: BrowserBuildOptions | null;
    bin: CommonJSBuildOptions | null;
    types: TypesBuildOptions | null;
  };
  dependencies: {
    runtime: { [name: string]: string } | null;
    dev: { [name: string]: string } | null;
    peer: { [name: string]: string } | null;
  };
  cache: string | null;
  project: string | null;
}

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

Features

  • Builds a CommonJS Module based on the "main" field in your package.json
  • Builds an ES Module based on the "module" (or "jsnext:main") field in your package.json
  • Builds a Browser module based on the "browser" field in your package.json
  • Builds a Binary module 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" and "peerDependencies" as external for CommonJS Module, ES Module and Binary builds
  • Uses and configures any supported rollup plugin 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" or peerDependencies

License

MIT © 2019 Manuel Fernández

Install

npm i bundlib

DownloadsWeekly Downloads

441

Version

0.15.5

License

MIT

Unpacked Size

282 kB

Total Files

46

Last publish

Collaborators

  • avatar