Foreign Function Interface (FFI)

Deno's Foreign Function Interface (FFI) allows JavaScript and TypeScript code to call functions in dynamic libraries written in languages like C, C++, or Rust. This enables you to integrate native code performance and capabilities directly into your Deno applications.

Deno FFI Reference Docs

Introduction to FFI

FFI provides a bridge between Deno's JavaScript runtime and native code. This allows you to:

• Use existing native libraries within your Deno applications
• Implement performance-critical code in languages like Rust or C
• Access operating system APIs and hardware features not directly available in JavaScript

Deno's FFI implementation is based on the Deno.dlopen API, which loads dynamic libraries and creates JavaScript bindings to the functions they export.

Security considerations

FFI requires explicit permission using the --allow-ffi flag, as native code runs outside of Deno's security sandbox:

deno run --allow-ffi my_ffi_script.ts

:::info

⚠️ Important security warning: Unlike JavaScript code running in the Deno sandbox, native libraries loaded via FFI have the same access level as the Deno process itself. This means they can:

• Access the filesystem
• Make network connections
• Access environment variables
• Execute system commands

Always ensure you trust the native libraries you're loading through FFI.

:::

Basic usage

The basic pattern for using FFI in Deno involves:

1. Defining the interface for the native functions you want to call
2. Loading the dynamic library using Deno.dlopen()
3. Calling the loaded functions

Here's a simple example loading a C library:

const dylib = Deno.dlopen("libexample.so", {
  add: { parameters: ["i32", "i32"], result: "i32" },
});

console.log(dylib.symbols.add(5, 3)); // 8

dylib.close();

Supported types

Deno's FFI supports a variety of data types for parameters and return values:

FFI Type	Deno	C	Rust
i8	number	char / signed char	i8
u8	number	unsigned char	u8
i16	number	short int	i16
u16	number	unsigned short int	u16
i32	number	int / signed int	i32
u32	number	unsigned int	u32
i64	bigint	long long int	i64
u64	bigint	unsigned long long int	u64
usize	bigint	size_t	usize
isize	bigint	size_t	isize
f32	number	float	f32
f64	number	double	f64
void[1]	undefined	void	()
pointer	{} | null	void *	*mut c_void
buffer[2]	TypedArray | null	uint8_t *	*mut u8
function[3]	{} | null	void (*fun)()	Option<extern "C" fn()>
{ struct: [...] }[4]	TypedArray	struct MyStruct	MyStruct

Working with structs

You can define and use C structures in your FFI code:

// Define a struct type for a Point
const pointStruct = {
  fields: {
    x: "f64",
    y: "f64",
  },
} as const;

// Define the library interface
const signatures = {
  distance: {
    parameters: [
      { struct: pointStruct },
      { struct: pointStruct },
    ],
    result: "f64",
  },
} as const;

// Create struct instances
const point1 = new Deno.UnsafePointer(
  new BigUint64Array([
    BigInt(Float64Array.of(1.0).buffer),
    BigInt(Float64Array.of(2.0).buffer),
  ]).buffer,
);

const point2 = new Deno.UnsafePointer(
  new BigUint64Array([
    BigInt(Float64Array.of(4.0).buffer),
    BigInt(Float64Array.of(6.0).buffer),
  ]).buffer,
);

// Call the function with structs
const dist = dylib.symbols.distance(point1, point2);

Working with callbacks

You can pass JavaScript functions as callbacks to native code:

const signatures = {
  setCallback: {
    parameters: ["function"],
    result: "void",
  },
  runCallback: {
    parameters: [],
    result: "void",
  },
} as const;

// Create a callback function
const callback = new Deno.UnsafeCallback(
  { parameters: ["i32"], result: "void" } as const,
  (value) => {
    console.log("Callback received:", value);
  },
);

// Pass the callback to the native library
dylib.symbols.setCallback(callback.pointer);

// Later, this will trigger our JavaScript function
dylib.symbols.runCallback();

// Always clean up when done
callback.close();

Best practices with FFI

1. Always close resources. Close libraries with dylib.close() and callbacks with callback.close() when done.

2. Prefer TypeScript. Use TypeScript for better type-checking when working with FFI.

3. Wrap FFI calls in try/catch blocks to handle errors gracefully.

4. Be extremely careful when using FFI, as native code can bypass Deno's security sandbox.

5. Keep the FFI interface as small as possible to reduce the attack surface.

Examples

Using a Rust library

Here's an example of creating and using a Rust library with Deno:

First, create a Rust library:

// lib.rs
#[no_mangle]
pub extern "C" fn fibonacci(n: u32) -> u32 {
  if n <= 1 {
    return n;
  }
  fibonacci(n - 1) + fibonacci(n - 2)
}

Compile it as a dynamic library:

rustc --crate-type cdylib lib.rs

Then use it from Deno:

const libName = {
  windows: "./lib.dll",
  linux: "./liblib.so",
  darwin: "./liblib.dylib",
}[Deno.build.os];

const dylib = Deno.dlopen(
  libName,
  {
    fibonacci: { parameters: ["u32"], result: "u32" },
  } as const,
);

// Calculate the 10th Fibonacci number
const result = dylib.symbols.fibonacci(10);
console.log(`Fibonacci(10) = ${result}`); // 55

dylib.close();

Examples

• Netsaur
• WebView_deno
• Deno_sdl2
• Deno FFI examples repository

These community-maintained repos includes working examples of FFI integrations with various native libraries across different operating systems.

Related Approaches to Native Code Integration

While Deno's FFI provides a direct way to call native functions, there are other approaches to integrate native code:

Using Node-API (N-API) with Deno

Deno supports Node-API (N-API) for compatibility with native Node.js addons. This enables you to use existing native modules written for Node.js.

Directly loading a Node-API addon:

import process from "node:process";
process.dlopen(module, "./native_module.node", 0);

Using an npm package that uses a Node-API addon:

import someNativeAddon from "npm:some-native-addon";
console.log(someNativeAddon.doSomething());

How is this different from FFI?

Aspect	FFI	Node-API Support
Setup	No build step required	Requires precompiled binaries or build step
Portability	Tied to library ABI	ABI-stable across versions
Use Case	Direct library calls	Reuse Node.js addons

Node-API support is ideal for leveraging existing Node.js native modules, whereas FFI is best for direct, lightweight calls to native libraries.

Alternatives to FFI

Before using FFI, consider these alternatives:

• WebAssembly, for portable native code that runs within Deno's sandbox.
• Use Deno.run to execute external binaries and subprocesses with controlled permissions.
• Check whether Deno's native APIs already provide the functionality you need.

Deno's FFI capabilities provide powerful integration with native code, enabling performance optimizations and access to system-level functionality. However, this power comes with significant security considerations. Always be cautious when working with FFI and ensure you trust the native libraries you're using.