Get started#

Install Koffi#

You can install Koffi with npm:

1npm install koffi

Once you have installed Koffi, you can start by loading it:

1// CommonJS syntax
2const koffi = require('koffi');
4// ES6 modules
5import koffi from 'koffi';

Simple examples#

Below you can find two examples:

  • The first one runs on Linux. The functions are declared with the C-like prototype language.

  • The second one runs on Windows, and uses the node-ffi like syntax to declare functions.

For Linux#

This is a small example for Linux systems, which uses gettimeofday(), localtime_r() and printf() to print the current time.

It illustrates the use of output parameters.

 1// ES6 syntax: import koffi from 'koffi';
 2const koffi = require('koffi');
 4// Load the shared library
 5const lib = koffi.load('');
 7// Declare struct types
 8const timeval = koffi.struct('timeval', {
 9    tv_sec: 'unsigned int',
10    tv_usec: 'unsigned int'
12const timezone = koffi.struct('timezone', {
13    tz_minuteswest: 'int',
14    tz_dsttime: 'int'
16const time_t = koffi.struct('time_t', { value: 'int64_t' });
17const tm = koffi.struct('tm', {
18    tm_sec: 'int',
19    tm_min: 'int',
20    tm_hour: 'int',
21    tm_mday: 'int',
22    tm_mon: 'int',
23    tm_year: 'int',
24    tm_wday: 'int',
25    tm_yday: 'int',
26    tm_isdst: 'int'
29// Find functions
30const gettimeofday = lib.func('int gettimeofday(_Out_ timeval *tv, _Out_ timezone *tz)');
31const localtime_r = lib.func('tm *localtime_r(const time_t *timeval, _Out_ tm *result)');
32const printf = lib.func('int printf(const char *format, ...)');
34// Get local time
35let tv = {};
36let now = {};
37gettimeofday(tv, null);
38localtime_r({ value: tv.tv_sec }, now);
40// And format it with printf (variadic function)
41printf('Hello World!\n');
42printf('Local time: %02d:%02d:%02d\n', 'int', now.tm_hour, 'int', now.tm_min, 'int', now.tm_sec);

For Windows#

This is a small example targeting the Win32 API, using MessageBox() to show a Hello World! message to the user.

It illustrates the use of the x86 stdcall calling convention, and the use of UTF-8 and UTF-16 string arguments.

 1// ES6 syntax: import koffi from 'koffi';
 2const koffi = require('koffi');
 4// Load the shared library
 5const lib = koffi.load('user32.dll');
 7// Declare constants
 8const MB_OK = 0x0;
 9const MB_YESNO = 0x4;
10const MB_ICONQUESTION = 0x20;
11const MB_ICONINFORMATION = 0x40;
12const IDOK = 1;
13const IDYES = 6;
14const IDNO = 7;
16// Find functions
17const MessageBoxA = lib.func('__stdcall', 'MessageBoxA', 'int', ['void *', 'str', 'str', 'uint']);
18const MessageBoxW = lib.func('__stdcall', 'MessageBoxW', 'int', ['void *', 'str16', 'str16', 'uint']);
20let ret = MessageBoxA(null, 'Do you want another message box?', 'Koffi', MB_YESNO | MB_ICONQUESTION);
21if (ret == IDYES)
22    MessageBoxW(null, 'Hello World!', 'Koffi', MB_ICONINFORMATION);

Bundling Koffi#

Please read the dedicated page for information about bundling and packaging applications using Koffi.

Build manually#

Follow the build instrutions if you want to build the native Koffi code yourself.


This is only needed if you want to hack on Koffi. The official NPM package provide prebuilt binaries and you don’t need to compile anything if you only want to use Koffi in Node.js.