bpkg Node.js Bundler

0.9.2 · abandoned · verified Sun Apr 19

bpkg is a command-line bundler and build tool specifically designed for Node.js projects, with an emphasis on handling native Node.js modules. It differentiates itself by requiring zero external dependencies for its operation, aiming for auditability and simplicity. It provides functionality similar to Browserify but with a stronger focus on Node.js-specific patterns, such as inlining or collecting native C++ bindings. The current version is v0.9.2. However, the project is considered abandoned; its GitHub repository is archived and marked as read-only, indicating no further development, bug fixes, or security patches will be provided. While it supports ES modules, full browser compatibility, and includes Babel/TypeScript/Uglify-JS support out of the box, its unmaintained status means these features may not be up-to-date with modern standards or environments.

Common errors

```
bpkg: command not found
```
cause The bpkg command-line tool is not installed globally or is not accessible in your system's PATH.

fix Install bpkg globally using npm: `npm install -g bpkg`, or execute it directly using `npx bpkg <command>`.
```
Error: Cannot find module 'some-native-module.node'
```
cause bpkg failed to correctly resolve or inline a native Node.js module dependency during the bundling process, or the path was incorrect.

fix Ensure the native module is correctly specified in your `package.json` and its location is accessible to bpkg. You might need to adjust bpkg's resolution options like `--collect-bindings` or `--ignore-bindings`, or manually ensure all native module dependencies are met.
```
SyntaxError: Unexpected token 'export' (or similar for modern JavaScript features)
```
cause bpkg's internal parser or transformers do not support the specific modern JavaScript syntax (e.g., ES modules, new language features) used in your source code by default.

fix Try using bpkg's `--esm` or `--es2015` flags if applicable. If the issue persists, you may need to transpile your source code with a tool like Babel or TypeScript *before* feeding it to bpkg, or switch to a more actively maintained bundler that natively supports modern JavaScript.

Warnings

breaking The bpkg project is no longer maintained and its GitHub repository is archived and read-only. It will not receive updates, bug fixes, or security patches, making it unsuitable for new projects or environments requiring ongoing support.
Fix: Consider using actively maintained alternatives for bundling, such as esbuild, Rollup, or Webpack, which provide current features, security updates, and community support.
gotcha As an unmaintained tool, bpkg may not correctly handle modern JavaScript syntax (e.g., newer ES module features, optional chaining, nullish coalescing) or new Node.js APIs without manual configuration or pre-processing, potentially leading to build failures or runtime errors.
Fix: Verify compatibility with your project's target Node.js version and JavaScript features. Manual transformations via Babel or TypeScript might be required if bpkg's built-in support is insufficient, or use a modern bundler.
gotcha bpkg's unique handling of native Node.js modules (inlining them as base64 or collecting separately) might introduce challenges with bundle size, security scanning tools, or module resolution in certain complex environments.
Fix: Thoroughly test bundled applications in all target environments, especially concerning native module loading and performance. Be aware of potential security implications of inlined binaries and review bundle contents carefully.
gotcha The package is pre-1.0 (v0.9.2) and unmaintained. This implies that even prior to its abandonment, it lacked the stability guarantees typically associated with 1.0+ versions, and any existing bugs, quirks, or undocumented behaviors will not be addressed.
Fix: Exercise extreme caution when integrating and ensure comprehensive testing. Expect that any encountered issues will likely require manual workarounds or switching to an alternative.

Install

npm install bpkg npm
yarn add bpkg yarn
pnpm add bpkg pnpm

Quickstart

Demonstrates how to globally install bpkg and then bundle the 'bcrypto' package, including its native C++ modules, into a single JavaScript file.

npm install -g bpkg

# Example: Bundle the 'bcrypto' package, including its native modules
bpkg ./node_modules/bcrypto bcrypto_bundle.js

# Now, bcrypto_bundle.js can be used as a standalone module:
# const bcrypto = require('./bcrypto_bundle.js');
# console.log(bcrypto.randomBytes(32));

view raw JSON →