GLFW for Node.js

This is a part of Node3D project.

npm install @node-3d/glfw

Node.js addon with GLFW3 bindings.

• GLFW version 3.4.0 backend.
• Exposes low-level GLFW interface.
• Multiple windows for a single Node.js process.
• Able to switch to fullscreen and back.
• Provides GlfwWindow, a native GLFW window wrapper for direct window/control work.
• Uses @node-3d/uv-loop for frame and loop scheduling.
• Keeps legacy Window and Document classes for compatibility with older code.
• Leaves browser-like Window/Document/canvas behavior to @node-3d/core.

The package has named exports only. Use glfw for the raw native bindings, and import GlfwWindow directly for native window management.

import { GlfwWindow, glfw } from '@node-3d/glfw';

const wnd = new GlfwWindow({ title: 'GLFW Test', vsync: true });

wnd.loop(() => {
	if (wnd.shouldClose || wnd.getKey(glfw.KEY_ESCAPE)) {
		process.exit(0);
		return;
	}
	
	glfw.testScene(wnd.width, wnd.height);
});

Note: this addon uses N-API, and therefore its GLFW binary is ABI-compatible across different Node.js versions. Frame scheduling depends on @node-3d/uv-loop, which ships Node-major-specific binaries because it calls Node's embedded libuv directly. Addon binaries are precompiled and there is no compilation step during the npm install command when matching archives are available.

Prebuilt addon binaries are provided for Windows x64/ARM64, Linux x64/ARM64, and macOS x64/ARM64.

Concern Separation

@node-3d/glfw is the GLFW layer:

• glfw exposes the raw native GLFW binding and constants.
• GlfwWindow wraps a native GLFW window handle with event, size, mode, context, frame, and loop helpers.
• Window and Document remain as legacy compatibility classes.

Browser-style application compatibility belongs in @node-3d/core:

• BrowserWindow owns browser-style requestAnimationFrame.
• BrowserDocument owns document/canvas/image/WebGL compatibility.
• init() wires globalThis.window, globalThis.document, WebGL, Image, and other browser-like globals.

GLFW

This is a low-level interface, where most of the stuff is directly reflecting GLFW API. GLFW does NOT EXPOSE OpenGL commands, it only controls the window-related setup and resources. To access OpenGL/WebGL API you can use @node-3d/webgl or any other similar addon.

Aside from several additional features, this addon directly exposes the GLFW API to JS. E.g.:

DBG_EXPORT JS_METHOD(pollEvents) {
	glfwPollEvents();
	RET_GLFW_VOID;
}

Nothing is added between you and GLFW, unless necessary or explicitly mentioned.

• All glfw* functions are accessible as glfw.*. E.g. glfwPollEvents -> glfw.pollEvents.
• All GLFW_* constants are accessible as glfw.*. E.g. GLFW_TRUE -> glfw.TRUE.
• Higher-level helpers are separate named exports. E.g. import { GlfwWindow } from '@node-3d/glfw'.
• Method glfw.createWindow takes some additional arguments. This is mostly related to JS events being generated from GLFW callbacks, and here's where you provide an Emitter object.
• Pointers are directly exposed as numbers to JS and are expected as arguments in specific methods. Such as, glfw.createWindow returns a number (pointer), and then you provide it back to e.g. glfw.setWindowTitle.

See this example for raw GLFW calls.

The public entrypoint exports glfw, GlfwWindow, legacy Window, legacy Document, and event/window option types. The lower-level raw API is on glfw; the classes are imported directly.

---

class GlfwWindow

import { GlfwWindow } from '@node-3d/glfw';

const wnd = new GlfwWindow({ title: 'GLFW Test', vsync: true });

This class manages native window objects and their events. It can also switch between fullscreen, borderless and windowed modes. It does not implement browser requestAnimationFrame or document/canvas compatibility.

frame() and loop() are scheduled through @node-3d/uv-loop instead of a recursive setImmediate loop. The scheduling target is maximum frame pacing stability for native rendering; use vsync, numeric swap intervals, or application-level timing checks when slower updates are needed.

