export or dynamic
import() paths to explicit file paths. The output files are ready to be consumed by any modern browser. This lets you use ECMAScript modules (ESM) and NPM packages, the stuff from
node_modules, in the web browser without bundling everything into a single file. Or use process the generated files further using other tools for minification, revving, bundling, auditing, etc.
$ unbundle --entry app.js --destination dist
app.js is a source code entry file and
dist is a to-be-created output directory.
app.js uses unresolved paths and named imports
import widget from './widget' import moment from 'moment' const foobar = import('./foobar') // ...
dist/app.js has its import paths resolved
import widget from './widget.js' import lodash from '/node_modules/moment/src/moment.js' const foobar = import('./foobar.mjs') // ...
All sub-dependencies are recursively traced and written to the output directory in the correct location. Named dependencies, i.e. packages from NPM, are moved to a '/node_modules` sub-directory. Any NPM package that publishes ECMAScript modules (ESM) should work. See below for compatibility testing.
The resulting output directory looks like:
Any external source maps are also copied to the destination directory. They are only downloaded when the browser development tools are opened, so no performance penalty.
To make NPM packages (i.e.
node_modules) work on the web with the least amount of effort.
Tools like Browserify, Webpack, and Rollup exist to transpile various languages and module formats into a single, concatenated bundle. Depending on the use-case, configuring these tools and optimising their output requires significant effort and expertise.
Unbundle is a tiny tool. About 50 significant lines of code (SLoC). Standalone it is useful; composed with others it is powerful. That is the Unix philosophy of minimalist, modular, reusable tools.
Unbundle is designed for, but not limited to, delivering web apps with protocols like HTTP/2 Server Push. Other tools can be used to provide file revving for cache busting, code minification, AMD/UMD/CommonJS to ES2015 module conversion, Flow/TypeScript language transpilation, and more.
Earlier, defunct versions of Unbundle, anno 2016, did too much at once: support for JSX and Flow, injecting service workers with Cache Digest and
Cache-Control: immutable, file watching, multi-CPU cluster support, CLI progress reporting, file revving for cache busting, code minification, source maps, and more. That caused it to be good at exactly one workflow and wrong, to varying degrees, for almost everything else.
File path of source code entry point.
Directory path to write output.
Prefix for import paths
Overwrite existing files.
Recursively trace all files.
Show more information during file processing.
Show version number
Show version number
Trace all dependencies of
src/app.js and output to
unbundle --entry ./src/app.js --destination ./dist
Prefix imports of NPM packages with:
unbundle --entry index.js --destination public/assets/scripts --root /assets/scripts/
Anything that exports a standard ECMAScript module should work just fine. Please report any issues with the name and version of the problematic package.