npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@comandeer/rollup-lib-bundler

v0.25.0

Published

Simple library bundler

Downloads

337

Readme

@comandeer/rollup-lib-bundler

Build Status codecov npm (scoped)

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. ./chunksrc/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.