CMake.js

8.0.0 verified Sat Apr 25 auth: no javascript

CMake.js is a Node.js native addon build tool that replaces node-gyp's gyp with CMake. Current stable version is 8.0.0 (released late 2024), requiring Node.js >=20.17.0 or >=22.9.0. It supports Node.js, NW.js, and Electron runtimes out of the box, with automatic runtime detection and build configuration. Key differentiators: uses CMake instead of GYP, supports modern Node.js versions, built-in fetch for smaller install size, and native addon development without post-build steps for Electron/NW.js. Release cadence is irregular with major version bumps roughly every 1-2 years, each introducing breaking changes.

Common errors

error CMake Error: Could not find cmake module file: cmake-js.cmake ↓

cause CMakeLists.txt missing include line or cmake-js not installed

fix

Add 'include(../node_modules/cmake-js/cmake-js.cmake)' to CMakeLists.txt, or run 'npm install cmake-js'

error Error: Unable to detect runtime. Use --runtime and --runtime-version. ↓

cause cmake-js cannot auto-detect runtime from Node.js version

fix

Specify runtime explicitly: --runtime=node --runtime-version=20.0.0

error npm ERR! command cmake-js compile failed (exit code 1) ↓

cause Missing CMake installation or incompatible generator

fix

Install CMake >=3.10 and ensure generator matches platform (e.g., 'Unix Makefiles' on Linux, 'Visual Studio 17 2022' on Windows)

Warnings

breaking v8.0.0 dropped support for Node.js <20.17.0 and <22.9.0 ↓

fix Upgrade Node.js to ^20.17.0 || >=22.9.0

breaking v7.0.0 removed support for Node.js <14.15 ↓

fix Use v6.x for older Node.js or upgrade Node.js to 14.15+

breaking v7.0.0 changed CMake variable naming conventions - CMAKE_JS_SRC etc. require updates to CMakeLists.txt ↓

fix Update CMakeLists.txt to use new variable names as per upgrade guide

breaking v4.0.0 removed support for Visual Studio 2013 and older ↓

fix Use Visual Studio 2015 or newer

gotcha Cross-compilation requires manual CMAKE_TOOLCHAIN_FILE specification ↓

fix Use --cmake-path or -DCMAKE_TOOLCHAIN_FILE=... when targeting different architecture

gotcha Electron builds require --runtime=electron --runtime-version=X.Y.Z flags to match Electron's Node.js ABI ↓

fix Use: cmake-js compile --runtime=electron --runtimeVersion=28.0.0

Install

npm install cmake-js

yarn add cmake-js

pnpm add cmake-js

Imports

default (cmake-js CLI)
wrong
```
node -e "require('cmake-js')"
```
correct
```
npx cmake-js build
```
cmake-js is primarily used as a CLI tool, not a library import. Use npx or install globally.
CMakeJS (programmatic API)
wrong
```
import cmakejs from 'cmake-js';
```
correct
```
const cmakejs = require('cmake-js');
```
cmake-js is CommonJS-only. ESM import is not supported.

Quickstart

Shows minimal setup: CMakeLists.txt with cmake-js include hook, and CLI compile command.

// Create a minimal CMakeLists.txt in your project root:
// cmake_minimum_required(VERSION 3.10)
// project(MyNativeAddon)
// include(../node_modules/cmake-js/cmake-js.cmake)

// Then build:
// npx cmake-js compile

// Example package.json build script:
// { "scripts": { "build": "cmake-js compile" } }