npx skills add jasnell/node-skills --skill node-ffiSKILL.md
node:ffi: call native libraries without an addon
| Feature | Versions | Stability | Flag |
|---|---|---|---|
node:ffi (dlopen, DynamicLibrary, memory helpers) |
v26.1.0 | 1 | none; --no-experimental-ffi disables |
--allow-ffi (permission model) |
v26.1.0 | 1.1 | with --permission |
getCurrentEventLoop() |
v26.6.0 | 1 | none |
dlopen of a path inside a mounted node:vfs |
v26.10.0 | 1 | none |
library.toFunction() |
main only (no YAML; absent in v26.13.0) | 1 | none |
Not on v24. Present only in builds with FFI support (the official v26 builds
have it). Importing it emits an ExperimentalWarning.
Experimental API. Before relying on these details, run the
node-experimental-checkskill's probe (ornode --versionplus a feature-detect one-liner) and check the docs for the installed version:https://nodejs.org/docs/<version>/api/<module>.html. If the installed version disagrees with this skill, the installed version wins.
Call a C function
import { dlopen } from 'node:ffi';
{
using h = dlopen('libc.so.6', { // Linux glibc; NOT 'libc.so' (linker script)
strlen: { arguments: ['string'], return: 'uint64' },
abs: { arguments: ['int32'], return: 'int32' },
});
h.functions.strlen('héllo'); // 6n: 64-bit returns are always bigint
h.functions.abs(-5); // 5
} // library closed here
dlopen(null, …) resolves from the process image (not on Windows). Build
names portably with `libfoo.${ffi.suffix}` (so/dylib/dll).
Pointers and callbacks
const p = malloc(16); // 'pointer' returns are bigint
ffi.exportString('hi', p, 16); ffi.toString(p); free(p);
const cmp = lib.registerCallback({ arguments: ['pointer','pointer'], return: 'int32' },
(a, b) => ffi.getInt32(a) - ffi.getInt32(b));
qsort(int32Array, n, 4, cmp); lib.unregisterCallback(cmp);
Pitfalls
- No coercion:
abs(1.5),abs('5'),abs(5n)andbooltruethrowERR_INVALID_ARG_VALUE. Pass0/1forbool. - A
'string'return is a bigint pointer. Decode it withffi.toString(). - Wrong signatures are not detected. Declaring
boolfor a Cinttruncates it, and a wrong pointer crashes the process. - A callback that throws aborts the process. Callbacks must be sync and
run on the creating thread. A
'function'argument needs aregisterCallbackpointer, not a JS function. - Calls are synchronous on the JS thread. A slow C call blocks the event loop.
toBuffer(p, n, false)views andgetRawPointer()dangle afterfree()or GC.process.permission.drop('ffi')does not stop calls orgetFunction()on an already-open library. Only new libraries,toFunction, and memory helpers are denied.- No structs by value, no calling-convention choice, fixed signatures only.
Don't
- Don't install
ffi-napi,node-ffi,ref-napiorkoffifor simple calls on 26.1+. - Don't write a C++ addon just to call one C function.
- Do still use Node-API/an addon when you need structs by value, threadpool work, native objects, v24 support, or a vetted safe API.
Reference
- rules/api.md: read for type names, every DynamicLibrary method, callbacks' lifetime rules, and memory helpers.
- rules/call-paths-safety.md: read for performance (Fast API/shared-buffer/generic paths, arg limits), permissions, and the full safety list.