install-binaries

Downloads, verifies and installs external binaries declared in your package.json.

This command-line tool keeps platform utilities and other external executables out of your npm package while making their installation reproducible.

Requirements

• Node.js 18 or later.
• A project containing a binaries section in its package.json.

Installation

npm i @itrocks/install-binaries

Run the command with npx:

npx install-binaries

You can also declare it as a project script. npm automatically adds node_modules/.bin to the command path, so npx is not needed there:

{
  "scripts": {
    "postinstall": "install-binaries"
  }
}

Configuration

Declare each binary in the binaries section of your project's package.json:

{
  "binaries": {
    "MultiMonitorTool": {
      "destination": "vendor/windows/MultiMonitorTool",
      "sha256": {
        "MultiMonitorTool.exe": "99b472f85fd905d7ffea461f80362ca1ddfbb13b958f21b14d8c94b542d938da"
      },
      "url": "https://www.nirsoft.net/utils/multimonitortool-x64.zip"
    }
  }
}

Each entry has three properties:

• url: file to download.
• destination: installation directory, relative to the project directory.
• sha256: checksum of the download or checksums of selected extracted files.

SHA-256 verification

Use a string when the checksum applies to the downloaded file itself:

{
  "sha256": "0123456789abcdef..."
}

The download is verified before extraction and kept in a .downloads directory under the destination. It can then be reused by later executions.

Use an object when checksums apply to files after extraction:

{
  "sha256": {
    "tool.exe": "0123456789abcdef...",
    "helper.exe": "fedcba9876543210..."
  }
}

Only the listed extracted files are verified. The downloaded archive is temporary and .downloads is not kept.

Checksums may optionally start with sha256: and are compared without regard to case or whitespace.

Supported downloads

The file type is detected from the URL filename:

• .zip
• .tgz and .tar.gz
• .gz
• uncompressed files

When an archive contains a single wrapping directory, it is automatically removed from the installation path. Other files from the archive are installed without overwriting existing unchecked files.

Behaviour

The command reads package.json from the current working directory and processes all entries from binaries.

Files with configured extracted checksums are left untouched when already valid. A stale .downloads directory is removed in this mode. Downloads verified directly are cached only after successful checksum verification.

Temporary files are created below .cache/binaries and removed after each installation attempt. The command exits with a failure status when at least one binary cannot be processed.