node-raylib

Node.js C++ bindings for raylib 6.0, using Node-API and raylib-cpp.

import rl from "node-raylib";

const window = new rl.Window(800, 450, "node-raylib");
window.setTargetFPS(60);

while (!window.shouldClose()) {
  window.beginDrawing();
  window.clearBackground(rl.colors.RAYWHITE);
  rl.drawText("Hello from Node.js", 250, 210, 20, rl.colors.BLACK);
  window.endDrawing();
}

window.close();

API conventions

• JavaScript uses camelCase methods and raylib-style constant names.
• Window, value types, cameras, and resources are JavaScript objects.
• Drawing helpers are procedural functions; stateful native objects expose methods.
• Color, vectors, rectangles, matrices, and cameras are value objects.
• Image, Texture, Font, Sound, Music, Shader, Model, Material, and Mesh own native resources.
• Resource objects expose .unload() for deterministic cleanup and .isLoaded() for state checks. Garbage collection also triggers native RAII cleanup.
• Invalid argument types, arity, and resource-load failures throw JavaScript exceptions.
• Native pointers and raylib C structs are not exposed directly.

Supported API surface

The current release includes:

• Window lifecycle and frame drawing
• Core 2D primitives and text
• Texture and model draw helpers
• 2D and 3D cameras
• Keyboard, mouse, gamepad, and touch polling
• Core raylib value types
• Managed resource bindings

See examples/simple-window.mjs for a runnable example.

Building

Requirements:

• Node.js 18 or newer
• CMake 3.20 or newer
• A C++17 compiler

npm install
npm run build
npm test
node examples/simple-window.mjs

The default package uses the vendored raylib static library. To use an external raylib installation on Linux or Windows, pass its root directory:

cmake --preset release -DRAYLIB_ROOT=/path/to/raylib
cmake --build --preset release

You can also provide an exact library path with -DRAYLIB_LIBRARY=....

The current repository includes universal macOS raylib libraries. macOS arm64 and x64 builds are the first packaged targets; Linux and Windows builds use the same CMake target with a platform-provided raylib library.

npm release flow

Build and stage a native artifact for the current platform:

npm run build
npm run stage-native
npm run release:check

For a release matrix, run the build on each target and set the target variables when staging the resulting binary:

NODE_RAYLIB_TARGET_PLATFORM=darwin \
NODE_RAYLIB_TARGET_ARCH=arm64 \
npm run stage-native

After all target artifacts are staged, validate and publish:

NODE_RAYLIB_RELEASE_TARGETS=darwin-arm64,darwin-x64,linux-x64,linux-arm64,win32-x64 \
npm run release:check
npm publish --access public

The loader selects build/artifacts/<platform>-<arch>/node_raylib.node and falls back to build/node_raylib.node for local development.