cmake-js

CMake.js is a build tool for Node.js native addons that uses the CMake build system instead of gyp. It is designed to work similarly to node-gyp but provides better integration with CMake-based projects.

Supported Runtimes

• Node.js: Version 14.15+ (for older runtimes, use an earlier version of CMake.js).
• NW.js: Compatible out-of-the-box without extra magic.
• Electron: Out-of-the-box build support with no post-build steps required.

Note: If your module uses node-api instead of nan, it can typically run on all the above runtimes without needing separate builds for each.

CMake.js provides a CMAKE_JS_VERSION variable. You can use this to conditionally include subdirectories or logic specifically for CMake.js based builds.

if (CMAKE_JS_VERSION)
    add_subdirectory(node_addon)
else()
    add_subdirectory(other_subproject)
endif()

CMake.js automatically picks up configuration from your .npmrc or NPM configuration. Any key starting with cmake_js_ is converted into a CLI option.

• If the option name is a single character, it is treated as a short flag (e.g., cmake_js_d becomes -d).
• Otherwise, it is treated as a long flag (e.g., cmake_js_directory becomes --directory).

# In .npmrc
cmake_js_debug=true
cmake_js_runtime=node18

Standard Node.js buildpacks on Heroku provide node-gyp but not CMake. To use CMake.js on Heroku, use the heroku-buildpack-multi facility.

1. Set the application's buildpack to: https://github.com/heroku/heroku-buildpack-multi.git
2. Create a .buildpacks file in your root directory with these two lines:

   https://github.com/brave/heroku-cmake-buildpack.git
   https://github.com/heroku/heroku-buildpack-nodejs.git

3. Deploy your application.

Electron

On Windows, native modules require the win_delay_load_hook to be embedded to load correctly in the render process.

How to enable: CMake.js will automatically add this hook if your CMakeLists.txt contains the library ${CMAKE_JS_SRC}.

NW.js

CMake.js modules are compatible with NW.js out-of-the-box. To make an NW.js application compatible with any NAN-based CMake.js modules, configure the application's package.json as follows:

{
  "cmake-js": {
    "runtime": "nw",
    "runtimeVersion": "nw.js-version-here",
    "arch": "appropriate-architecture"
  }
}

To use CMake.js, you must have the following installed on your system:

Core Requirements

• CMake: The build system itself.
• C/C++ Compiler Toolchain:
  • Windows: Visual C++ Build Tools. You can install these via the Node.js installer or via Chocolatey using choco install visualstudio2017-workload-vctools.
  • Unix/Posix: Clang or GCC, and Ninja or Make (Ninja is preferred if both are present).

Windows Specifics

If you have multiple versions of Visual Studio installed, you can select a specific version using npm configuration (this also affects node-gyp): npm config set msvs_version 2017

The cmake-js CLI is the primary interface for managing the lifecycle of a C++ Node.js addon project. It handles installing Node.js distribution files, configuring CMake projects, building, cleaning, and more. If no command is provided, it defaults to build.

# Build the project (default command)
cmake-js build

# Install Node.js distribution files
cmake-js install

# Configure the project
cmake-js configure

# Clean the project directory
cmake-js clean

To pass custom definitions to the underlying CMake process, use the --CD flag with an equals sign. The format must be --CD<key>=<value>.

# Example: Passing a custom CMake definition
cmake-js build --CDMY_CUSTOM_OPTION=ON

Install cmake-js as a dependency using npm to begin building Node.js native addons with CMake.

npm install cmake-js

CMake.js automatically integrates with NPM configuration. Any NPM config setting prefixed with cmake_ is automatically converted into a CMake definition (-D).

For example, an NPM config entry cmake_MY_SETTING=true will be passed to CMake as -D MY_SETTING=true.