Node-ninja: Native Addon Build Tool

1.0.2 · abandoned · verified Sun Apr 19

Node-ninja is a cross-platform command-line utility for compiling Node.js native addon modules. It serves as a fork of node-gyp, bundling the gyp project used by the Chromium team, with the long-term, unfulfilled goal of transitioning to the Ninja build system. The tool aims to simplify the process of building native modules across different platforms and supports compiling for multiple Node.js ABI versions by downloading necessary development headers. The current stable version is 1.0.2. Its release cadence is effectively non-existent, as the last release is considerably old, targeting historical Node.js versions (e.g., 0.8, 0.9, 0.10, 1.0) and Python 2.7. Key differentiators from upstream node-gyp, at the time of its last development, included better support for projects with multiple gyp files and incremental builds for prebuilds. However, it is now largely superseded by the actively maintained `node-gyp` and appears to be an abandoned project.

Common errors

```
gyp: Undefined variable PYTHON_VERSION in common.gypi while evaluating conditions. Make sure to specify a Python version via the PYTHON environment variable.
```
cause Python 2.x is not installed, not correctly configured in PATH, or Python 3.x is being used instead of Python 2.7.

fix Install Python 2.7 and ensure it's accessible in your system's PATH. On Windows, set the `PYTHON` environment variable to the full path of your `python.exe` for Python 2.7.
```
'msbuild.exe' is not recognized as an internal or external command, operable program or batch file.
```
cause Microsoft Visual C++ build tools (which include MSBuild) are not installed, or their path is not correctly configured in the environment variables for `node-ninja` to find them on Windows.

fix Install the required version of Microsoft Visual Studio (e.g., 2013, 2015 Community Edition) with the C++ development components. Ensure you open the command prompt via 'Developer Command Prompt for VS' or that relevant environment variables like `GYP_MSVS_VERSION` are set.
```
make: command not found
```
cause The `make` utility or a proper C/C++ compiler toolchain (like GCC on Linux or Xcode Command Line Tools on macOS) is not installed or not in the system's PATH.

fix On Linux, install `build-essential` (e.g., `sudo apt-get install build-essential`). On macOS, install Xcode from the App Store and then install its Command Line Tools via `xcode-select --install`.

Warnings

breaking node-ninja (and its underlying gyp dependency) strictly requires Python 2.7. It does NOT support Python 3.x, which is the current default for most operating systems. Using Python 3 will lead to build failures.
Fix: Ensure Python 2.7 is installed and accessible in your system's PATH. On Windows, verify the `PYTHON` environment variable points to `python.exe` for Python 2.7. You may need to manage Python versions carefully using tools like `pyenv` or `conda`.
gotcha The underlying `gyp` project, which node-ninja bundles and relies on, has been archived by Chromium and is no longer actively maintained. This means node-ninja builds rely on an unmaintained core dependency, posing potential compatibility and security risks for newer Node.js versions or operating systems.
Fix: Consider migrating your native addons to use `node-gyp`, which is the officially maintained build tool for Node.js native addons and receives regular updates. Be aware that this project is effectively abandoned.
gotcha The `node-ninja` project itself appears to be abandoned. The last release (v1.0.2) is significantly old, targeting historical Node.js versions, and the README explicitly states parts are out of date. This implies no active development, bug fixes, or compatibility updates for modern Node.js environments or operating systems.
Fix: For new projects or existing projects requiring modern Node.js support, it is strongly recommended to use `node-gyp` instead. For legacy projects, proceed with caution, anticipating potential build environment issues.
gotcha Building native addons on Windows often requires specific versions of Microsoft Visual C++ (MSVC). Incorrect or missing MSVC installations (e.g., needing 2013 or 2015 Community Edition with C++ tools) can lead to build failures.
Fix: Carefully follow the installation instructions in the README for your specific Windows version, ensuring you install the correct Visual Studio edition (e.g., 2015 Community) and select the C++ development workloads during installation. Set `GYP_MSVS_VERSION` environment variable if necessary.

Install

npm install node-ninja npm
yarn add node-ninja yarn
pnpm add node-ninja pnpm

Imports

node-ninja
```
n/a (CLI tool)
```
node-ninja is a command-line interface (CLI) tool and is not intended for programmatic import into JavaScript/TypeScript files. It is installed globally via npm and executed from the terminal.

Quickstart

Demonstrates the typical command-line installation and usage flow for `node-ninja` to configure and build a native Node.js addon.

// This JavaScript snippet describes how to use the node-ninja CLI tool.
// node-ninja itself is not imported into JavaScript applications but executed from the terminal.

console.log("First, install node-ninja globally via npm:");
console.log("  npm install -g node-ninja");

console.log("\nOnce installed, navigate to your native addon project directory.");
console.log("For example, if your project is 'my-native-addon':");
console.log("  cd my-native-addon");

console.log("\nThen, configure your native addon project. This step generates build files (e.g., Makefiles):");
console.log("  node-ninja configure");

console.log("\nFinally, build your native addon. This compiles your C/C++ source code:");
console.log("  node-ninja build");

console.log("\nTo build for a specific Node.js target version (useful for prebuilds):");
console.log("  node-ninja rebuild --target=0.10.0");

console.log("\nEnsure you have system dependencies like Python 2.7 and a C/C++ toolchain installed.");

view raw JSON →