nanobundle
Yet another build tool for libraries, powered by esbuild
Features
- Support for ESM and CommonJS
- Support Import Maps
- Find and optimize the esbuild options for you
- Only configuration you need is
package.json
(and optionallytsconfig.json
)
Installation
-
Install by running
yarn add -D nanobundle
ornpm i -D nanobundle
-
Setup your
package.json
:{ "name": "your-package-name", "source": "./src/foo.ts", // required, the entry source file "module": "./dist/foo.mjs", // where to generate the ESM bundle "main": "./dist/foo.cjs", // where to generate the main entry (CommonJS by default, or ESM if `"type": "module"` and not `*.cjs`) "imports": { // import maps for modules/paths alias // ... }, "exports": { // export maps for multiple/conditional entries // ... }, "scripts": { "build": "nanobundle build" // compiles "source" to "main"/"module" } }
-
Try it out by running
yarn build
ornpm run build
Usage & Configuration
nanobundle is heavily inspired by microbundle, but more daring to try to remove the configuration much as possible. I believe the package.json
today is complex enough and already contains most of the configuration for common module use cases.
So attempting to turn users' attention back to the Node's package spec and some meaningful proposals like ES Modules and Import maps which are already supported by Node.js, rather than another custom configuration.
Build targets
nanobundle expects you to write a Web-compatible package.
If you use any Node.js APIs, you need to tell it explicitly via:.
- Set the entry point with
.cjs
or.node
extension - Specify Node.js version via
engines
field in thepackage.json
Without engines
, the default target will be Node.js v14.
Import Map
nanobundle supports Import maps
You can specify import alias by your package.json
, or by a separated json file with the --import-map
option.
{
"imports": {
"~/": "./",
"@util/": "./src/utils/",
// Node.js-style conditional imports
"#dep": {
"default": "./dep-polyfill.js",
"node": "dep-node-native"
}
}
}
Export Map
You can specify multiple/conditional entry points in your package.json
.
See Node.js docs for more detail.
{
"type": "module",
"main": "./main.js",
"exports": {
".": "./main.js",
"./feature": {
"default": "./feature.js",
"node": "./feature-node.js"
}
}
}
Embedding dependencies
nanobundle by default does nothing about external like dependencies
and peerDependencies
.
However, if the --standalone
flag is set, it will try to embed all external dependencies into the bundle.
Dependencies specified with --external
and Node.js internal APIs are always excluded.
TypeScript
Given a tsconfig.json
file in the cwd or --tsconfig
option, nanobundle looks for options for TypeScript and JSX.
You can specify declarationDir
in your tsconfig, or nanobundle infer the dir from types
entry.
nanobundle automatically generate TypeScript declaration as you specify types
entry in the package.json
, or you can disable it passing --dts=false
argument.
Alternatives
- microbundle : Rollup wrapper that provides similar concept
- esbuild : This is a simple esbuild wrapper so you can get similar results with just esbuild alone
- estrella : Build tool based on esbuild
- tsup : Zero-config bundler based on esbuild
License
MIT