node-lua-runner

Embed Lua 5.1 in your Node.js programs.

Lua and LuaFileSystem are compiled directly into the addon, so there is no system Lua to install and nothing to configure — npm install builds everything from source on Linux, macOS and Windows, on both x64 and ARM64.

• Installation
• Quick start
• Documentation
• Examples
• How it works
• Caveats
• License

Installation

npm install node-lua-runner

The addon is compiled at install time, so you need a working C/C++ toolchain:

• Linux — build-essential (or your distribution's equivalent) and Python 3
• macOS — the Xcode Command Line Tools (xcode-select --install)
• Windows — the "Desktop development with C++" workload from Visual Studio Build Tools

Nothing else. Node.js 18 or newer.

If the install fails, see troubleshooting — the common ones are Visual Studio 2026 on Windows and npm 12 blocking build scripts.

Quick start

const nodelua = require('node-lua-runner');

const lua = new nodelua.LuaState();

lua.DoString('print("Hello from Lua!")');

// Expose a JavaScript function to Lua
lua.RegisterFunction('add', function () {
	const a = lua.ToValue(1);
	const b = lua.ToValue(2);
	lua.Pop(2);
	lua.Push(a + b);
	return 1;
});

lua.DoString('print("2 + 3 = " .. add(2, 3))');

lua.Close();

Documentation

• API reference — every method, type conversion, and how stack indices behave
• Migrating to 2.0 — what changed and what to check in existing code
• Troubleshooting — build and install problems
• Development — layout, CI, and how releases are cut
• Changelog

Examples

• Simple — running code, registering a JavaScript function, reading globals
• Using require — loading Lua modules from disk
• Using LuaFileSystem

How it works

Built on the Lua 5.1 C API through Node-API, which is ABI-stable — a compiled build keeps working across future Node.js releases instead of breaking on each major version.

The API is low-level and maps closely onto the C API, and it is synchronous throughout.

Descended from NodeLua and node-luajit.

Caveats

This is a thin wrapper over the Lua C API, and it does not shield you from every way of misusing it. Some stack operations on a value of an unexpected type raise an unprotected Lua error, which aborts the process rather than throwing a JavaScript exception. SetField and GetField guard against this; other methods do not. Keep track of what is on the stack — see stack indices.

License

ISC — see LICENSE. The vendored Lua and LuaFileSystem sources are MIT; their notices are in THIRD-PARTY-NOTICES.md.