Bun FFI

Bun's FFI allows calling native C/C++ libraries from JavaScript.

Quick Start

import { dlopen, suffix, FFIType } from "bun:ffi";

// Load library const lib = dlopen(libc.${suffix}, { printf: { args: [FFIType.cstring], returns: FFIType.int, }, });

// Call function lib.symbols.printf("Hello from C!\n");

Loading Libraries

Platform-Specific Paths

import { dlopen, suffix } from "bun:ffi";

// suffix is: "dylib" (macOS), "so" (Linux), "dll" (Windows)

// System library const libc = dlopen(libc.${suffix}, { ... });

// Custom library const myLib = dlopen(./libmylib.${suffix}, { ... });

// Absolute path const sqlite = dlopen("/usr/lib/libsqlite3.so", { ... });

Cross-Platform Loading

function getLibPath(name: string): string { const platform = process.platform; const paths = { darwin: /usr/local/lib/lib${name}.dylib, linux: /usr/lib/lib${name}.so, win32: C:\\Windows\\System32\\${name}.dll, }; return paths[platform] || paths.linux; }

const lib = dlopen(getLibPath("mylib"), { ... });

FFI Types

import { FFIType } from "bun:ffi";

const types = { // Integers i8: FFIType.i8, // int8_t i16: FFIType.i16, // int16_t i32: FFIType.i32, // int32_t / int i64: FFIType.i64, // int64_t / long long

// Unsigned integers u8: FFIType.u8, // uint8_t u16: FFIType.u16, // uint16_t u32: FFIType.u32, // uint32_t u64: FFIType.u64, // uint64_t

// Floats f32: FFIType.f32, // float f64: FFIType.f64, // double

// Pointers ptr: FFIType.ptr, // void* cstring: FFIType.cstring, // const char*

// Other bool: FFIType.bool, // bool void: FFIType.void, // void };

Function Definitions

import { dlopen, FFIType, ptr, CString } from "bun:ffi";

const lib = dlopen("./libmath.so", { // Simple function add: { args: [FFIType.i32, FFIType.i32], returns: FFIType.i32, },

// String function greet: { args: [FFIType.cstring], returns: FFIType.cstring, },

// Pointer function allocate: { args: [FFIType.u64], returns: FFIType.ptr, },

// Void function log_message: { args: [FFIType.cstring], returns: FFIType.void, },

// No args get_version: { args: [], returns: FFIType.cstring, }, });

// Call functions const sum = lib.symbols.add(1, 2); // 3 const message = lib.symbols.greet(ptr(Buffer.from("World\0")));

Working with Strings

import { dlopen, FFIType, ptr, CString } from "bun:ffi";

// Passing strings to C const str = Buffer.from("Hello\0"); // Must be null-terminated lib.symbols.print_string(ptr(str));

// Receiving strings from C const result = lib.symbols.get_string(); const jsString = new CString(result); // Convert to JS string console.log(jsString.toString());

Working with Pointers

import { dlopen, FFIType, ptr, toArrayBuffer } from "bun:ffi";

const lib = dlopen("./libdata.so", { create_buffer: { args: [FFIType.u64], returns: FFIType.ptr, }, fill_buffer: { args: [FFIType.ptr, FFIType.u8, FFIType.u64], returns: FFIType.void, }, free_buffer: { args: [FFIType.ptr], returns: FFIType.void, }, });

// Allocate buffer const size = 1024; const bufPtr = lib.symbols.create_buffer(size);

// Fill buffer lib.symbols.fill_buffer(bufPtr, 0xff, size);

// Read buffer as ArrayBuffer const arrayBuffer = toArrayBuffer(bufPtr, 0, size); const view = new Uint8Array(arrayBuffer); console.log(view); // [255, 255, 255, ...]

// Free buffer lib.symbols.free_buffer(bufPtr);

Structs

import { dlopen, FFIType, ptr } from "bun:ffi";

// C struct: // struct Point { int32_t x; int32_t y; };

const lib = dlopen("./libgeom.so", { create_point: { args: [FFIType.i32, FFIType.i32], returns: FFIType.ptr, // Returns Point* }, get_distance: { args: [FFIType.ptr, FFIType.ptr], returns: FFIType.f64, }, });

// Create struct manually const point = new ArrayBuffer(8); // 2 x int32 const view = new DataView(point); view.setInt32(0, 10, true); // x = 10 view.setInt32(4, 20, true); // y = 20

// Pass to C lib.symbols.get_distance(ptr(point), ptr(point));

Callbacks

import { dlopen, FFIType, callback } from "bun:ffi";

const lib = dlopen("./libsort.so", { sort_array: { args: [FFIType.ptr, FFIType.u64, FFIType.ptr], // callback returns: FFIType.void, }, });

// Create callback const compareCallback = callback( { args: [FFIType.ptr, FFIType.ptr], returns: FFIType.i32, }, (a, b) => { const aVal = new DataView(toArrayBuffer(a, 0, 4)).getInt32(0, true); const bVal = new DataView(toArrayBuffer(b, 0, 4)).getInt32(0, true); return aVal - bVal; } );

// Use callback lib.symbols.sort_array(arrayPtr, length, compareCallback.ptr);

// Close callback when done compareCallback.close();

Example: SQLite

import { dlopen, FFIType, ptr, CString } from "bun:ffi";

const sqlite = dlopen("libsqlite3.dylib", { sqlite3_open: { args: [FFIType.cstring, FFIType.ptr], returns: FFIType.i32, }, sqlite3_exec: { args: [FFIType.ptr, FFIType.cstring, FFIType.ptr, FFIType.ptr, FFIType.ptr], returns: FFIType.i32, }, sqlite3_close: { args: [FFIType.ptr], returns: FFIType.i32, }, });

// Open database const dbPtrArray = new BigInt64Array(1); const dbPath = Buffer.from("test.db\0"); sqlite.symbols.sqlite3_open(ptr(dbPath), ptr(dbPtrArray)); const db = dbPtrArray[0];

// Execute query const sql = Buffer.from("CREATE TABLE test (id INTEGER);\0"); sqlite.symbols.sqlite3_exec(db, ptr(sql), null, null, null);

// Close sqlite.symbols.sqlite3_close(db);

Memory Management

// Manual allocation const buffer = new ArrayBuffer(1024); const pointer = ptr(buffer);

// Buffer stays valid as long as ArrayBuffer exists // JavaScript GC will clean up ArrayBuffer

// For C-allocated memory, call C's free function lib.symbols.free(cPointer);

Thread Safety

// FFI calls are synchronous and block the main thread // For long-running operations, use Web Workers:

// worker.ts import { dlopen } from "bun:ffi"; const lib = dlopen(...);

self.onmessage = (e) => { const result = lib.symbols.expensive_operation(e.data); self.postMessage(result); };

Common Errors

Error Cause Fix

Library not found

Wrong path Check library path

Symbol not found

Wrong function name Check function export

Type mismatch

Wrong FFI types Match C types exactly

Segmentation fault

Memory error Check pointer validity

When to Load References

Load references/type-mappings.md when:

• Complex type conversions

• Struct layouts

• Union types

Load references/performance.md when:

• Optimizing FFI calls

• Batching operations

• Memory pooling