Unbundle traces JavaScript dependencies in your code to resolve export/import/import() paths. The output files contain relative file paths, as supported by modern browsers.
Unbundle follows the UNIX philosophy of doing one job well. Use other tools to further process the files for minification, revving, auditing, server pushing, etc.
The Commons Host dashboard web app uses Unbundle. See the build script in its package.json file.
Code: https://gitlab.com/commonshost/website
$ unbundle --entry app.js --destination dist
Where app.js is a source code entry file and dist is a to-be-created output directory.
Input: app.js uses unresolved paths and named imports
import widget from './widget'
import moment from 'moment'
const foobar = import('./foobar')
// ...
Output: 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.
const files = unbundle(entry, options)
entry is the path of a source file to transform, and optionally trace and transform its dependencies.
options is an object containing the properties:
recurse - Process all discovered dependencies. Default: trueroot - Prefix a custom path to the NPM dependencies in node_modules. Default: /verbose - Print information to the console. Default: falsefiles is a Map containing results. Keys are the source path. Values have the properties:
code - Transformed source code.from - Absolute input file path.to- Relative output file path.map - File name of the source map.unbundle [options]
-i, --entry <file>File path of source code entry point.
-o, --destination <directory>Directory path to write output.
--root"/"Prefix path for node_modules
-f, --forcefalseOverwrite existing files.
-r, --recursetrueRecursively trace all files.
--verbosefalseShow more information during file processing.
--versionShow version number
--helpShow version number
Trace all dependencies of src/app.js and output to dist directory.
unbundle --entry ./src/app.js --destination ./dist
Prefix imports of NPM packages with: /assets/scripts/node_modules/
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.
FAQs
import/export & node_modules in the browser, without the bundling
We found that unbundle demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.