vsync: true maps to swapInterval: -1 and vsync: false maps to swapInterval: 0. For direct presentation experiments, pass a number through vsync or use the clearer swapInterval option/property:

const wnd = new GlfwWindow({ title: 'GLFW Test', swapInterval: 1 });

wnd.swapInterval = 0;

Swap interval numbers are normalized before they reach GLFW: values below zero map to -1, values above zero map to 1, and 0 remains unpaced. Non-zero intervals enable Node3D's native frame-start gate and native driver sync underneath it. 1 uses glfwSwapInterval(1), while -1 uses adaptive glfwSwapInterval(-1) when the window's context reports swap-control tear support during creation, otherwise glfwSwapInterval(1).

Request	Platform	Window mode	Native behavior
false / 0	all	all	glfwSwapInterval(0)
true / negative number	all	all	native frame gate plus adaptive glfwSwapInterval(-1) when available, otherwise 1
positive number	all	all	native frame gate plus glfwSwapInterval(1)

Use swapInterval: 0 when you need raw unpaced presentation. Use vsync: true for Node3D's native frame-gated presentation behavior.

The native frame gate controls when render callbacks are emitted, but callbacks receive actual monotonic time. It does not feed synthetic fixed-step timestamps to application code. Use application-level delta clamping or fixed-step simulation when a scene must tolerate rare long pauses without advancing physics or animation by the full wall-clock gap.

The frame gate also controls event polling. If a paced frame is not due yet, drawWindow() returns before polling events, running the render callback, or swapping buffers. This keeps the hot idle scheduler from polling native window events thousands of times per second.

The window refresh rate used by the frame gate is sampled at window creation and updated when the window moves, resizes, or changes mode.

The first window creates an additional invisible root-window for context sharing (so that you can also close any window and still keep the root context). The platform context (pointers/handles) for sharing may be obtained when necessary.

See ts/window.ts for more details.

Legacy Window remains available as a subclass with requestAnimationFrame and cancelAnimationFrame. New browser-style code should use BrowserWindow from @node-3d/core.

Use examples/perf.ts with --scheduler=idle or --scheduler=immediate when comparing visual frame pacing behavior.

---

Legacy class Document

import { Document } from '@node-3d/glfw';

const doc = new Document({ title: 'GLFW Test', vsync: true });

Document inherits from legacy Window and has the same features in general. It exposes additional APIs to mimic the content of web document. There are some tricks to provide WebGL libraries with necessary environment. Document is kept for compatibility; new browser-style code should use BrowserDocument from @node-3d/core. Other web libraries may work too, but may require additional tweaking.

See ts/document.ts for more details.

---

Events

Keyboard events are normalized toward browser-style fields. GLFW key events keep their native which value available through the raw event path, while GlfwWindow normalizes common fields such as key, code, keyCode, and which so browser-oriented input code can handle keys like WASD and shortcuts without GLFW-specific key constants.

---

Extras

• glfw.hideConsole(): void - tries to hide the console window on Windows.
• glfw.showConsole(): void - shows the console window if it has been hidden.
• glfw.drawWindow(w: number, cb: (timestamp: number) => void): void - draws one frame when the window's pacing state allows it. Unpaced windows call pollEvents, then cb, then swapBuffers on every invocation. Paced windows can return before those steps when the next frame is not due. GlfwWindow#drawWindow wraps this call and supplies the window handle for you. timestamp is the actual monotonic callback time, including for paced non-zero swap intervals.
• glfw.platformDevice(): number - returns the native display or device handle, or whatever is similar on other systems.
• glfw.platformWindow(w: number): number - returns the window HWND on Windows, or whatever is similar on other systems.
• glfw.platformContext(w: number): number - returns the window WGL Context on Windows, or whatever is similar on other systems.

Binary Origin

Release archives are built by this repository's public GitHub Actions workflows.

Attestations: https://github.com/node-3d/glfw/attestations

To verify a downloaded archive:

gh release download <tag> -R node-3d/glfw -p <platform>.gz
gh attestation verify <platform>.gz -R node-3d/glfw