bundlib/README.md

# Bundlib

[![CircleCI](https://circleci.com/gh/manferlo81/bundlib.svg?style=svg)](https://circleci.com/gh/manferlo81/bundlib) [![dependabot](https://api.dependabot.com/badges/status?host=github&repo=manferlo81/bundlib)](https://dependabot.com) [![npm](https://badgen.net/npm/v/bundlib)](https://www.npmjs.com/package/bundlib) [![codecov](https://codecov.io/gh/manferlo81/bundlib/branch/master/graph/badge.svg)](https://codecov.io/gh/manferlo81/bundlib) [![dependencies](https://badgen.net/david/dep/manferlo81/bundlib)](https://david-dm.org/manferlo81/bundlib) [![dev dependencies](https://badgen.net/david/dev/manferlo81/bundlib)](https://david-dm.org/manferlo81/bundlib?type=dev) [![packagephobia](https://badgen.net/packagephobia/install/bundlib)](https://packagephobia.now.sh/result?p=bundlib) [![types](https://img.shields.io/npm/types/bundlib.svg)](https://github.com/microsoft/typescript) [![Known Vulnerabilities](https://snyk.io/test/npm/bundlib/badge.svg)](https://snyk.io/test/npm/bundlib) [![license](https://badgen.net/github/license/manferlo81/bundlib)](LICENSE)

An automatic configuration manager for [Rollup.js](https://github.com/rollup/rollup).

> :warning: Bundlib is under active development, please [file a new issue](https://github.com/manferlo81/bundlib/issues) if you find any issue or bug, suggestions are welcome as well.

## BREAKING CHANGES in version 0.15.x

* [Rollup](https://github.com/rollup/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](#install)
* [First steps](#first-steps)
* [Build](#build)
* [Configuration](#configuration)
* [Supported Plugins](#supported-plugins)
* [CLI](#cli)
* [API](#api)
* [Types](#types-1)
* [Known Issues](#known-issues)
* [Features](#features)

## Install

```bash
npm i -D bundlib
```

> :warning: 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`](#input) option.

Add the corresponding scripts to your `package.json` and run them. [see below for CLI options](#cli).

## 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](#configuration) 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](#configuration) 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`](#format) or [`browser`](#browser) option, see the [configuration section](#configuration) 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](#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"`](#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"`](#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"`](#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"`](#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"`](#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"`](#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](#advanced-configuration) for more information.

### Advanced Configuration

Advanced configuration is done through the `"bundlib"` field in your `package.json`. See the [list of options](#options) below.

***example***

```javascript
// 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

```typescript
input: string | 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

```typescript
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`](#main), [`module`](#module), [`browser`](#browser) and [`bin`](#bin) options.

#### esModule

```typescript
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`](#main), [`browser`](#browser) and [`bin`](#bin) options.

#### interop

```typescript
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`](#main), [`browser`](#browser) and [`bin`](#bin) options.

#### format

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

default "umd";
```

Defines the format to be used for the `Browser` build.

This option can be overridden using the [`browser`](#browser) option.

#### name

```typescript
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`](#browser) option.

#### id

```typescript
id: string;
```

Optional amd id for `AMD` or `UMD` build.

This option can be overridden using the [`browser`](#browser) option.

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

#### extend

```typescript
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`](#browser) option.

#### globals

```typescript
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`](#browser) option.

#### equals

```typescript
equals: boolean;

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](#supported-plugins) instead.

Transforms type export for `CommonJS Module` using `export = ...` instead of `export default ...`.

This option can be overridden using the [`types`](#types) option.

> :warning: *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

```typescript
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*](#-dev-d) , 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](#-dev-d).

This option can be overridden using `per-build` options. See [`main`](#main), [`module`](#module), [`browser`](#browser) and [`bin`](#bin) options.

#### cache

```typescript
cache: string;

default "node_modules/.cache/bundlib"
```

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

#### project

```typescript
cache: string;

default "tsconfig.json"
```

Defines the location of typescript `tsconfig.json` file.

#### main

```typescript
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`](#sourcemap), [`esModule`](#esmodule), [`interop`](#interop) and [`min`](#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

```typescript
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`](#sourcemap) and [`min`](#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

```typescript
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`](#sourcemap), [`esModule`](#esmodule), [`interop`](#interop), [`min`](#min), [`format`](#format), [`name`](#name), [`id`](#id), [`extend`](#extend) and [`globals`](#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

```typescript
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`](#sourcemap), [`esModule`](#esmodule), [`interop`](#interop) and [`min`](#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

```typescript
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`](#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`.

* [`rollup-plugin-eslint`](https://github.com/TrySound/rollup-plugin-eslint)
* [`rollup-plugin-typescript2`](https://github.com/ezolenko/rollup-plugin-typescript2)
* [`@rollup/plugin-typescript`](https://github.com/rollup/plugins/tree/master/packages/typescript)
* [`rollup-plugin-babel`](https://github.com/rollup/rollup-plugin-babel)
* [`@rollup/plugin-buble`](https://github.com/rollup/plugins/tree/master/packages/buble)
* [`@rollup/plugin-node-resolve`](https://github.com/rollup/plugins/tree/master/packages/node-resolve)
* [`@rollup/plugin-commonjs`](https://github.com/rollup/plugins/tree/master/packages/commonjs)
* [`@rollup/plugin-json`](https://github.com/rollup/plugins/tree/master/packages/json)
* [`rollup-plugin-terser`](https://github.com/TrySound/rollup-plugin-terser)
* [`rollup-plugin-strip-shebang`](https://github.com/manferlo81/rollup-plugin-strip-shebang)
* [`rollup-plugin-add-shebang`](https://github.com/ls-age/rollup-plugin-add-shebang)
* [`rollup-plugin-export-equals`](https://github.com/manferlo81/rollup-plugin-export-equals)

The following plugins will be supported in the future.

* [`rollup-plugin-prettier`](https://github.com/mjeanroy/rollup-plugin-prettier)
* [`rollup-plugin-preserve-shebang`](https://github.com/developit/rollup-plugin-preserve-shebang)

Any plugin suggestion will be well received, please [file a new issue](https://github.com/manferlo81/bundlib/issues).

## CLI

```bash
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`](#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***

```javascript
// rollup.config.js

import { configsFromPkg } from "bundlib";

const dev = !process.env.production;

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

### analizePkg

```typescript
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`](#pkganalized). If `pkg` not provided it will be read from the current working directory `cwd`.

### configsFromPkg

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

```typescript
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`](#commonjsbuildoptions), [`ESModuleBuildOptions`](#esmodulebuildoptions), [`BrowserBuildOptions`](#browserbuildoptions) & [`TypesBuildOptions`](#typesbuildoptions)

### CommonJSBuildOptions

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

### ESModuleBuildOptions

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

### BrowserBuildOptions

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

```typescript
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](#supported-plugins) 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](LICENSE) &copy; 2019 [Manuel Fernández](https://github.com/manferlo81)