nanobundle v2.1.0
nanobundle
Perfect build tool for libraries, powered by esbuild
Nanobundle is currently testing in RC version, feel free to leave feedback on the issue tracker!
Features
- Automatic entry points
- TypeScript
NodeNext
resolution - Support for ESM and CommonJS
- Support multple/complex entries by Conditional Exports
- 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", // conditional exports for entries "exports": { "./client": { "types": "./lib/client.d.ts", "require": "./lib/client.min.js", "import": "./lib/client.min.mjs" }, "./server": { "types": "./lib/server.d.ts", "require": "./lib/server.js", "import": "./lib/server.mjs" }, "./package.json": "./package.json" }, "scripts": { "build": "nanobundle build" } }
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 adding another customizing options.
Automatic entry points
You don't need to pass or set entry points in any configuration file, only you have to do is provide correct exports
in your package.json
.
nanobundle will automatically search for entry files in the rootDir
and outDir
you have. (defaults are src
and lib
, or respectively configurable by tsconfig.json
or CLI arguments)
{
"main": "./lib/index.js", // => search src/index.cts, src/index.ts, etc
"module": "./lib/index.mjs", // => search src/index.mts, src/index.ts, etc
"exports": {
"./feature": "./lib/feature.js" // => search src/feature.cts, src/feature.ts, etc
}
}
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:.
- Pass
--platform=node
flag - Set the entry point with
node
condition.
Without engines
field in package.json
, the default Node.js version will be v14.
Conditional Exports
You can specify multiple/conditional entry points in your package.json
.
See Node.js docs for more detail.
{
"type": "module",
"main": "./main.js", // Legacy entry
"exports": {
".": "./main.js",
"./feature": {
"node": "./feature-node.js", // conditional entry
"default": "./feature.js"
}
}
}
You can use conditional exports for dealing with Dual Package Hazard. E.g. for supporting both CommonJS and ESM package.
{
"exports": {
"require": "./lib/index.cjs",
"import": "./lib/index.mjs"
}
}
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": {
"node": "dep-node-native",
"default": "./dep-polyfill.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.
nanobundle automatically generate TypeScript declaration as you specify types
entries in the package.json
, or you can disable it passing --no-dts
flag.
Minification
Any entires with .min.(c|m)?js
will generate minified output.
{
"exports": "./index.min.js" // will be minifies output
}
Using process.env.NODE_ENV
with condition
Conditional entries with Node.js community condition production
or development
will be built with injected process.env.NODE_ENV
as its value.
{
"exports": {
".": {
"development": "./dev.js", // process.env.NODE_ENV === 'development'
"production": "./prod.min.js" // process.env.NODE_ENV === 'production'
}
}
}
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
1 year ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago