{"id":18224,"library":"cmake-ts","title":"cmake-ts","description":"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+).","status":"active","version":"1.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/EmbeddedEnterprises/cmake-ts","tags":["javascript","cmake","nan","node","native","addon","build","cmake-js","typescript"],"install":[{"cmd":"npm install cmake-ts","lang":"bash","label":"npm"},{"cmd":"yarn add cmake-ts","lang":"bash","label":"yarn"},{"cmd":"pnpm add cmake-ts","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used for runtime addon loading and prebuild detection","package":"@aminya/node-gyp-build","optional":true},{"reason":"The CMake build system is required at build time","package":"cmake","optional":false}],"imports":[{"note":"ESM-only; the loader is an .mjs file, not requireable. Available since v0.6.0.","wrong":"const loadAddon = require('cmake-ts/build/loader');","symbol":"loadAddon","correct":"import { loadAddon } from 'cmake-ts/build/loader.mjs';"},{"note":"Default export is ESM-only; CommonJS require is not supported. Use dynamic import if needed.","wrong":"const cmakeTs = require('cmake-ts');","symbol":"default","correct":"import cmakeTs from 'cmake-ts';"},{"note":"Manifest type is exported from 'cmake-ts/build/types', not the main entry. Type-only import avoids runtime inclusion.","wrong":"import { Manifest } from 'cmake-ts';","symbol":"type Manifest","correct":"import type { Manifest } from 'cmake-ts/build/types';"}],"quickstart":{"code":"// Build your native addon using cmake-ts CLI\n// Ensure CMake is installed (https://cmake.org/download)\n// Create CMakeLists.txt in project root\n\nimport { loadAddon } from 'cmake-ts/build/loader.mjs';\nimport path from 'node:path';\nimport { fileURLToPath } from 'node:url';\n\nconst __dirname = path.dirname(fileURLToPath(import.meta.url));\n\n// Load the addon built by cmake-ts\n// The loader automatically finds the correct binary for current runtime/architecture\nconst addon = loadAddon(path.resolve(__dirname, 'build'));\n\n// Use the addon\nconsole.log(addon.myNativeFunction());\n\n// Build via CLI: cmake-ts build --config release\n// Cross-compile: cmake-ts build --config cross-linux-arm64-release","lang":"typescript","description":"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."},"warnings":[{"fix":"Use the loader's manifest to resolve paths dynamically instead of hardcoding.","message":"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.","severity":"breaking","affected_versions":">=0.6.1"},{"fix":"Ensure you use the public API and the loader from 'cmake-ts/build/loader.mjs'.","message":"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.","severity":"breaking","affected_versions":">=0.5.2"},{"fix":"Replace 'downloadZip' calls with the updated download utilities from '@aminya/node-gyp-build' or similar.","message":"The download utility 'downloadZip' was removed in v0.5.3. Use the new download utils instead.","severity":"deprecated","affected_versions":">=0.5.3"},{"fix":"Use dynamic import() or switch to an ESM project. If running CommonJS, consider using import('cmake-ts/build/loader.mjs').","message":"The loader file is in .mjs format, so it cannot be required with require(). This is intentional as it's ESM-only.","severity":"gotcha","affected_versions":">=0.6.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Use dynamic import: const { loadAddon } = await import('cmake-ts/build/loader.mjs');","cause":"Using CommonJS require on an .mjs file.","error":"Error: Cannot find module 'cmake-ts/build/loader'"},{"fix":"Run `cmake-ts build --config release` to build for the current runtime, or ensure cross-compilation config is correct.","cause":"No prebuilt binary matches the current runtime (e.g., node vs electron, or different ABI).","error":"AssertionError [ERR_ASSERTION]: The addon was not built for this runtime/architecture"},{"fix":"Install CMake from https://cmake.org/download/ or use a package manager (apt, brew, choco) and add to PATH.","cause":"CMake is required but not installed.","error":"Error: CMake is not installed or not found in PATH"},{"fix":"Run `cmake-ts build` to generate the manifest. Ensure you are using cmake-ts v0.6.0+.","cause":"The build directory does not contain a manifest.json (e.g., not built with cmake-ts or old version).","error":"Error: ENOENT: no such file or directory, open 'manifest.json'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}