1 | # Bundlib
|
2 |
|
3 | [![CircleCI](https://circleci.com/gh/manferlo81/bundlib.svg?style=svg)](https://circleci.com/gh/manferlo81/bundlib) [![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)
|
4 |
|
5 | An automatic library bundler powered by [Rollup.js](https://github.com/rollup/rollup).
|
6 |
|
7 | > :warning: **Bundlib** is under development, please [file a new issue](https://github.com/manferlo81/bundlib/issues) if you find any issue or bug, suggestions are welcome as well.
|
8 |
|
9 | ## In this guide
|
10 |
|
11 | * [Install](#install)
|
12 | * [Build](#build)
|
13 | * [Configuration](#configuration)
|
14 | * [Advanced Configuration](#advanced-configuration)
|
15 | * [Options](#options)
|
16 | * [input](#input)
|
17 | * [sourcemap](#sourcemap)
|
18 | * [esModule](#esmodule)
|
19 | * [interop](#interop)
|
20 | * [format](#format)
|
21 | * [name](#name)
|
22 | * [id](#id)
|
23 | * [extend](#extend)
|
24 | * [globals](#globals)
|
25 | * [min](#min)
|
26 | * [equals](#equals)
|
27 | * [cache](#cache)
|
28 | * [project](#project)
|
29 | * [skip](#skip)
|
30 | * [Selective Options](#selective-options)
|
31 | * [Object based selective format](#object-based-selective-format)
|
32 | * [String based selective format](#string-based-selective-format)
|
33 | * [Using the CLI tool](#using-the-cli-tool)
|
34 | * [Using **Bundlib** programmatically](#using-bundlib-programmatically)
|
35 | * [Types](#types)
|
36 | * [Features](#features)
|
37 |
|
38 | ## Install
|
39 |
|
40 | ```bash
|
41 | npm i -D bundlib
|
42 | ```
|
43 |
|
44 | ## Build
|
45 |
|
46 | **Bundlib** will try to find your entry point file in the **`src`** folder. You can manually set your entry points using the [`input`](#input) option.
|
47 |
|
48 | ### CommonJS module
|
49 |
|
50 | To build a `CommonJS Module` simply add a `"main"` field to your `package.json` pointing to the output file, [see the configuration section](#configuration) for extra options.
|
51 |
|
52 | ### ES module
|
53 |
|
54 | To build a `ES Module` add a `"module"` field to your `package.json` pointing to the output file, [see the configuration section](#configuration) for extra options.
|
55 |
|
56 | ### IIFE, AMD and UMD build
|
57 |
|
58 | 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) option, see the [configuration section](#configuration) for more info and extra options.
|
59 |
|
60 | ## Configuration
|
61 |
|
62 | ### Automatic Configuration
|
63 |
|
64 | **Bundlib** will configure [**Rollup**](https://github.com/rollup/rollup) according to you `package.json` data, see [Advanced Configuration](#advanced-configuration) for more information.
|
65 |
|
66 | #### "main"
|
67 |
|
68 | 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 [`skip`](#skip) option.
|
69 |
|
70 | #### "module" or "jsnext:main"
|
71 |
|
72 | 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 [`skip`](#skip) option. `"jsnext:main"` field will also be honored if `"module"` field is not present, but it is recommended to use the `"module"` field.
|
73 |
|
74 | #### "browser"
|
75 |
|
76 | 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 [`skip`](#skip) option. **Bundlib** only supports `string` type `"browser"` field, it will **throw** otherwise.
|
77 |
|
78 | #### "bin"
|
79 |
|
80 | 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 [`skip`](#skip) option. **Bundlib** only supports `string` type `"bin"` field, it will **throw** otherwise.
|
81 |
|
82 | #### "types" or "typings"
|
83 |
|
84 | The `"types"` field will be used as your **Types** output if you are using `typescript`. You can skip types generation using the [`skip`](#skip) option. `"typings"` field will also be honored if `"types"` field is not present.
|
85 |
|
86 | #### "dependencies"
|
87 |
|
88 | The `"dependencies"` field will be used to detect installed packages, it will also be used to set external dependencies for your **CommonJS module**, **ES module**, and **Binary** builds, for **Browser** build dependencies will be bundled into the output file unless otherwise specified using the [`"globals"`](#globals) option.
|
89 |
|
90 | #### "devDependencies"
|
91 |
|
92 | The `"devDependencies"` field will be used to detect installed packages.
|
93 |
|
94 | #### "peerDependencies"
|
95 |
|
96 | The `"peerDependencies"` field will be used as external dependencies for your **CommonJS module,**, **ES module**, and **Binary** builds.
|
97 |
|
98 | #### "bundlib"
|
99 |
|
100 | The `"bundlib"` field can be used for advanced configuration, see [Advanced Configuration](#advanced-configuration) for more information.
|
101 |
|
102 | ### Advanced Configuration
|
103 |
|
104 | Advanced configuration can be done using the `"bundlib"` field in your `package.json` or by using one of the supported [configuration files](#configuration-files).
|
105 |
|
106 | #### Configuration in `package.json`
|
107 |
|
108 | Set `"bundlib"` field in your `package.json` to an `object` with your configuration. See [options](#options) for more information.
|
109 |
|
110 | ***example***
|
111 |
|
112 | ```json
|
113 | // package.json
|
114 | {
|
115 | "name": "my-lib",
|
116 | "version": "1.0.0",
|
117 | "browser" : "dist/my-lib.amd.js",
|
118 | "bundlib": {
|
119 | "format": "amd"
|
120 | }
|
121 | ...
|
122 | }
|
123 | ```
|
124 |
|
125 | You can also set `"bundlib"` field in `package.json` to a `string` as a path, relative to the project root, pointing to a `.json`, `.yaml`, `.yml` or `.js` configuration file.
|
126 |
|
127 | ***example***
|
128 |
|
129 | ```json
|
130 | // package.json
|
131 | {
|
132 | "name": "my-lib",
|
133 | "version": "1.0.0",
|
134 | "browser" : "dist/my-lib.amd.js",
|
135 | "bundlib": "custom-options.yaml"
|
136 | // ...
|
137 | }
|
138 | ```
|
139 |
|
140 | then...
|
141 |
|
142 | ```yaml
|
143 | # custom-options.yaml
|
144 | format: amd
|
145 | ```
|
146 |
|
147 | #### Configuration files
|
148 |
|
149 | If `"bundlib"` field not present in your `package.json`, **Bundlib** will try to find your configuration file using the following order...
|
150 |
|
151 | * .bundlibrc (json or yaml format)
|
152 | * .bundlibrc.json
|
153 | * .bundlibrc.yaml
|
154 | * .bundlibrc.yml
|
155 | * .bundlibrc.js
|
156 | * bundlib.config.js
|
157 |
|
158 | See the [list of options](#options) below.
|
159 |
|
160 | ### Options
|
161 |
|
162 | The option object 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.
|
163 |
|
164 | #### input
|
165 |
|
166 | ```typescript
|
167 | input: string | SelectiveOption;
|
168 | ```
|
169 |
|
170 | The path to the files to be used as entry points for each of your builds.
|
171 |
|
172 | This option supports `object` based [`selective format`](#selective-options). See [Selective Options](#selective-options) for more information.
|
173 |
|
174 | #### sourcemap
|
175 |
|
176 | ```typescript
|
177 | sourcemap: boolean | 'inline' | 'hidden' | SelectiveOption;
|
178 |
|
179 | default true;
|
180 | ```
|
181 |
|
182 | Whether or not to generate source maps, See [Rollup documentation](https://rollupjs.org/guide/en/#outputsourcemap) for more information. If not specified or set to `null` it will default to `true`.
|
183 |
|
184 | This option supports `object` based and `string` based [`selective format`](#selective-options). See [Selective Options](#selective-options) for more information.
|
185 |
|
186 | #### esModule
|
187 |
|
188 | ```typescript
|
189 | esModule: boolean | SelectiveOption;
|
190 |
|
191 | default false;
|
192 | ```
|
193 |
|
194 | Whether or not to add a `__esModule: true` property to your module. If `esModule = true` it will affect all builds.
|
195 |
|
196 | This option supports `object` based and `string` based [`selective format`](#selective-options). See [Selective Options](#selective-options) for more information.
|
197 |
|
198 | #### interop
|
199 |
|
200 | ```typescript
|
201 | interop: boolean | SelectiveOption;
|
202 |
|
203 | default false;
|
204 | ```
|
205 |
|
206 | Whether or not to add an interop block. If `interop = true` it will affect all builds.
|
207 |
|
208 | This option supports `object` based and `string` based [`selective format`](#selective-options). See [Selective Options](#selective-options) for more information.
|
209 |
|
210 | #### format
|
211 |
|
212 | ```typescript
|
213 | format: "iife" | "amd" | "umd";
|
214 |
|
215 | default "umd";
|
216 | ```
|
217 |
|
218 | Defines the format to be used for the `Browser` build.
|
219 |
|
220 | #### name
|
221 |
|
222 | ```typescript
|
223 | name: string;
|
224 | ```
|
225 |
|
226 | 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.
|
227 |
|
228 | #### id
|
229 |
|
230 | ```typescript
|
231 | id: string;
|
232 | ```
|
233 |
|
234 | Optional amd id for `AMD` or `UMD` build.
|
235 |
|
236 | If not present, `AMD` `define` method will use no id.
|
237 |
|
238 | #### extend
|
239 |
|
240 | ```typescript
|
241 | extend: boolean;
|
242 |
|
243 | default false;
|
244 | ```
|
245 |
|
246 | Whether or not to extend the globally exposed [name](#name) on a `IIFE` or `UMD` build.
|
247 |
|
248 | #### globals
|
249 |
|
250 | ```typescript
|
251 | globals: { [name: string]: string } | string[];
|
252 |
|
253 | default {};
|
254 | ```
|
255 |
|
256 | `Object` or `array` to map names to globals in `Browser` build.
|
257 |
|
258 | #### min
|
259 |
|
260 | ```typescript
|
261 | min: boolean | SelectiveOption;
|
262 |
|
263 | default false;
|
264 | ```
|
265 |
|
266 | Defines which files should be used to build an additional 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).
|
267 |
|
268 | This option supports `object` based and `string` based [`selective format`](#selective-options). See [Selective Options](#selective-options) for more information.
|
269 |
|
270 | #### equals
|
271 |
|
272 | ```typescript
|
273 | equals: boolean;
|
274 |
|
275 | default false;
|
276 | ```
|
277 |
|
278 | Transforms type export for CommonJS module using `export = ...` instead of `export default ...`.
|
279 |
|
280 | > :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.*
|
281 |
|
282 | #### cache
|
283 |
|
284 | ```typescript
|
285 | cache: string;
|
286 |
|
287 | default "node_modules/.cache/bundlib";
|
288 | ```
|
289 |
|
290 | Defines the directory to be used for cache, relative to the project root.
|
291 |
|
292 | #### project
|
293 |
|
294 | ```typescript
|
295 | project: string | SelectiveOption;
|
296 |
|
297 | default "tsconfig.json"
|
298 | ```
|
299 |
|
300 | Defines the location of typescript `tsconfig.json` file, relative to the project root.
|
301 |
|
302 | This option supports `object` based [`selective format`](#selective-options). See [Selective Options](#selective-options) for more information.
|
303 |
|
304 | #### skip
|
305 |
|
306 | ```typescript
|
307 | min: boolean | SelectiveOption;
|
308 |
|
309 | default false;
|
310 | ```
|
311 |
|
312 | Defined which build **Bundlib** should skip.
|
313 |
|
314 | This option supports `object` based and `string` based [`selective format`](#selective-options). See [Selective Options](#selective-options) for more information.
|
315 |
|
316 | ### Selective Options
|
317 |
|
318 | Some options support a selective format to allow for a more flexible configuration. See [`SelectiveOption`](#SelectiveOption) type for more information.
|
319 |
|
320 | Note that some options support different selective formats. `Boolean` type options support `string` based format and `object` based format while others support only `object` based format.
|
321 |
|
322 | See [input](#input), [sourcemap](#sourcemap), [esModule](#esmodule), [interop](#interop), [min](#min) and [project](#project) options.
|
323 |
|
324 | #### Object based selective format
|
325 |
|
326 | `object` based format works by preserving the default value and overriding it with the provided configuration.
|
327 |
|
328 | ***example***
|
329 |
|
330 | ```javascript
|
331 | // assuming default = false...
|
332 |
|
333 | {
|
334 | main: true
|
335 | }
|
336 |
|
337 | // ... will resolve to
|
338 |
|
339 | /*
|
340 | {
|
341 | main: true,
|
342 | ...others: false
|
343 | }
|
344 | */
|
345 | ```
|
346 |
|
347 | ##### The special `default` property
|
348 |
|
349 | You can override the default value as well using the `"default"` object key.
|
350 |
|
351 | ***example***
|
352 |
|
353 | ```javascript
|
354 | // assuming default = false
|
355 |
|
356 | {
|
357 | default: true,
|
358 | bin: false
|
359 | }
|
360 |
|
361 | // ... will resolve to
|
362 |
|
363 | /*
|
364 | {
|
365 | bin: false,
|
366 | ...others: true
|
367 | }
|
368 | */
|
369 | ```
|
370 |
|
371 | ##### The special `api` property
|
372 |
|
373 | The `"api"` object key represents `main`, `module` and `browser`.
|
374 |
|
375 | ***example***
|
376 |
|
377 | ```javascript
|
378 | // assuming default = false...
|
379 |
|
380 | {
|
381 | api: true
|
382 | }
|
383 |
|
384 | // ... will resolve to
|
385 |
|
386 | /*
|
387 | {
|
388 | main: true,
|
389 | module: true,
|
390 | browser: true,
|
391 | ...others: false
|
392 | }
|
393 | */
|
394 | ```
|
395 |
|
396 | #### String based selective format
|
397 |
|
398 | `string` based format works in a different way, it does not preserve the default value, included build types will be set to `true` and the others will be set to `false`. It can be a `string` or an `string array`.
|
399 |
|
400 | ##### As string
|
401 |
|
402 | ***example***
|
403 |
|
404 | ```javascript
|
405 | 'module'
|
406 |
|
407 | // ... will resolve to
|
408 |
|
409 | /*
|
410 | {
|
411 | module: true,
|
412 | ...others: false
|
413 | }
|
414 | */
|
415 | ```
|
416 |
|
417 | ##### As array of strings
|
418 |
|
419 | ***example***
|
420 |
|
421 | ```javascript
|
422 | ['main', 'module']
|
423 |
|
424 | // ... will resolve to
|
425 |
|
426 | /*
|
427 | {
|
428 | main: true,
|
429 | module: true,
|
430 | ...others: false
|
431 | }
|
432 | */
|
433 | ```
|
434 |
|
435 | ##### The special `api` build type
|
436 |
|
437 | ***example***
|
438 |
|
439 | ```javascript
|
440 | 'api'
|
441 |
|
442 | // ... will resolve to
|
443 |
|
444 | /*
|
445 | {
|
446 | main: true,
|
447 | module: true,
|
448 | browser: true,
|
449 | ...others: false
|
450 | }
|
451 | */
|
452 | ```
|
453 |
|
454 | ## Using the CLI tool
|
455 |
|
456 | ```bash
|
457 | bundlib [options]
|
458 | ```
|
459 |
|
460 | ### CLI Options
|
461 |
|
462 | Combine options according to your needs. Run `bundlib --help` or `bundlib -h` for a detailed help.
|
463 |
|
464 | #### `--dev`, `-d`
|
465 |
|
466 | Create development, not minified builds. Builds affected by the [`min`](#min) option will ignore this option.
|
467 |
|
468 | #### `--watch`, `-w`
|
469 |
|
470 | Run **Bundlib** in watch mode.
|
471 |
|
472 | #### `--silent`, `-s`
|
473 |
|
474 | Prevent messages from showing in the console.
|
475 |
|
476 | #### `--version`, `-v`
|
477 |
|
478 | Show **Bundlib** version.
|
479 |
|
480 | #### `--help`, `-h`
|
481 |
|
482 | Show detailed help about the CLI tool.
|
483 |
|
484 | ## Using Bundlib programmatically
|
485 |
|
486 | ***example***
|
487 |
|
488 | ```javascript
|
489 | // rollup.config.js
|
490 |
|
491 | import { configsFromPkg } from "bundlib";
|
492 |
|
493 | const dev = !process.env.production;
|
494 |
|
495 | export default configsFromPkg(
|
496 | process.cwd(),
|
497 | { dev },
|
498 | );
|
499 | ```
|
500 |
|
501 | ### analyzePkg
|
502 |
|
503 | ```typescript
|
504 | function analyzePkg(
|
505 | cwd: string,
|
506 | pkg: PkgJson = read(cwd + "/package.json"),
|
507 | ): Promise<PkgAnalyzed>;
|
508 | ```
|
509 |
|
510 | Analyzes `package.json` and returns a `Promise` that resolves to useful normalized information, [*see* `PkgAnalyzed`](#pkganalyzed). If `pkg` not provided it will be read from the current working directory `cwd`.
|
511 |
|
512 | ### configsFromPkg
|
513 |
|
514 | ```typescript
|
515 | function configsFromPkg(
|
516 | cwd: string,
|
517 | options: { dev? boolean, watch?: boolean } | null | false,
|
518 | pkg: PkgJson = read(cwd + "/package.json"),
|
519 | ): Promise<RollupOptions[]>;
|
520 | ```
|
521 |
|
522 | 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`.
|
523 |
|
524 | ## Types
|
525 |
|
526 | ### PkgAnalyzed
|
527 |
|
528 | ```typescript
|
529 | interface PkgAnalyzed {
|
530 | cwd: string;
|
531 | pkg: PkgJson;
|
532 | main: ModuleBuildOptions | null;
|
533 | module: ModuleBuildOptions | null;
|
534 | browser: BrowserBuildOptions | null;
|
535 | bin: ModuleBuildOptions | null;
|
536 | types: TypesBuildOptions | null;
|
537 | dependencies: {
|
538 | runtime: { [name: string]: string } | null;
|
539 | dev: { [name: string]: string } | null;
|
540 | peer: { [name: string]: string } | null;
|
541 | };
|
542 | cache: string | null;
|
543 | }
|
544 | ```
|
545 |
|
546 | *see also:* [`ModuleBuildOptions`](#modulebuildoptions), [`BrowserBuildOptions`](#browserbuildoptions) and [`TypesBuildOptions`](#typesbuildoptions).
|
547 |
|
548 | ### ModuleBuildOptions
|
549 |
|
550 | ```typescript
|
551 | interface ModuleBuildOptions {
|
552 | input: string | null;
|
553 | output: string;
|
554 | sourcemap: boolean | 'inline' | 'hidden';
|
555 | esModule: boolean;
|
556 | interop: boolean;
|
557 | min: boolean;
|
558 | project: string | null;
|
559 | }
|
560 | ```
|
561 |
|
562 | ### BrowserBuildOptions
|
563 |
|
564 | ```typescript
|
565 | interface BrowserBuildOptions extends ModuleBuildOptions {
|
566 | format: "iife" | "amd" | "umd";
|
567 | name: string | null;
|
568 | id: string | null;
|
569 | globals: Record<string, string> | null;
|
570 | extend: boolean;
|
571 | }
|
572 | ```
|
573 |
|
574 | ### TypesBuildOptions
|
575 |
|
576 | ```typescript
|
577 | interface TypesBuildOptions {
|
578 | output: string;
|
579 | equals: boolean;
|
580 | }
|
581 | ```
|
582 |
|
583 | ### SelectiveOption
|
584 |
|
585 | ```typescript
|
586 | interface ObjectBasedSelectiveOption<T> {
|
587 | default: T;
|
588 | [K: BuildType]: T;
|
589 | }
|
590 |
|
591 | type StringBasedSelectiveOption = BuildType | BuildType[];
|
592 |
|
593 | type BuildType = 'main' | 'module' | 'browser' | 'bin' | 'api' | ...others;
|
594 | ```
|
595 |
|
596 | ## Features
|
597 |
|
598 | * Uses `"main"` field in your `package.json` to build a `CommonJS Module`.
|
599 | * Uses `"module"` field in your `package.json` (or `"jsnext:main"` field) to build an `ES Module`.
|
600 | * Uses `"browser"` field in your `package.json` to build a `Browser` module. It only supports `"browser"` field as `string`, `object` format not supported.
|
601 | * Uses `"bin"` field in your `package.json` to build a `Binary` module. It only supports `"bin"` field as `string`, `object` format not supported.
|
602 | * Uses `"types"` field in your `package.json` (or `"typings"` field) as path for types declarations.
|
603 | * Uses `"dependencies"` and `"peerDependencies"` to set external modules for `CommonJS Module`, `ES Module` and `Binary` builds. Dependencies will be bundled by default in `Browser` builds, unless otherwise specified using the [`global`](#globals) option.
|
604 | * Skip any build based on [options](#skip).
|
605 | * Uses `rollup-plugin-typescript2` if `typescript` installed as runtime or dev dependency.
|
606 | * Uses `@rollup/plugin-babel` if `@babel/core` installed as runtime or dev dependency, otherwise it uses `@rollup/plugin-buble`.
|
607 | * Uses `rollup-plugin-strip-shebang` and `rollup-plugin-add-shebang` to ensure a shebang on binary build.
|
608 | * Uses `@rollup/plugin-json` to import JSON files.
|
609 | * Uses `rollup-plugin-eslint` if `eslint` installed as runtime or dev dependency.
|
610 | * Uses `rollup-plugin-terser` to minify production build.
|
611 | * Uses `chokidar` for file watch if installed.
|
612 |
|
613 | ## License
|
614 |
|
615 | [MIT](LICENSE) © 2019 [Manuel Fernández](https://github.com/manferlo81)
|