@comandeer/rollup-lib-bundler

Super opinionated library bundler using Rollup, Babel and terser.

Installation

npm install @comandeer/rollup-lib-bundler --save-dev

Usage

Just make it a npm script:

"scripts": {
	"build": "rlb"
}

Configuration

No configuration. Consider it a feature.

How does it work?

It gets package.json from the current working directory, parses it and fetches the neeeded info:

• name, author, version and license to create beautiful banner comment,
• exports.import to determine where to save ESM bundle (see the "Supported exports syntax" section for more info).

Then the bundling happens. The default entry point for Rollup is src/index.js.

[!WARNING] Please note that dist directory is purged before bundling! So if anything should be there alongside the bundle, it should be added there after the bundling.

Assumed file structure

This is very opinionated bundler and it assumes that the project's file structure looks like the one below:

package/
|- package.json
|- src/
|     |- index.js
|     |- some-other-chunk.js
|- dist/
|      |- bundled-index.mjs
|      |- bundled-index.mjs.map
|      |- bundled-some-other-chunk.mjs
|      |- bundled-some-other-chunk.mjs.map

• package.json is in the root of the package (the only bit we all agree on!),
• src/ directory contains package's source,
  • index.js is the main entrypoint of the package,
  • some-other-chunk.js is the optional additional entrypoint (see [#mutliple-bundles](Multiple bundles) section for more info),
• dist/ directory contains bundled code.

Bundler search for source files with the following extensions in the following order:

• .mts,
• .ts,
• .mjs,
• .js,
• .cts,
• .cjs.

Multiple bundles

By default, src/index.js is treated as the only entry point. However, using subpath exports you can create several bundled chunks/files. Example:

"exports": {
	".": {
		"import": "./dist/package.mjs"
	},

	"./chunk": {
		"import": "./dist/chunk.mjs"
	}
}

In this case two source files will be bundled:

• src/index.js:
  • ESM output: dist/package.mjs,
• src/chunk.js:
  • ESM output: dist/chunk.mjs.

Each subpath is translated to appropriate file in src directory. Basically, ./ at the beginning is translated to src/ and the name of the subpath is translated to <subpath>.<extension> (e.g. ./chunk → src/chunk.js). The only exception is the . subpath, which is translated to src/index.js.

As of version 0.19.0 the bundler also automatically omits bundling bundles inside other bundles. If there were an import of the src/chunk.js file inside the src/index.js file in the above structure, then the dist/package.(c|m)js file would contain an import from dist/chunk.(c|m)js file instead of the content of the other bundle.

Supported exports syntax

The bundler supports only the subset of the exports syntax allowed by the Node.js:

• exports as a string:

   {
   	"exports": "./dist/package.mjs"
   }

• subpaths as strings:

   {
   	"exports": {
   		".": "./dist/package.mjs",
   		"./subpath": "./dist/chunk.js"
   	}
   }

• exports with conditional exports:

   {
   	"exports": {
   		"types": "./dist/package.d.mts",
   		"import": "./dist/package.mjs"
   	}
   }

• subpaths with conditional exports:

   {
   	"exports": {
   		".": {
   			"types": "./dist/package.d.mts",
   			"import": "./dist/package.mjs"
   		}
   	}
   }

Transpilation

The bundler transpiles all the code with Babel. The transpilation target can be specified with the engines.node field in the package.json file:

{
	"engines": {
		"node": "20.1.0"
	}
}

Any valid semver syntax is supported.

If the engines.node field is not specified or it contains invalid version, the bundler fallbacks to the current version – so the version of Node that was used to run the bundler.

TypeScript support

Starting from v0.17.0 the bundler is able also to bundle TypeScript projects. There is no configuration needed, just replace the .js extension with the .ts one! Also ensure that there's a valid tsconfig.json file in the root of your project. If you want to provide different configuration for the bundler, place a tsconfig.rlb.json file instead.

[!WARNING] The outDir config option is overridden by the bundler to point to the same directory as the one in the Rollup's configuration. See #327 for more details.

The bundler also bundles .d.ts files but only if you specified the exports.types field in your package.json.

Sample configuration for a TS project:

"exports": {
	".": {
		"types": "./dist/index.d.ts",
		"import": "./dist/index.mjs"
	},

	"./chunk": {
		"import": "./dist/chunk.mjs"
	}
}

In this case two source files will be bundled:

• src/index.ts:
  • ESM output: dist/index.mjs,
  • DTS output: dist/index.d.ts,
• src/chunk.ts:
  • ESM output: dist/chunk.mjs,
  • DTS output: none (there's no types field).

Bundling executables (aka binaries)

From v0.19.0 rlb can also bundle executables defined in the bin field of the package.json. It supports both the simple format of that field and the complex one. Source files for binaries must be placed in the src/__bin__ directory with the same name as in the bin field. All source file formats supported for exports bundles are also supported for the bin ones.

All bundles created from the bin field are saved in the ESM format. The bundler will also preserve shebang in the produced bundle.

Example with the simple bin format

{
	"name": "some-package",
	"exports": {
		".": {
			"import": "./dist/index.mjs"
		}
	},
	"bin": "./dist/bin.mjs"
}

In that case bundler excepts the following source file structure:

some-package/
|- package.json
|- src/
|     |- index.js
|     |- __bin__/
|     |         |- some-package.js

Please note that when using the simple bin format (so just the path to the executable, without its name), the bundler will look for the source file with the name of the package (derived from the name field in the package.json files).

Example with the complex bin format

{
	"name": "some-package",
	"exports": {
		".": {
			"import": "./dist/index.mjs"
		}
	},
	"bin": {
		"whatever": "./dist/bin.mjs",
		"another-one": "./dist/bin2.js"
	}
}

In that case bundler excepts the following source file structure:

some-package/
|- package.json
|- src/
|     |- index.js
|     |- __bin__/
|     |         |- whatever.js
|     |         |- another-one.js

Support for non-standard dist directories

From v0.20.0 the bundler officially supports non-standard dist directories (different than the ./dist one). The dist directory is resolved from the exports field in the package.json, e.g.:

"exports": {
	".": {
		"import": "./hublabubla/package.mjs"
	}
}

In the above example, the ./hublabubla directory will be used instead of the ./dist one.

The bundler supports also multiple non-standard dist directories, e.g.:

"exports": {
	".": {
		"import": "./bublahubla/package.mjs"
	},
	"./chunk": "./hublabubla/chunk.mjs"
}

[!WARNING] Non-standard dist directories are purged befored the bundling! So if anything should be there alongside the bundle, it should be added there after the bundling.

Configuring VSC to correctly suggest imports

VSC uses TypeScript rules to suggest imports. However, TS uses CJS rules by default, ignoring the constraints of the exports field and suggesting the whole file paths (e.g. <package>/dist/<file> instead of <package>/<submodule-name>). To fix it, TS must be configured by tsconfig.json or jsconfig.json file to resolve modules according to ESM rules:

{
	"module": "node16",
	// or
	"moduleResolution": "node16"
}

License

See LICENSE file for details.