Create a shippable binary from a JS file
Last updated 2 months ago by addaleax .
Apache-2.0 · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install boxednode 
SYNC missed versions from official npm registry.

???? boxednode – Ship a JS file with Node.js in a box


  1. A JavaScript file
  2. Node.js

and pack them up as a single binary.

For example:

$ cat example.js
console.log('Hello, world!');
$ boxednode -s example.js -t example
$ ./example
Hello, world!

CLI usage

      --version         Show version number                            [boolean]
  -c, --clean           Clean up temporary directory after success     [boolean]
  -s, --source          Source .js file                      [string] [required]
  -t, --target          Target executable file               [string] [required]
  -n, --node-version    Node.js version or semver version range
                                                         [string] [default: "*"]
  -C, --configure-args  Extra ./configure or vcbuild arguments, comma-separated
  -M, --make-args       Extra make or vcbuild arguments, comma-separated[string]
      --tmpdir          Temporary directory for compiling Node.js source[string]
      --help            Show help                                      [boolean]

Node.js versions may be specific versions, semver ranges, or any of the aliases supported by

Programmatic API

type CompilationOptions = {
  // Single Node.js version, semver range or shorthand alias to pick from
  nodeVersionRange: string;

  // Optional temporary directory for storing and compiling Node.js source
  tmpdir?: string;

  // A single .js file that serves as the entry point for the generated binary
  sourceFile: string;

  // The file path to the target binary
  targetFile: string;

  // Optional list of extra arguments to be passed to `./configure` or `vcbuild`
  configureArgs?: string[];

    // Optional list of extra arguments to be passed to `make` or `vcbuild`
  makeArgs?: string[];

  // If true, remove the temporary directory created earlier when done
  clean?: boolean;

  // Environment variables for build processes. Defaults to inheriting
  // environment variables.
  env?: { [name: string]: string };

  // Specify the entrypoint target name. If this is 'foo', then the resulting
  // binary will be able to load the source file as 'require("foo/foo")'.
  // This defaults to the basename of sourceFile, e.g. 'bar' for '/path/bar.js'.
  namespace?: string;

  // A list of native addons to link in.
  addons?: AddonConfig[]

type AddonConfig = {
  // Path to the root directory of the target addon, i.e. the one containing
  // a binding.gyp file.
  path: string,

  // A regular expression to match for `require()` calls from the main file.
  // `require(str)` will return the linked binding if `str` matches.
  // This will *not* be the same as `require(path)`, which usually is a JS
  // wrapper around this.
  requireRegexp: RegExp

export function compileJSFileAsBinary(options: CompilationOptions);

The BOXEDNODE_CONFIGURE_ARGS environment variable will be read as a comma-separated list of strings and added to configureArgs, and likewise BOXEDNODE_MAKE_ARGS to makeArgs.

Why this solution

We needed a simple and reliable way to create shippable binaries from a source file.

Unlike others, this solution:

  • Works for Node.js v12.x and above, without being tied to specific versions
  • Uses only officially supported, stable Node.js APIs
  • Creates binaries that are not bloated with extra features
  • Creates binaries that can be signed and notarized on macOS
  • Supports linking native addons into the binary


This package compiles Node.js from source. See the Node.js file for a complete list of tools that may be necessary.

Not supported

  • Multiple JS files

Similar projects



Current Tags

  • 1.7.1                                ...           latest (2 months ago)

16 Versions

  • 1.7.1                                ...           2 months ago
  • 1.7.0                                ...           2 months ago
  • 1.6.3                                ...           2 months ago
  • 1.6.2                                ...           3 months ago
  • 1.6.1                                ...           3 months ago
  • 1.6.0                                ...           3 months ago
  • 1.5.1                                ...           3 months ago
  • 1.5.0                                ...           3 months ago
  • 1.4.0                                ...           4 months ago
  • 1.3.0                                ...           4 months ago
  • 1.2.3                                ...           4 months ago
  • 1.2.2                                ...           4 months ago
  • 1.2.1                                ...           4 months ago
  • 1.2.0                                ...           4 months ago
  • 1.1.0                                ...           4 months ago
  • 1.0.0                                ...           4 months ago

Copyright 2014 - 2016 © |