node-cmake

library2.5.1jsnpmunverified

node-cmake is a build system for Node.js native modules that leverages CMake (version 3.1 or newer) as an alternative to the default node-gyp. The current stable version is 2.5.1. Major version 2.0 introduced a complete rewrite, aiming for drop-in execution compatibility with the `node-gyp` binary and standardization of its output format. Key differentiators include its reliance on CMake for greater build flexibility, a simplified and portable configuration script (`NodeJS.cmake`), and improved handling of Node.js variants. While its primary interaction is via CLI, it provides a JavaScript module for locating built native addons. The project's release cadence is not strictly defined, but major versions can introduce significant breaking changes, as seen with the 2.0 rewrite.

devops

npm install node-cmake

github ↗package ↗

INSTALL

IMPORT

SIG · NODE-CMAKE

node-cmake

devopsjavascriptv2.5.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

find

✓ import { find } from 'node-cmake/lib/binding';

✗ const find = require('node-cmake').find;

The `find` utility helps locate the compiled native addon (.node) file in the build output directory. This is for consuming the output of node-cmake, not for directly using the build system itself.

ncmake

✓ import { ncmake } from 'node-cmake';

✗ const ncmake = require('node-cmake'); ncmake.build();

This imports the main programmatic interface for `node-cmake`'s build logic (from `lib/ncmake.js`). While `node-cmake` is primarily a CLI tool, this export allows for advanced programmatic control over the build process.

commands

✓ import { commands } from 'node-cmake';

✗ const commands = require('node-cmake').cliCommands;

This exports an object containing the functions mapped to the `ncmake` command-line interface subcommands (e.g., `build`, `rebuild`, `update`). Useful for introspection or highly customized build orchestrations in JavaScript.

This quickstart demonstrates how to set up a Node.js native addon project using `node-cmake`. It includes `package.json` configurations, a `CMakeLists.txt` build script, a simple C++ source file (`my_module.cc`), and a JavaScript file (`index.js`) that uses the `node-cmake` helper to load and interact with the compiled native module. Run `npm install` to build the module, then `npm start` to execute the JavaScript example.

```json // package.json { "name": "my-native-addon-project", "version": "1.0.0", "private": true, "scripts": { "postinstall": "ncmake update", "build": "ncmake rebuild", "start": "node index.js" }, "devDependencies": { "node-cmake": "^2.5.1" } } ``` ```cmake // CMakeLists.txt cmake_minimum_required(VERSION 3.1) project(my_module VERSION 1.0.0) include(NodeJS.cmake) nodejs_init() add_nodejs_module(${PROJECT_NAME} my_module.cc) ``` ```cpp // my_module.cc #include <napi.h> Napi::String GreetMethod(const Napi::CallbackInfo& info) { Napi::Env env = info.Env(); return Napi::String::New(env, "world from C++!"); } Napi::Object Init(Napi::Env env, Napi::Object exports) { exports.Set(Napi::String::New(env, "greet"), Napi::Function::New(env, GreetMethod)); return exports; } NODE_API_MODULE(my_module, Init) ``` ```javascript // index.js const path = require('path'); const { find } = require('node-cmake').binding; async function main() { try { // Locate the built native module using node-cmake's helper const modulePath = find(process.cwd(), 'my_module.node'); if (!modulePath) { console.error("Error: Native module 'my_module.node' not found.\nMake sure to run 'npm install' to build the native addon."); process.exit(1); } const addon = require(modulePath); console.log(`Hello ${addon.greet()}`); // Expected: Hello world from C++! } catch (error) { console.error("Failed to load or execute native module:", error); process.exit(1); } } main(); ```

node-cmake --version

Debug

Known issues

breakingThe `find_package` support for `NodeJS` was removed in `node-cmake` v2.0 due to issues with deeply nested native dependencies. Projects upgrading from v1.x will encounter build failures if they continue to use `find_package`.

fix

Remove `find_package(NodeJS)` from your `CMakeLists.txt`. Instead, include the copied `NodeJS.cmake` script directly using `include(NodeJS.cmake)` after running `ncmake update` to copy the file to your project.

affects: >=2.0.0

breakingCommand-line arguments for `ncmake` were completely revised in v2.0 to align with `node-gyp`'s interface. Old commands like `ncmake --build` are no longer valid.

fix

Update your build scripts (e.g., `package.json` scripts) to use the new `node-gyp` compatible syntax, such as `ncmake rebuild` (which performs clean, configure, and build) instead of the old `--build` flag. Refer to the `node-cmake` manual for a complete list of new commands.

affects: >=2.0.0

gotchaThe `NodeJS.cmake` configuration script is copied into your project via `ncmake update`, not symlinked. This means automatic updates to `node-cmake` itself will not propagate changes to `NodeJS.cmake` in your project without manual intervention.

fix

Always run `ncmake update` after updating `node-cmake` to a new version (especially major ones) to ensure your project benefits from the latest configuration script changes and bug fixes.

affects: >=2.0.0

gotchaSupport for NW.js is significantly limited and may not function correctly due to inconsistencies in the NW.js release server structure, specifically regarding the `SHASUMS256.txt` file lacking checksums for all required resources. This prevents `node-cmake` from validating downloads.

fix

Users targeting NW.js should be aware of potential download and integrity validation issues. Consider alternative build systems or manual dependency management for NW.js until the upstream server compliance is addressed.

affects: >=2.0.0

Errors

Common errors & fixes

Error: `ncmake` command not found

`node-cmake` is a development dependency and its binary (`ncmake`) is not directly in your system's PATH, or the package was not installed.

fix

Ensure `node-cmake` is listed in your `devDependencies` in `package.json` and run `npm install`. When invoking `ncmake` in scripts, use `npm run <script-name>` or `npx ncmake` to ensure the binary is resolved correctly.

CMake Error at CMakeLists.txt:X (find_package): Could not find a package configuration file...

Attempting to use `find_package(NodeJS)` which was removed in `node-cmake` v2.0.

fix

Remove the `find_package(NodeJS)` call from your `CMakeLists.txt`. Instead, add `include(NodeJS.cmake)` and ensure you have run `ncmake update` to copy the necessary `NodeJS.cmake` file into your project.

Error: Unknown command --build. Did you mean rebuild?

Using an outdated command-line argument (`--build`) from `node-cmake` v1.x with a v2.x installation.

fix

Update your `package.json` scripts or any direct CLI invocations to use the new `node-gyp`-compatible commands, such as `ncmake rebuild`.

CMake Error at CMakeLists.txt:X (include): File NodeJS.cmake does not exist.

The `NodeJS.cmake` configuration file, which `node-cmake` provides, has not been copied to your project's root directory.

fix

Run `ncmake update` from your project's root directory. This command copies `NodeJS.cmake` into your project, making it available for inclusion in `CMakeLists.txt`.

Upgrade

Version history

2.5.1latest on npm

Audit

Dependencies

cmakerequiredRequired external build tool; Node-cmake acts as an interface and generates CMake build files. Requires CMake >= v3.1.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/cjntaylor/node-cmake ↗

packagehttps://www.npmjs.com/package/node-cmake ↗