cmake-ts

1.0.2 verified Sat Apr 25 auth: no javascript

cmake-ts v1.0.2 is a CMake-based build system for native Node.js and Electron addons, written in TypeScript. It is loosely inspired by cmake-js but fixes several design flaws, focusing on prebuilt addons and advanced build configurations. It ships TypeScript type definitions and supports cross-compilation for multiple architectures (arm64, x64, etc.) and runtimes (node, electron, iojs). The project is actively maintained with frequent releases on GitHub. Key differentiators include built-in support for cross-compilation via named configs, a manifest system for runtime addon loading, and compatibility with modern Node versions (12+).

Common errors

error Error: Cannot find module 'cmake-ts/build/loader' ↓

cause Using CommonJS require on an .mjs file.

fix

Use dynamic import: const { loadAddon } = await import('cmake-ts/build/loader.mjs');

error AssertionError [ERR_ASSERTION]: The addon was not built for this runtime/architecture ↓

cause No prebuilt binary matches the current runtime (e.g., node vs electron, or different ABI).

fix

Run cmake-ts build --config release to build for the current runtime, or ensure cross-compilation config is correct.

error Error: CMake is not installed or not found in PATH ↓

cause CMake is required but not installed.

fix

Install CMake from https://cmake.org/download/ or use a package manager (apt, brew, choco) and add to PATH.

error Error: ENOENT: no such file or directory, open 'manifest.json' ↓

cause The build directory does not contain a manifest.json (e.g., not built with cmake-ts or old version).

fix

Run cmake-ts build to generate the manifest. Ensure you are using cmake-ts v0.6.0+.

Warnings

breaking In v0.6.1, parent directory name changed from 'abi' to 'libc-abi-buildType' to prevent conflicts. If your package hardcodes the old path, it will fail to load. ↓

fix Use the loader's manifest to resolve paths dynamically instead of hardcoding.

breaking In v0.5.2, cmake-ts started using Vite for building. The legacy and modern bundles are provided. If you rely on internal module internals, your code may break. ↓

fix Ensure you use the public API and the loader from 'cmake-ts/build/loader.mjs'.

deprecated The download utility 'downloadZip' was removed in v0.5.3. Use the new download utils instead. ↓

fix Replace 'downloadZip' calls with the updated download utilities from '@aminya/node-gyp-build' or similar.

gotcha The loader file is in .mjs format, so it cannot be required with require(). This is intentional as it's ESM-only. ↓

fix Use dynamic import() or switch to an ESM project. If running CommonJS, consider using import('cmake-ts/build/loader.mjs').

Install

npm install cmake-ts

yarn add cmake-ts

pnpm add cmake-ts

Imports

loadAddon

wrong

const loadAddon = require('cmake-ts/build/loader');

correct

import { loadAddon } from 'cmake-ts/build/loader.mjs';

ESM-only; the loader is an .mjs file, not requireable. Available since v0.6.0.

default
wrong
```
const cmakeTs = require('cmake-ts');
```
correct
```
import cmakeTs from 'cmake-ts';
```
Default export is ESM-only; CommonJS require is not supported. Use dynamic import if needed.
type Manifest
wrong
```
import { Manifest } from 'cmake-ts';
```
correct
```
import type { Manifest } from 'cmake-ts/build/types';
```
Manifest type is exported from 'cmake-ts/build/types', not the main entry. Type-only import avoids runtime inclusion.

Quickstart

Shows how to build a native addon with cmake-ts and load it at runtime using the ESM loader. Demonstrates loader usage and CLI build command.

// Build your native addon using cmake-ts CLI
// Ensure CMake is installed (https://cmake.org/download)
// Create CMakeLists.txt in project root

import { loadAddon } from 'cmake-ts/build/loader.mjs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';

const __dirname = path.dirname(fileURLToPath(import.meta.url));

// Load the addon built by cmake-ts
// The loader automatically finds the correct binary for current runtime/architecture
const addon = loadAddon(path.resolve(__dirname, 'build'));

// Use the addon
console.log(addon.myNativeFunction());

// Build via CLI: cmake-ts build --config release
// Cross-compile: cmake-ts build --config cross-linux-arm64-release