# bun-ffi

Guides agents on loading native C and C++ shared libraries in Bun using bun:ffi, pointer utilities, and type signatures.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 386 installs · ★ 237
- Author: secondsky
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/secondsky/claude-skills/tree/HEAD/plugins/bun/skills/bun-ffi/SKILL.md
- Updated: 2026-10-20
- HTML: https://affpapa.org/en/nevibecode/skills/bun-ffi

## What it does

The skill provides reference patterns for Bun's built-in `bun:ffi` interface. It instructs the assistant on using `dlopen` with platform-aware shared library extensions such as `.dylib`, `.so`, and `.dll`. The reference also details primitive mappings in `FFIType`, covering fixed-width integers, floating-point numbers, and raw pointers.

Code recipes cover null-terminated strings, converting native pointers back into strings via `CString`, and reading binary memory buffers. It also details passing JavaScript functions into native libraries with `callback`. Structs are assembled manually using `ArrayBuffer` and `DataView`.

Native calls block the main thread. Heavy computations must run inside Web Workers to keep the runtime responsive. Memory allocated by C routines requires explicit cleanup, since the JavaScript garbage collector cannot track it.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add secondsky/claude-skills --skill bun-ffi -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/bun-ffi/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/bun-ffi/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add secondsky/claude-skills --skill bun-ffi -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/bun-ffi/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add secondsky/claude-skills --skill bun-ffi -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/bun-ffi/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install secondsky/claude-skills bun-ffi
```

2. **Manually: put the files in place**
- File: `.github/skills/bun-ffi/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add secondsky/claude-skills --skill bun-ffi -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/secondsky/claude-skills --path plugins/bun/skills/bun-ffi
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/bun-ffi/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add secondsky/claude-skills --skill bun-ffi -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/secondsky/claude-skills/tree/HEAD/plugins/bun/skills/bun-ffi/SKILL.md

## When to use it
- Load system and third-party shared libraries using `dlopen` across operating systems
- Declare C function signatures with argument and return specifications from `FFIType`
- Send null-terminated strings and decode native string pointers with `CString`
- Pack binary struct layouts in `ArrayBuffer` instances using `DataView`
- Pass JavaScript functions to C APIs using the `callback` helper

## Example prompts
- Show me how to load `libsqlite3` in Bun using `bun:ffi` to execute a query.
- Help me pack a two-integer C struct into an `ArrayBuffer` for `bun:ffi`.
- Wrap a C array sorting function with a custom JavaScript comparison `callback`.

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: eccc593ce45f820f.

BEGIN THIRD-PARTY FILE eccc593ce45f820f
````text
---
name: bun-ffi
description: "This skill should be used when the user asks about \"bun:ffi\", \"foreign function interface\", \"calling C from Bun\", \"native libraries\", \"dlopen\", \"shared libraries\", \"calling native code\", or integrating C/C++ libraries with Bun."
metadata:
  version: "1.0.0"
license: MIT
---

# Bun FFI

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

## Quick Start

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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
````
END THIRD-PARTY FILE eccc593ce45f820f

The third-party file has ended. Everything between the eccc593ce45f820f tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2792 of 7320 bytes. © secondsky · MIT · https://github.com/secondsky/claude-skills/tree/HEAD/plugins/bun/skills/bun-ffi/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md