1 | # Bundlib
|
2 |
|
3 | [![CircleCI](https://circleci.com/gh/manferlo81/bundlib.svg?style=svg)](https://circleci.com/gh/manferlo81/bundlib) [![Greenkeeper badge](https://badges.greenkeeper.io/manferlo81/bundlib.svg)](https://greenkeeper.io/) [![npm](https://img.shields.io/npm/v/bundlib.svg)](https://www.npmjs.com/package/bundlib) [![dependencies Status](https://david-dm.org/manferlo81/bundlib/status.svg)](https://david-dm.org/manferlo81/bundlib) [![devDependencies Status](https://david-dm.org/manferlo81/bundlib/dev-status.svg)](https://david-dm.org/manferlo81/bundlib?type=dev) [![install size](https://packagephobia.now.sh/badge?p=bundlib)](https://packagephobia.now.sh/result?p=bundlib) [![Known Vulnerabilities](https://snyk.io/test/github/manferlo81/bundlib/badge.svg?targetFile=package.json)](https://snyk.io/test/github/manferlo81/bundlib?targetFile=package.json) [![codecov](https://codecov.io/gh/manferlo81/bundlib/branch/master/graph/badge.svg)](https://codecov.io/gh/manferlo81/bundlib) [![License](https://img.shields.io/github/license/manferlo81/bundlib.svg)](LICENSE)
|
4 |
|
5 | An automatic javascript library bundler using [Rollup.js](https://github.com/rollup/rollup) and optionally [Typescript](https://github.com/Microsoft/TypeScript).
|
6 |
|
7 | > :warning: Bundlib under active development, please [file a new issue](https://github.com/manferlo81/bundlib/issues) if you find any issue/bug, suggestions are welcome as well.
|
8 |
|
9 | ## In this guide
|
10 |
|
11 | * [Install](#install)
|
12 | * [First steps](#first-steps)
|
13 | * [Build](#build)
|
14 | * [Configuration](#configuration)
|
15 | * [CLI](#cli)
|
16 | * [API](#api)
|
17 | * [Types](#types-1)
|
18 | * [Known Issues](#known-issues)
|
19 | * [Features](#features)
|
20 |
|
21 | ## Install
|
22 |
|
23 | ```bash
|
24 | npm i -D bundlib
|
25 | ```
|
26 |
|
27 | ## First steps
|
28 |
|
29 | *Bundlib will use* `src/index.ts` *as entry file for your library by default, it can be configured using* [`input`](#input) *option. Add the corresponding scripts to your* `package.json` *and run them. [see below for CLI options](#cli).*
|
30 |
|
31 | ## Build
|
32 |
|
33 | ### CommonJS module
|
34 |
|
35 | *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](#configuration) for extra options.*
|
36 |
|
37 | ### ES module
|
38 |
|
39 | *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.*
|
40 |
|
41 | ### IIFE, AMD and UMD build
|
42 |
|
43 | *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.*
|
44 |
|
45 | ## Configuration
|
46 |
|
47 | *Configuration is done through the* `"bundlib"` *field in* `package.json`*. See the [list of options](#options) below.*
|
48 |
|
49 | ***example***
|
50 |
|
51 | ```javascript
|
52 | // package.json
|
53 | {
|
54 | "version": "1.0.0",
|
55 | "name": "my-lib",
|
56 | "browser" : "dist/my-lib.amd.js",
|
57 | // ...
|
58 | "bundlib": {
|
59 | "format": "amd"
|
60 | }
|
61 | // ...
|
62 | }
|
63 | ```
|
64 |
|
65 | ### Options
|
66 |
|
67 | *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.*
|
68 |
|
69 | #### input
|
70 |
|
71 | ```typescript
|
72 | input: string | InputOptions;
|
73 |
|
74 | interface InputOptions {
|
75 | api?: string;
|
76 | bin?: string;
|
77 | }
|
78 |
|
79 | default {
|
80 | api: "src/index.ts";
|
81 | bin: "src-bin/index.ts";
|
82 | };
|
83 | ```
|
84 |
|
85 | *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.*
|
86 |
|
87 | #### sourcemap
|
88 |
|
89 | ```typescript
|
90 | sourcemap: boolean | "inline";
|
91 |
|
92 | default true;
|
93 | ```
|
94 |
|
95 | *Whether or not to generate source maps. Anything other than* `false` *or* `"inline"` *will default to* `true`*.*
|
96 |
|
97 | *This option can be overridden using* `per-build` *options. See* [`main`](#main)*,* [`module`](#module)*,* [`browser`](#browser) *and* [`bin`](#bin) *options.*
|
98 |
|
99 | #### esModule
|
100 |
|
101 | ```typescript
|
102 | esModule: BuildType | BuildType[] | boolean;
|
103 |
|
104 | type BuildType = "main" | "browser" | "min";
|
105 |
|
106 | default false;
|
107 | ```
|
108 |
|
109 | *Whether or not to add a* `__esModule: true` *property to your non-es-module build. If* `esModule = true` *it will affect all builds.*
|
110 |
|
111 | *This option can be overridden using* `per-build` *options. See* [`main`](#main)*,* [`browser`](#browser) *&* [`bin`](#bin) *options.*
|
112 |
|
113 | #### interop
|
114 |
|
115 | ```typescript
|
116 | interop: BuildType | BuildType[] | boolean;
|
117 |
|
118 | type BuildType = "main" | "browser" | "min";
|
119 |
|
120 | default false;
|
121 | ```
|
122 |
|
123 | *Whether or not to add an interop block. If* `interop = true` *it will affect all builds.*
|
124 |
|
125 | *This option can be overridden using* `per-build` *options. See* [`main`](#main)*,* [`browser`](#browser) *&* [`bin`](#bin) *options.*
|
126 |
|
127 | #### format
|
128 |
|
129 | ```typescript
|
130 | format: "iife" | "amd" | "umd";
|
131 |
|
132 | default "umd";
|
133 | ```
|
134 |
|
135 | *Defines the format to be used for the* `browser` *build.*
|
136 |
|
137 | *This option can be overridden using the* [`browser`](#browser) *option.*
|
138 |
|
139 | #### name
|
140 |
|
141 | ```typescript
|
142 | name: string;
|
143 | ```
|
144 |
|
145 | *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.*
|
146 |
|
147 | *This option can be overridden using the* [`browser`](#browser) *option.*
|
148 |
|
149 | #### id
|
150 |
|
151 | ```typescript
|
152 | id: string;
|
153 | ```
|
154 |
|
155 | *Optional amd id for* `AMD` *or* `UMD` *build.*
|
156 |
|
157 | *This option can be overridden using the* [`browser`](#browser) *option.*
|
158 |
|
159 | *If not present,* `AMD` *module will be defined with no id.*
|
160 |
|
161 | #### extend
|
162 |
|
163 | ```typescript
|
164 | extend: boolean;
|
165 |
|
166 | default false;
|
167 | ```
|
168 |
|
169 | *Whether or not to extend the globally exposed name on a* `IIFE`, `UMD` *build.*
|
170 |
|
171 | *This option can be overridden using the* [`browser`](#browser) *option.*
|
172 |
|
173 | #### globals
|
174 |
|
175 | ```typescript
|
176 | globals: { [name: string]: string } | string[];
|
177 |
|
178 | default {};
|
179 | ```
|
180 |
|
181 | *Object or array to map names to globals in browser builds.*
|
182 |
|
183 | *This option can be overridden using the* [`browser`](#browser) *option.*
|
184 |
|
185 | #### equals
|
186 |
|
187 | ```typescript
|
188 | equals: boolean;
|
189 |
|
190 | default false;
|
191 | ```
|
192 |
|
193 | *Transforms type export for CommonJS module using* `export = ...` *instead of* `export default ...`*.*
|
194 |
|
195 | *This option can be overridden using the* [`types`](#types) *option.*
|
196 |
|
197 | > :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.*
|
198 |
|
199 | #### min
|
200 |
|
201 | ```typescript
|
202 | min: BuildType | BuildType[] | boolean;
|
203 |
|
204 | type BuildType = "main" | "module" | "browser" | "min";
|
205 |
|
206 | default false;
|
207 | ```
|
208 |
|
209 | *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)*.*
|
210 |
|
211 | *This option can be overridden using* `per-build` *options. See* [`main`](#main)*,* [`module`](#module)*,* [`browser`](#browser) *&* [`bin`](#bin) *options.*
|
212 |
|
213 | #### cache
|
214 |
|
215 | ```typescript
|
216 | cache: string;
|
217 |
|
218 | default "node_modules/.cache/bundlib"
|
219 | ```
|
220 |
|
221 | *Defines the directory to be used for cache, relative to the project root.*
|
222 |
|
223 | #### main
|
224 |
|
225 | ```typescript
|
226 | main: CommonJSOptions | false;
|
227 |
|
228 | interface CommonJSOptions {
|
229 | sourcemap?: boolean | "inline";
|
230 | esModule?: boolean | null;
|
231 | interop?: boolean | null;
|
232 | min?: boolean | null;
|
233 | }
|
234 | ```
|
235 |
|
236 | *Specific options to be used in* `CommonJS` *build. They will override any corresponding option set in the top-level options. See* [`sourcemap`](#sourcemap)*,* [`esModule`](#esmodule)*,* [`interop`](#interop) *&* [`min`](#min) *options.*
|
237 |
|
238 | *If it's set to* `false`*, it will prevent* `CommonJS` *build altogether, even if there is a* `main` *field in* `package.json`*.*
|
239 |
|
240 | #### module
|
241 |
|
242 | ```typescript
|
243 | module: ESModuleOptions | false;
|
244 |
|
245 | interface ESModuleOptions {
|
246 | sourcemap?: boolean | "inline";
|
247 | min?: boolean;
|
248 | }
|
249 | ```
|
250 |
|
251 | *Specific options to be used in* `ESModule` *build. They will override any corresponding option set in the top-level options. See* [`sourcemap`](#sourcemap) *&* [`min`](#min) *options.*
|
252 |
|
253 | *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`*.*
|
254 |
|
255 | #### browser
|
256 |
|
257 | ```typescript
|
258 | browser: BrowserOptions | false;
|
259 |
|
260 | interface BrowserOptions {
|
261 | sourcemap?: boolean | "inline";
|
262 | esModule?: boolean;
|
263 | interop?: boolean;
|
264 | min?: boolean;
|
265 | format?: "iife" | "amd" | "umd" ;
|
266 | name?: string;
|
267 | id?: string;
|
268 | extend?: boolean;
|
269 | globals?: { [name: string]: string } | string[];
|
270 | }
|
271 | ```
|
272 |
|
273 | *Specific options to be used in* `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) *&* [`globals`](#globals) *options.*
|
274 |
|
275 | *If it's set to* `false`*, it will prevent* `Browser` *build altogether, even if there is a* `browser` *field in* `package.json`*.*
|
276 |
|
277 | #### bin
|
278 |
|
279 | ```typescript
|
280 | bin: CommonJSOptions | false;
|
281 |
|
282 | interface CommonJSOptions {
|
283 | sourcemap?: boolean | "inline";
|
284 | esModule?: boolean;
|
285 | interop?: boolean;
|
286 | min?: boolean;
|
287 | }
|
288 | ```
|
289 |
|
290 | *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) *&* [`min`](#min) *options.*
|
291 |
|
292 | *If it's set to* `false`*, it will prevent* `Binary` *build altogether, even if there is a* `bin` *field in* `package.json`*.*
|
293 |
|
294 | > :warning: *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`](#input) *option instead.*
|
295 |
|
296 | #### types
|
297 |
|
298 | ```typescript
|
299 | types: TypesOptions | false;
|
300 |
|
301 | interface TypesOptions {
|
302 | equals: boolean;
|
303 | }
|
304 | ```
|
305 |
|
306 | *Specific options to be used for types generation. They will override any corresponding option set in the top-level options. See* [`equals`](#equals) *option.*
|
307 |
|
308 | *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`*.*
|
309 |
|
310 | ## CLI
|
311 |
|
312 | ```bash
|
313 | bundlib [options]
|
314 | ```
|
315 |
|
316 | ### CLI Options
|
317 |
|
318 | *Combine options according to your needs. Run* `bundlib -h` *for a detailed help.*
|
319 |
|
320 | #### `--dev`, `-d`
|
321 |
|
322 | *Create development, not minified builds. Builds affected by the* [`min`](#min) *option will ignore this option.*
|
323 |
|
324 | #### `--watch`, `-w`
|
325 |
|
326 | *Run* `bundlib` *in watch mode.*
|
327 |
|
328 | #### `--silent`, `-s`
|
329 |
|
330 | *Prevent messages from showing in the console.*
|
331 |
|
332 | #### `--version`, `-v`
|
333 |
|
334 | *Show* `bundlib` *version.*
|
335 |
|
336 | #### `--help`, `-h`
|
337 |
|
338 | *Show detailed help about the cli tool.*
|
339 |
|
340 | ## API
|
341 |
|
342 | ***example***
|
343 |
|
344 | ```javascript
|
345 | // rollup.config.js
|
346 |
|
347 | import { configsFromPkg } from "bundlib";
|
348 |
|
349 | const dev = !process.env.production;
|
350 |
|
351 | export default configsFromPkg(
|
352 | process.cwd(),
|
353 | { dev },
|
354 | );
|
355 | ```
|
356 |
|
357 | ### analizePkg
|
358 |
|
359 | ```typescript
|
360 | function analizePkg(
|
361 | cwd: string,
|
362 | pkg: PkgJson = read(cwd + "/package.json"),
|
363 | ): Promise<PkgAnalized>;
|
364 | ```
|
365 |
|
366 | *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`*.*
|
367 |
|
368 | > :warning: *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.*
|
369 |
|
370 | ### configsFromPkg
|
371 |
|
372 | ```typescript
|
373 | function configsFromPkg(
|
374 | cwd: string,
|
375 | options: { dev? boolean, watch?: boolean } | null | false,
|
376 | pkg: PkgJson = read(cwd + "/package.json"),
|
377 | ): Promise<RollupOptions[]>;
|
378 | ```
|
379 |
|
380 | *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`*.*
|
381 |
|
382 | ## Types
|
383 |
|
384 | ### PkgAnalized
|
385 |
|
386 | ```typescript
|
387 | interface PkgAnalized {
|
388 | cwd: string;
|
389 | pkg: PkgJson;
|
390 | input: {
|
391 | api: string;
|
392 | bin: string;
|
393 | };
|
394 | output: {
|
395 | main: CommonJSBuildOptions | null;
|
396 | module: ESModuleBuildOptions | null;
|
397 | browser: BrowserBuildOptions | null;
|
398 | bin: CommonJSBuildOptions | null;
|
399 | types: TypesBuildOptions | null;
|
400 | };
|
401 | dependencies: {
|
402 | runtime: string[] | null;
|
403 | peer: string[] | null;
|
404 | optional: string[] | null;
|
405 | };
|
406 | cache: string;
|
407 | }
|
408 | ```
|
409 |
|
410 | *see also:* [`CommonJSBuildOptions`](#commonjsbuildoptions), [`ESModuleBuildOptions`](#esmodulebuildoptions), [`BrowserBuildOptions`](#browserbuildoptions) & [`TypesBuildOptions`](#typesbuildoptions)
|
411 |
|
412 | ### CommonJSBuildOptions
|
413 |
|
414 | ```typescript
|
415 | interface CommonJSBuildOptions {
|
416 | path: string;
|
417 | sourcemap: boolean | "inline";
|
418 | esModule: boolean;
|
419 | interop: boolean;
|
420 | min: boolean;
|
421 | }
|
422 | ```
|
423 |
|
424 | ### ESModuleBuildOptions
|
425 |
|
426 | ```typescript
|
427 | interface ESModuleBuildOptions {
|
428 | path: string;
|
429 | sourcemap: boolean | "inline";
|
430 | min: boolean;
|
431 | }
|
432 | ```
|
433 |
|
434 | ### BrowserBuildOptions
|
435 |
|
436 | ```typescript
|
437 | interface BrowserBuildOptions {
|
438 | path: string;
|
439 | sourcemap: boolean | "inline";
|
440 | esModule: boolean;
|
441 | interop: boolean;
|
442 | min: boolean;
|
443 | format: "iife" | "amd" | "umd";
|
444 | name: string | null;
|
445 | id: string | null;
|
446 | globals: Record<string, string> | null;
|
447 | extend: boolean;
|
448 | }
|
449 | ```
|
450 |
|
451 | ### TypesBuildOptions
|
452 |
|
453 | ```typescript
|
454 | interface TypesBuildOptions {
|
455 | path: string;
|
456 | equals: boolean;
|
457 | }
|
458 | ```
|
459 |
|
460 | ## Known Issues
|
461 |
|
462 | * [Issue #7](https://github.com/manferlo81/bundlib/issues/7)
|
463 |
|
464 | ## Features
|
465 |
|
466 | * *Creates a* `CommonJS` *Module based on the* `"main"` *field in* `package.json`
|
467 | * *Creates an* `ES Module` *based on the* `"module"` *or* `"jsnext:main"` *field in* `package.json`
|
468 | * *Creates an* `Browser` *build based on the* `"browser"` *field in* `package.json` *(only if* `"browser"` *field value is a* `string`*)*
|
469 | * *Creates an CLI* `Binary` *build based on the* `"bin"` *field in* `package.json` *(only if* `"bin"` *field value is a* `string`*)*
|
470 | * *Exports type declarations based on the* `"types"` *or* `"typings"` *field in your* `package.json`
|
471 | * *Skip any build based on options*
|
472 | * *Sets* `"dependencies"`*,* `"peerDependencies"` *and `"optionalDependencies"` *as external for* `CommonJS`*,* `ES Module` *and* `Bynary` *modules*
|
473 | * *Uses the user copy of* `typescript` *if installed*
|
474 | * *Uses* `chokidar` *if installed*
|
475 | * *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`
|
476 | * *Transforms* `async/await` *using* [`Babel`](https://babeljs.io) *and* [`babel-plugin-transform-async-to-promises`](https://github.com/rpetrich/babel-plugin-transform-async-to-promises) *for ES5 support*
|
477 | * *Dynamic Import support through* [`@babel/plugin-syntax-dynamic-import`](https://babeljs.io/docs/en/babel-plugin-syntax-dynamic-import)
|
478 | * `React JSX` *support through* [`@babel/preset-react`](https://babeljs.io/docs/en/next/babel-preset-react)
|
479 | * Uses [`@babel/preset-env`](https://babeljs.io/docs/en/next/babel-preset-env)
|
480 | * *Minifies build using* [`Terser`](https://github.com/terser-js/terser)
|
481 |
|
482 | ## License
|
483 |
|
484 | [MIT](LICENSE) © [Manuel Fernández](https://github.com/manferlo81)
|