| name | bun-ffi |
| description | Build a complete, correct Rust↔Bun FFI bridge for ANY Rust project: a `cdylib` crate exposing `extern "C"` functions that Bun loads with `bun:ffi` (`dlopen`/`cc`/`JSCallback`). Use this skill whenever the user wants to call Rust from Bun/JavaScript, "bind a Rust crate to Bun", "expose Rust to bun:ffi", pass strings/structs/buffers/callbacks across the Rust↔JS boundary, generate the TypeScript `dlopen` bindings for a native library, or debug FFI crashes (segfaults, wrong values, memory corruption) when using bun:ffi — even if they just say "I want my Rust function callable from Bun" without naming FFI. |
| metadata | {"version":"1.0.0","keywords":["bun","ffi","rust","cdylib","dlopen","JSCallback","native","FFIType","n-api"]} |
bun-ffi — Rust ↔ Bun FFI bridge
Build the binding layer that lets Bun call into a native Rust library and back.
The target is a Rust cdylib (.so/.dylib/.dll) whose extern "C" symbols
Bun loads via bun:ffi's dlopen, plus the TypeScript wrapper that declares
each symbol's signature and converts values.
Bun's FFI is not generic libffi — for every symbol you declare, Bun JIT‑compiles
a bespoke C trampoline (via embedded TinyCC) that reads JS arguments directly out
of the JSC call frame, bit‑casts them to native C types, calls your symbol, and
bit‑casts the return back to a JSValue. That is why it's fast, and why the
declared signature must exactly match the Rust ABI — a mismatch is a
hard‑to‑debug crash, not a type error.
When bun:ffi is the right tool
bun:ffi is best for prototyping and self‑contained numeric/buffer APIs: fast
to set up, no build step beyond , no codegen. Reach for instead when you need: rich JS object graphs, async work
that integrates with the event loop, exceptions that propagate as JS errors,
production stability (Bun's docs label "experimental"), or the same
addon to also run on Node. This skill covers ; for the N‑API path and a
decision matrix, point the user at the skill. For turning the
result into a publishable, multi‑platform package, see .
