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
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 adefault
export and nonamed
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 forBinary
build. For compatibility reasons it still works if you set this option asstring
. This behavior will be removed in the future and therefore should not be used. Useinput
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
Features
- Creates a
CommonJS Module
build based on the"main"
field in yourpackage.json
- Creates an
ES Module
build based on the"module"
or"jsnext:main"
field in yourpackage.json
- Creates a
Browser
build based on the"browser"
field in yourpackage.json
- Creates an CLI
Binary
build based on the"bin"
field in yourpackage.json
- Exports type declarations based on the
"types"
or"typings"
field in yourpackage.json
- Skip any build based on options
- Sets
"dependencies"
,"peerDependencies"
and"optionalDependencies"
as external forCommonJS Module
,ES Module
andBinary
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 iflodash
is included in your"dependencies"
,peerDependencies
oroptionalDependencies
- Transforms
async/await
usingBabel
andbabel-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