DEV Community: Rahul Garg

React Native JSI Deep Dive — Part 4: Your First React Native JSI Function

Rahul Garg — Mon, 23 Mar 2026 05:48:30 +0000

"Simplicity is prerequisite for reliability." — Edsger W. Dijkstra, How Do We Tell Truths That Might Hurt?, 1975

Excerpt: A JSI function is a C++ lambda disguised as a JavaScript function. No serialization, no bridge, no codegen — just a C++ callable that the runtime invokes directly. This post walks you through writing one from scratch: registering it with the runtime, reading arguments, validating types, handling errors, and calling it from JavaScript. By the end, you'll have a working native module with zero boilerplate.

Series: React Native JSI Deep Dive (12 parts — series in progress) Part 1: React Native Architecture — Threads, Hermes, and the Event Loop | Part 2: React Native Bridge vs JSI — What Changed and Why | Part 3: C++ for JavaScript Developers | Part 4: Your First React Native JSI Function (You are here) | Part 5: HostObjects — Exposing C++ Classes to JavaScript | Part 6: Memory Ownership | Part 7: Platform Wiring | Part 8: Threading & Async | Part 9: Real-Time Audio in React Native — Lock-Free Pipelines with JSI | Part 10: Storage Engine | Part 11: Module Approaches | Part 12: Debugging

Quick Recap

In Part 2, we saw that JSI replaces the JSON bridge with direct C++ function calls — no serialization, no async queue. In Part 3, we learned the C++ vocabulary: references (&), pointers (*), RAII, smart pointers, lambdas with explicit captures.

Now we use all of it. This post is where you write your first line of native module code.

Installing Native Functions in the JavaScript Runtime

In a web browser, you can add JavaScript functions to the global scope (window.myFunc = ...), but you can't install native functions — functions implemented in C++ that execute without the JavaScript engine interpreting them. The browser's native API surface (fetch, setTimeout, the DOM) is fixed by the browser vendor.

In React Native, you can. JSI lets you install C++ functions directly into the JavaScript runtime. From JavaScript's perspective, they're indistinguishable from any other function. From C++'s perspective, they're lambdas that receive the runtime and arguments — executed natively, not interpreted.

The primary API for doing this is one function: jsi::Function::createFromHostFunction. (You can also create callable functions via HostObject or evaluateJavaScript, but createFromHostFunction is the dedicated, purpose-built API for registering C++ functions.)

Step 1: The Simplest Possible JSI Function

Let's start with the absolute minimum — a function that takes no arguments and returns a number:

cpp/install.cpp — the seed

#include <jsi/jsi.h>

using namespace facebook;

void install(jsi::Runtime& rt) {
    auto fn = jsi::Function::createFromHostFunction(
        rt,                                         // 1. the runtime
        jsi::PropNameID::forAscii(rt, "getFortyTwo"), // 2. function name (for stack traces)
        0,                                          // 3. expected argument count
        [](jsi::Runtime& rt,                        // 4. the lambda
           const jsi::Value& thisVal,
           const jsi::Value* args,
           size_t count) -> jsi::Value {
            return jsi::Value(42);
        }
    );

    rt.global().setProperty(rt, "getFortyTwo", std::move(fn));
}

App.js — calling it

const n = getFortyTwo();
console.log(n); // 42

output

Four things happen in createFromHostFunction:

rt — the runtime instance. Every JSI call needs this — it's the handle to the JavaScript world.
PropNameID::forAscii(rt, "getFortyTwo") — the function's name. This shows up in error stack traces. It doesn't determine where the function is installed — that's setProperty's job.
0 — the expected argument count. This is informational (the JS .length property) — the runtime doesn't enforce it.
The lambda — the actual C++ code that runs when JavaScript calls the function. It receives the runtime, this value, a pointer to the arguments array, and the argument count.

The last line — rt.global().setProperty(...) — installs the function on the JavaScript global object. After this call, any JavaScript code can call getFortyTwo().

Key Insight: The function name passed to PropNameID and the property name passed to setProperty are independent. You could name the function "internalMathOp" for stack traces but install it as global.getFortyTwo. In practice, keep them the same to avoid confusion.

Step 2: Reading Arguments

A function that ignores its arguments isn't very useful. Let's add two numbers:

cpp/install.cpp — reading arguments ⚠️ no validation yet

void install(jsi::Runtime& rt) {
    auto add = jsi::Function::createFromHostFunction(
        rt,
        jsi::PropNameID::forAscii(rt, "nativeAdd"),
        2,  // expects 2 arguments
        [](jsi::Runtime& rt,
           const jsi::Value& thisVal,
           const jsi::Value* args,
           size_t count) -> jsi::Value {
            double a = args[0].asNumber();  // ← read first argument as double
            double b = args[1].asNumber();  // ← read second argument
            return jsi::Value(a + b);
        }
    );

    rt.global().setProperty(rt, "nativeAdd", std::move(add));
}

App.js

console.log(nativeAdd(3, 7));    // 10
console.log(nativeAdd(1.5, 2.5)); // 4

output

10
4

The args parameter is a pointer to an array of jsi::Value objects (as we learned in Part 3 — C-style array passing). args[0] is the first argument, args[1] is the second. The count parameter tells you how many were actually passed.

Gotcha: This code is deliberately unvalidated to keep it simple — don't ship this pattern. If JavaScript calls nativeAdd(5) with only one argument, args[1] accesses past the end of the arguments array. That's undefined behavior in C++ — it may crash, corrupt memory, or silently produce garbage. Step 3 fixes this with proper count validation. Always check count before indexing into args.

asNumber() converts a jsi::Value to a C++ double. But what happens if JavaScript passes a string instead of a number?

Think about it: What does nativeAdd("hello", 7) do? The args[0].asNumber() call encounters a string. Does it return NaN? Does it throw? Does it crash?

It throws a C++ exception that the JSI runtime catches and converts into a JavaScript Error — catchable with try/catch on the JS side. The app doesn't crash, but the call fails with a generic error message like "expected a number." This is better than silently returning garbage, but we should validate arguments explicitly rather than relying on the conversion to throw — both for better error messages and for safety (see the Gotcha below about missing arguments).

Step 3: Validating Arguments

Production JSI functions must validate their inputs. The jsi::Value type provides type-checking methods: isNumber(), isString(), isObject(), isUndefined(), isNull(), isBool(), isSymbol(), and isBigInt().

cpp/install.cpp — with argument validation

void install(jsi::Runtime& rt) {
    auto add = jsi::Function::createFromHostFunction(
        rt,
        jsi::PropNameID::forAscii(rt, "nativeAdd"),
        2,
        [](jsi::Runtime& rt,
           const jsi::Value& thisVal,
           const jsi::Value* args,
           size_t count) -> jsi::Value {
            // Validate argument count
            if (count < 2) {                                       // ← NEW
                throw jsi::JSError(rt, "nativeAdd requires 2 arguments");
            }

            // Validate argument types
            if (!args[0].isNumber() || !args[1].isNumber()) {      // ← NEW
                throw jsi::JSError(rt, "nativeAdd arguments must be numbers");
            }

            double a = args[0].asNumber();
            double b = args[1].asNumber();
            return jsi::Value(a + b);
        }
    );

    rt.global().setProperty(rt, "nativeAdd", std::move(add));
}

App.js — error handling

try {
    nativeAdd("hello", 7);
} catch (e) {
    console.log(e.message); // "nativeAdd arguments must be numbers"
}

try {
    nativeAdd(5);
} catch (e) {
    console.log(e.message); // "nativeAdd requires 2 arguments"
}

output

"nativeAdd arguments must be numbers"
"nativeAdd requires 2 arguments"

The pattern is always the same:

Check count — did JavaScript pass enough arguments?
Check types — are the arguments the right kind?
Throw jsi::JSError — if validation fails, this becomes a catchable JavaScript error.

Gotcha: Always validate before calling asNumber(), asString(), etc. These conversion methods throw a C++ exception on type mismatch (which the JSI runtime converts to a JS error), but the error message is generic ("Value is string, expected a number"). Your custom message — "nativeAdd arguments must be numbers" — is far more useful for debugging. More importantly, validate count before indexing into args — accessing args[i] when i >= count is undefined behavior that no exception handler can catch.

Step 4: Error Handling (jsi::JSError)

jsi::JSError is the bridge between C++ exceptions and JavaScript errors. When you throw a jsi::JSError inside a host function, it propagates back to JavaScript as a regular Error object — catchable with try/catch.

The JSI runtime does catch std::exception subclasses thrown from host functions and converts them into JavaScript errors (per the jsi.h documentation: "If a C++ exception is thrown, a JS Error will be created and thrown into JS; if the C++ exception extends std::exception, the Error's message will be whatever what() returns"). However, exceptions that don't extend std::exception, or undefined behavior that doesn't throw at all (like out-of-bounds array access), will crash the app. Relying on the runtime's catch-all is fragile — the error messages are generic, and non-exception UB isn't caught.

The robust pattern: wrap your native logic in a try/catch that gives you control over error messages and catches everything:

cpp/install.cpp — safe error boundary

[](jsi::Runtime& rt,
   const jsi::Value& thisVal,
   const jsi::Value* args,
   size_t count) -> jsi::Value {
    try {
        // Your native logic here
        auto result = someCppFunction(args[0].asNumber());
        return jsi::Value(result);
    } catch (const jsi::JSError&) {
        throw;  // already a JS error — let it propagate
    } catch (const std::exception& e) {
        throw jsi::JSError(rt, std::string("Native error: ") + e.what());
    } catch (...) {
        throw jsi::JSError(rt, "Unknown native error");
    }
}

This three-level catch ensures:

jsi::JSError passes through unchanged (it's already a JS error).
Standard C++ exceptions (std::runtime_error, std::invalid_argument, etc.) are wrapped with their error message.
Unknown exceptions get a generic fallback instead of crashing the app.

Key Insight: Every JSI host function is a boundary between two worlds. The JSI runtime handles std::exception subclasses automatically, but undefined behavior (dangling pointers, out-of-bounds access) bypasses all exception handling and crashes the app. The try/catch wrapper adds defense in depth: clearer error messages, a catch-all for non-standard exceptions, and explicit control over what JavaScript sees. Think of it as the native equivalent of a React error boundary.

The jsi::Value Type System

Before we build anything larger, let's understand the types you'll work with. jsi::Value is a tagged union — a single type that can hold any JavaScript value.

Reading Values (JS → C++)

JavaScript Type	Type Check	Conversion	C++ Type
`number`	`val.isNumber()`	`val.asNumber()`	`double`
`string`	`val.isString()`	`val.asString(rt)`	`jsi::String`
`boolean`	`val.isBool()`	`val.asBool()`	`bool`
`object`	`val.isObject()`	`val.asObject(rt)`	`jsi::Object`
`null`	`val.isNull()`	—	—
`undefined`	`val.isUndefined()`	—	—

Figure 1: jsi::Value type checks and conversions. Always check the type before converting.

Note the asymmetry: asNumber() doesn't take rt, but asString(rt) and asObject(rt) do. Numbers and booleans are plain C++ values (a double and a bool). Strings and objects are runtime-managed — they live inside the JS engine and need the runtime handle to access.

To get a std::string from a jsi::String, call .utf8(rt):

Reading a string argument

jsi::String jsStr = args[0].asString(rt);   // jsi::String (engine-managed)
std::string cppStr = jsStr.utf8(rt);         // std::string (C++-owned copy)

Creating Values (C++ → JS)

C++ Value	JSI Constructor	JavaScript Result
`42` or `3.14`	`jsi::Value(42)`	`number`
`true` / `false`	`jsi::Value(true)`	`boolean`
`"hello"`	`jsi::String::createFromUtf8(rt, "hello")`	`string`
—	`jsi::Value::null()`	`null`
—	`jsi::Value::undefined()`	`undefined`
—	`jsi::Object(rt)`	`{}` (empty object)

Figure 2: Creating JavaScript values from C++. Numbers and booleans wrap directly. Strings and objects need the runtime.

Returning different types

// Return a number
return jsi::Value(42);

// Return a string
return jsi::String::createFromUtf8(rt, "hello from C++");

// Return an object with properties
auto obj = jsi::Object(rt);
obj.setProperty(rt, "name", jsi::String::createFromUtf8(rt, "JSI"));
obj.setProperty(rt, "version", jsi::Value(4));
return obj;  // JS receives: { name: "JSI", version: 4 }

Putting It Together: A Math Module

Let's build something real — a small math module with multiple functions, installed as properties on a single object rather than polluting the global scope:

cpp/MathModule.cpp — complete module

#include <jsi/jsi.h>
#include <cmath>
#include <string>

using namespace facebook;

void installMathModule(jsi::Runtime& rt) {

    // Helper: validate that arg at index i is a number
    auto requireNumber = [](jsi::Runtime& rt,
                            const jsi::Value* args,
                            size_t count,
                            size_t index,
                            const char* fnName) {
        if (index >= count) {
            throw jsi::JSError(rt,
                std::string(fnName) + ": missing argument at index "
                + std::to_string(index));
        }
        if (!args[index].isNumber()) {
            throw jsi::JSError(rt,
                std::string(fnName) + ": argument " + std::to_string(index)
                + " must be a number");
        }
    };

    // --- add(a, b) ---
    auto add = jsi::Function::createFromHostFunction(
        rt, jsi::PropNameID::forAscii(rt, "add"), 2,
        [requireNumber](jsi::Runtime& rt, const jsi::Value&,
                        const jsi::Value* args, size_t count) -> jsi::Value {
            requireNumber(rt, args, count, 0, "add");
            requireNumber(rt, args, count, 1, "add");
            return jsi::Value(args[0].asNumber() + args[1].asNumber());
        }
    );

    // --- multiply(a, b) ---
    auto multiply = jsi::Function::createFromHostFunction(
        rt, jsi::PropNameID::forAscii(rt, "multiply"), 2,
        [requireNumber](jsi::Runtime& rt, const jsi::Value&,
                        const jsi::Value* args, size_t count) -> jsi::Value {
            requireNumber(rt, args, count, 0, "multiply");
            requireNumber(rt, args, count, 1, "multiply");
            return jsi::Value(args[0].asNumber() * args[1].asNumber());
        }
    );

    // --- sqrt(x) ---
    auto sqrt = jsi::Function::createFromHostFunction(
        rt, jsi::PropNameID::forAscii(rt, "sqrt"), 1,
        [requireNumber](jsi::Runtime& rt, const jsi::Value&,
                        const jsi::Value* args, size_t count) -> jsi::Value {
            requireNumber(rt, args, count, 0, "sqrt");
            double x = args[0].asNumber();
            if (x < 0) {
                throw jsi::JSError(rt, "sqrt: argument must be non-negative");
            }
            return jsi::Value(std::sqrt(x));
        }
    );

    // --- describe() — returns an object ---
    auto describe = jsi::Function::createFromHostFunction(
        rt, jsi::PropNameID::forAscii(rt, "describe"), 0,
        [](jsi::Runtime& rt, const jsi::Value&,
           const jsi::Value* args, size_t count) -> jsi::Value {
            auto obj = jsi::Object(rt);
            obj.setProperty(rt, "name",
                jsi::String::createFromUtf8(rt, "NativeMath"));
            obj.setProperty(rt, "version", jsi::Value(1));
            obj.setProperty(rt, "engine",
                jsi::String::createFromUtf8(rt, "JSI"));
            return obj;
        }
    );

    // Install all functions on a single object
    auto mathModule = jsi::Object(rt);
    mathModule.setProperty(rt, "add", std::move(add));
    mathModule.setProperty(rt, "multiply", std::move(multiply));
    mathModule.setProperty(rt, "sqrt", std::move(sqrt));
    mathModule.setProperty(rt, "describe", std::move(describe));

    rt.global().setProperty(rt, "NativeMath", std::move(mathModule));
}

App.js — using the module

console.log(NativeMath.add(3, 7));          // 10
console.log(NativeMath.multiply(6, 7));     // 42
console.log(NativeMath.sqrt(144));          // 12
console.log(NativeMath.describe());         // { name: "NativeMath", version: 1, engine: "JSI" }

try {
    NativeMath.sqrt(-1);
} catch (e) {
    console.log(e.message);                 // "sqrt: argument must be non-negative"
}

try {
    NativeMath.add("hello", 7);
} catch (e) {
    console.log(e.message);                 // "add: argument 0 must be a number"
}

output

10
42
12
{ "name": "NativeMath", "version": 1, "engine": "JSI" }
"sqrt: argument must be non-negative"
"add: argument 0 must be a number"

Every concept from this post and Part 3 is at work:

Pattern	What's Happening
`jsi::Runtime& rt`	Reference — borrows the runtime
`const jsi::Value* args`	Pointer — C-style array of arguments
`requireNumber` lambda	Captured by value into each host function
`jsi::JSError`	C++ exception → JavaScript `Error`
`std::move(add)`	Move semantics — transfers ownership to the module object
`jsi::Object(rt)`	Stack-allocated JSI object — RAII manages its handle
`setProperty` on `mathModule`	Installs functions on an object (not global) — cleaner namespace

Global vs Object Installation

You have two choices for where to install your functions:

Global installation — the function is available everywhere:

Global — available as a bare function

rt.global().setProperty(rt, "nativeAdd", std::move(fn));
// JS: nativeAdd(3, 7)

Object installation — the function is namespaced:

Object — namespaced under a module

auto module = jsi::Object(rt);
module.setProperty(rt, "add", std::move(fn));
rt.global().setProperty(rt, "NativeMath", std::move(module));
// JS: NativeMath.add(3, 7)

Prefer object installation. It avoids polluting the global namespace, groups related functions together, and matches how JavaScript modules work. The only reason to use global installation is for very simple, single-function modules.

The Tradeoffs (What This Approach Can't Do)

Pure JSI functions — as shown in this post — are powerful but limited:

Capability	JSI Host Functions	What You Need Instead
Synchronous calls	Yes — runs on JS thread	—
Return values	Yes — any `jsi::Value`	—
Stateful modules	Possible via `shared_ptr` captures, but verbose — no properties, no `this`	HostObjects (Part 5) — expose C++ classes with a clean interface
Async operations	No — must return synchronously	CallInvoker (Part 8) — background threads + Promises
Platform APIs	No — pure C++ only	Platform wiring (Part 7) — Obj-C++/JNI bridges
Type safety from JS	No — manual validation	TurboModules (Part 11) — codegen from Flow/TS specs

Figure 3: What JSI host functions can and can't do. Parts 5–11 address each limitation.

The biggest ergonomic limitation: no clean stateful interface. You can capture shared_ptr in lambdas to share state (as we did in Part 3's key-value store example), but it gets verbose fast — no property access, no this, and no way to group methods on an object that JavaScript can inspect. When you want a database connection, a cache, or a streaming audio session, you need a C++ object that JavaScript can interact with as a first-class object. That's what HostObjects provide — and that's Part 5.

Key Takeaways

createFromHostFunction is the core API. It takes a runtime, a name (for stack traces), an argument count, and a C++ lambda. The lambda is what JavaScript calls. That's the entire mechanism.
Always validate arguments. Check count before accessing args[index]. Check isNumber() / isString() / isObject() before calling asNumber() / asString(rt) / asObject(rt). Never trust that JavaScript passed what you expect.
Wrap native errors in jsi::JSError. The JSI runtime catches std::exception subclasses automatically, but the error messages are generic. Wrapping in try/catch gives you clear error messages and catches non-standard exceptions. Let jsi::JSError pass through unchanged. Undefined behavior (out-of-bounds access, dangling pointers) bypasses all exception handling — validate inputs first.
Install on objects, not globals. Group related functions under a namespace object (NativeMath.add) rather than polluting the global scope (nativeAdd). It's cleaner and matches JavaScript conventions.
Host functions are synchronous. They execute on the JS thread and return immediately. If your operation takes more than ~1ms, you'll block the event loop. Async patterns (background threads + Promises) come in Part 8.

Frequently Asked Questions

How do you create a JSI function in React Native?

Use jsi::Function::createFromHostFunction() to register a C++ lambda as a JavaScript function. The lambda receives the runtime, arguments as jsi::Value, and returns a jsi::Value.

Can JSI functions be synchronous?

Yes — JSI functions execute synchronously on the JS thread, returning results immediately without Promises or callbacks. This is only safe for operations completing in under ~1ms.

What happens if a JSI function throws?

C++ exceptions extending std::exception are caught by the JSI runtime and converted into JavaScript Error objects, catchable with try/catch on the JS side.

What's Next

You can now install C++ functions into JavaScript. But they're stateless — each call is independent. What if you want to expose a C++ object to JavaScript? A database connection that remembers its state. A cache you can read and write. An audio session you can start, pause, and stop.

In Part 5: HostObjects — Exposing C++ Classes to JavaScript, you'll learn to expose C++ classes to JavaScript as first-class objects with properties and methods. HostObjects are where JSI stops being a curiosity and becomes a real native module framework. You'll build a key-value store where storage.get('key') calls C++ synchronously — no await, no bridge, no serialization.

Part 4 gave you functions. Part 5 gives you objects.

References & Further Reading

The 5 C++ Concepts Every React Native Developer Needs (and Nothing More)

Rahul Garg — Fri, 20 Mar 2026 15:41:25 +0000

"The purpose of abstracting is not to be vague, but to create a new semantic level in which one can be absolutely precise." — Edsger W. Dijkstra, The Humble Programmer, 1972

Excerpt: You don't need to learn all of C++ to write JSI native modules. You need five concepts: stack vs heap, references and pointers, RAII, smart pointers, and lambdas. This post teaches exactly that subset — framed in JavaScript terms you already know. By the end, you'll read C++ the way you read TypeScript: not every keyword, but every intention.

Series: React Native JSI Deep Dive (12 parts — series in progress) Part 1: React Native Architecture — Threads, Hermes, and the Event Loop | Part 2: React Native Bridge vs JSI — What Changed and Why | Part 3: C++ for JavaScript Developers (You are here) | Part 4: Your First React Native JSI Function | Part 5: HostObjects — Exposing C++ Classes to JavaScript | Part 6: Memory Ownership | Part 7: Platform Wiring | Part 8: Threading & Async | Part 9: Real-Time Audio in React Native — Lock-Free Pipelines with JSI | Part 10: Storage Engine | Part 11: Module Approaches | Part 12: Debugging

The Problem: C++ Looks Like It Was Designed to Cause Suffering

If you've been writing JavaScript or TypeScript, your first encounter with C++ probably looks like this:

What a JSI function looks like

static jsi::Value multiply(
    jsi::Runtime& rt,
    const jsi::Value& thisVal,
    const jsi::Value* args,
    size_t count) {
  double a = args[0].asNumber();
  double b = args[1].asNumber();
  return jsi::Value(a * b);
}

You see &, *, const, size_t, and you think: I have to learn an entirely new language. But look again. Strip the symbols and it's a function that takes two numbers and returns their product. The & and * are about one thing only: who owns the data and where it lives.

That's the entire mental shift. JavaScript hides memory management behind a garbage collector. C++ makes you state it explicitly. Everything else — classes, loops, conditionals, strings — works roughly the way you'd expect.

This post teaches you the five C++ concepts that appear in every JSI module. No templates-of-templates. No operator overloading. No multiple inheritance. Just the vocabulary you need to read and write native module code.

Concept 1: Stack vs Heap (Where Data Lives)

In JavaScript, you never think about where your variables live. You write const x = 42 and the engine figures out the rest.

In C++, data primarily lives in one of two places — the stack or the heap — and you choose which one. (C++ also has static storage for globals and thread-local storage, but for JSI modules, stack and heap are what matter.)

The Stack

The stack is fast, automatic memory. When a function runs, its local variables live on the stack. When the function returns, they're destroyed. No cleanup required — it's instant.

Stack allocation — automatic lifetime

void greet() {
    int count = 42;            // lives on the stack
    std::string name = "JSI";  // also on the stack (string content may be heap-allocated internally)
    // use count and name...
}  // ← count and name are destroyed here, automatically

The JavaScript equivalent is a let inside a function — it exists while the function runs and is eligible for garbage collection after. But there's a crucial difference: in C++, stack destruction is immediate and deterministic. It doesn't happen "eventually" when a GC gets around to it. It happens at the closing brace. Every time. Guaranteed.

The Heap

The heap is for data that needs to outlive the function that created it. In JavaScript, everything that isn't a primitive (number, boolean) lives on the heap — objects, arrays, strings, closures. The garbage collector handles cleanup.

In C++, you explicitly allocate on the heap with new and must explicitly deallocate with delete:

Heap allocation — manual lifetime ⚠️

void createBuffer() {
    int* data = new int[1024];  // allocate 1024 ints on the heap
    // use data...
    delete[] data;              // YOU must free it
}  // if you forget delete[], those 1024 ints leak forever

Think about it: What happens if an exception is thrown between new and delete? The delete never runs. The memory leaks. This is the fundamental problem with manual memory management — and it's why modern C++ almost never uses raw new and delete. The solution is RAII, which we'll get to in Concept 3.

Here's the mental model:

┌─────────────────────────────────────────────────────────┐
│                        STACK                             │
│                                                          │
│  Fast. Automatic. Fixed-size.                            │
│  Dies when the function returns.                         │
│                                                          │
│  JS analogy: primitive values (number, boolean)          │
│  C++ use: local variables, function arguments            │
│                                                          │
├─────────────────────────────────────────────────────────┤
│                        HEAP                              │
│                                                          │
│  Slower. Manual (or smart-pointer managed). Dynamic.     │
│  Lives until you explicitly free it — or it leaks.       │
│                                                          │
│  JS analogy: objects, arrays, closures (GC'd)            │
│  C++ use: anything that outlives its creating function    │
│                                                          │
└─────────────────────────────────────────────────────────┘

Figure 1: Stack vs heap. JavaScript hides this distinction behind the garbage collector. C++ requires you to choose.

For JSI modules, you'll mostly work with stack-allocated values and smart pointers (which manage heap memory for you). Raw new and delete almost never appear in well-written modern C++.

Concept 2: References and Pointers (Aliasing Data)

In JavaScript, when you pass an object to a function, the function receives a copy of the reference — it can mutate the object's properties, but reassigning the parameter doesn't affect the caller's variable. (This is technically "pass-by-sharing," not true pass-by-reference in the C++ sense.) In practice, it feels like pass-by-reference for mutations:

JavaScript — object mutations are visible to the caller

function addItem(list) {
    list.push('new item');  // modifies the original
}

const myList = ['a', 'b'];
addItem(myList);
console.log(myList);  // ['a', 'b', 'new item']

In C++, you choose whether to pass data by value (copy it), by reference (alias it), or by pointer (hold its address). This is what the & and * symbols mean.

Pass by Value (Copy)

Pass by value — makes a copy

void process(std::string text) {   // text is a COPY
    text += " modified";           // modifies the copy only
}

std::string original = "hello";
process(original);
// original is still "hello" — the copy was modified, not the original

This is like JavaScript's behavior with primitives — let x = 5; foo(x); passes a copy.

Pass by Reference (`&`)

Pass by reference — aliases the original

void process(std::string& text) {  // & means "reference to"
    text += " modified";           // modifies the ORIGINAL
}

std::string original = "hello";
process(original);
// original is now "hello modified"

The & after the type means "this is not a copy — it's another name for the same data." The closest JavaScript analogy is passing an object to a function — the function can mutate the object's properties because it has a reference to the same data. But C++ references go further: reassigning the parameter does affect the caller's variable, unlike JavaScript.

Const Reference (`const &`)

Const reference — read-only alias

void print(const std::string& text) {  // can read but not modify
    std::cout << text;                  // OK — reading
    // text += " nope";                // COMPILER ERROR — can't modify
}

This is the most common pattern in JSI code. When a function receives data it needs to read but not modify, it takes a const &. It avoids the cost of copying while preventing accidental mutation.

Key Insight: When you see const jsi::Value& in a JSI function signature, read it as: "I'm borrowing this value for the duration of this call. I won't modify it, and I won't keep it after I return." The const is a promise to the compiler — and to every developer who reads your code.

Pointers (`*`)

A pointer holds the memory address of data. It's a lower-level construct than a reference — references are typically implemented as pointers under the hood, but with safer semantics (can't be null, can't be reseated).

Pointers — the address operator

int value = 42;
int* ptr = &value;    // ptr holds the ADDRESS of value
                      // (& here means "address of", not "reference" — context matters)
std::cout << *ptr;    // 42 — *ptr DEREFERENCES the pointer (reads the value at that address)

You'll see pointers in JSI function signatures:

JSI function — pointer to argument array

jsi::Value myFunction(
    jsi::Runtime& rt,          // reference to the runtime
    const jsi::Value& thisVal, // const reference to "this"
    const jsi::Value* args,    // POINTER to array of arguments
    size_t count               // how many arguments
) {
    double x = args[0].asNumber();  // args[0] works like array indexing
    // ...
}

The args parameter is a pointer to the first element of an array. args[0] is the first argument, args[1] is the second. The count parameter tells you how many there are. This is C-style array passing — no .length property, so the count is passed separately.

The Cheat Sheet

Symbol	Meaning	JS Analogy
`Type x`	Value (copy)	Primitive: `let x = 5`
`Type& x`	Reference (alias)	Object parameter: `function f(obj)`
`const Type& x`	Read-only reference	A read-only view — others may still have write access
`Type* x`	Pointer (memory address)	No direct analogy — closest is a weak reference
`&x`	"Address of x" (in an expression)	No analogy
`*x`	"Value at address x" (dereference)	No analogy

Figure 2: C++ parameter passing symbols. The & does double duty — in a type declaration it means "reference," in an expression it means "address of."

Gotcha: The & symbol has two completely different meanings depending on context. In a type declaration (std::string& text), it means "reference to." In an expression (int* ptr = &value), it means "address of." This trips up every JS developer learning C++. When you see &, check whether it's next to a type or next to a variable name.

Concept 3: RAII (The Destroyer Pattern)

RAII — Resource Acquisition Is Initialization — is the most important C++ concept for JSI development. It has the worst name in computer science, but the idea is simple.

In JavaScript, you write cleanup code manually:

JavaScript — manual cleanup with try/finally

function readFile(path) {
    const handle = openFile(path);
    try {
        return handle.read();
    } finally {
        handle.close();  // you must remember this
    }
}

If you forget the finally, the file handle leaks. If an exception throws before close() but outside the try, the file handle leaks. It's fragile.

In C++, RAII means: the constructor acquires the resource, and the destructor releases it. Since destructors run automatically when objects leave scope (stack unwinding), cleanup is guaranteed — even if exceptions are thrown.

C++ — RAII makes cleanup automatic

class FileHandle {
    FILE* file_;
public:
    FileHandle(const char* path) : file_(fopen(path, "r")) {   // acquire
        if (!file_) throw std::runtime_error("Failed to open file");
    }
    ~FileHandle() { fclose(file_); }                             // release — runs automatically

    std::string read() { /* ... */ }
};

void readFile(const char* path) {
    FileHandle handle(path);     // constructor opens the file
    auto content = handle.read();
    return content;
}  // ← destructor runs here — file is closed, guaranteed
   //   even if handle.read() threw an exception

The ~FileHandle() is a destructor — a function that runs automatically when the object is destroyed. For stack-allocated objects, that means when the scope ends (the closing }). For heap-allocated objects, it means when delete is called (or when a smart pointer decides it's time).

Key Insight: RAII is not about files. It's about any resource — memory, network connections, locks, GPU buffers, audio sessions. The pattern is always the same: acquire in the constructor, release in the destructor, and let scope determine lifetime. In JSI modules, HostObjects use RAII for their C++ state: when JavaScript's garbage collector collects the HostObject, the C++ destructor runs and cleans up native resources.

Here's the mental model:

JavaScript:                          C++ (RAII):

  const x = acquire();                {
  try {                                 Resource x(...);  // acquire
    use(x);                             use(x);
  } finally {                        }  // ← destructor releases
    release(x);                         //   automatically, even
  }                                     //   on exception

Figure 3: RAII eliminates manual cleanup. The closing brace IS the finally block.

The reason RAII matters for JSI: native modules manage resources that the JavaScript garbage collector knows nothing about — audio buffers, file handles, database connections, native thread pools. RAII ensures these resources are cleaned up deterministically, not "whenever the GC gets around to it."

Concept 4: Smart Pointers (Automatic Heap Management)

Raw new and delete are C++'s type-safe, object-aware replacements for C's malloc and free. Unlike malloc/free, new calls constructors and delete calls destructors — but they're still error-prone when used manually. Modern C++ uses smart pointers — RAII wrappers around heap pointers that automatically delete the memory when it's no longer needed.

There are two smart pointers you need to know. Think of them as two different ownership policies.

`std::unique_ptr` — Exclusive Ownership

A unique_ptr owns its data exclusively. Nobody else can own it. When the unique_ptr is destroyed, the data is freed. You cannot copy it — you can only move it (transfer ownership).

unique_ptr — one owner, automatic cleanup

#include <memory>

void example() {
    // Create a unique_ptr — it owns the AudioBuffer
    auto buffer = std::make_unique<AudioBuffer>(1024);
    buffer->fill(0.0f);    // use it like a regular pointer

    // auto copy = buffer;  // ❌ COMPILER ERROR — can't copy a unique_ptr
    auto moved = std::move(buffer);  // ✓ Transfer ownership
    // buffer is now nullptr — moved owns the data
}  // ← moved is destroyed here, AudioBuffer is freed

The JavaScript analogy: imagine a const reference that you can't share. Only one variable can point to the data at a time. If you want to pass it somewhere else, you move it — the original becomes null.

unique_ptr ownership:

  auto a = make_unique<X>();     a ──────▶ [X on heap]

  auto b = std::move(a);         a ──▶ nullptr
                                 b ──────▶ [X on heap]

  // b goes out of scope          b destroyed → [X freed]

Figure 4: unique_ptr ownership transfer. Only one pointer to the data at a time. Moving transfers ownership and nullifies the source.

`std::shared_ptr` — Shared Ownership

A shared_ptr lets multiple owners share the same data. It maintains a reference count — every copy increments the count, every destruction decrements it. When the count hits zero, the data is freed.

shared_ptr — reference-counted ownership

#include <memory>

void example() {
    auto config = std::make_shared<AppConfig>();  // refcount = 1

    auto copy1 = config;   // refcount = 2 (both point to same AppConfig)
    auto copy2 = config;   // refcount = 3

    copy1.reset();          // refcount = 2 (copy1 releases its share)
    copy2.reset();          // refcount = 1
}  // config destroyed → refcount = 0 → AppConfig freed

This is closest to how JavaScript's garbage collector works — the object lives as long as someone references it. The difference: shared_ptr uses deterministic reference counting (freed immediately when count hits zero), while JS uses tracing GC (freed "eventually" during a GC pass).

shared_ptr reference counting:

  auto a = make_shared<X>();     a ──────▶ [X] refcount: 1
  auto b = a;                    a ──────▶ [X] refcount: 2
                                 b ──────┘
  a.reset();                     b ──────▶ [X] refcount: 1
  b.reset();                               [X] refcount: 0 → freed

Figure 5: shared_ptr reference counting. Multiple pointers to the same data. Freed when the last one lets go.

Which One for JSI?

Smart Pointer	Use When	JSI Example
`unique_ptr`	One owner, no sharing needed	Internal buffers, temporary computation results
`shared_ptr`	Multiple owners, or exposed to JS	HostObjects — JS GC and C++ code both need access

The critical one for JSI is shared_ptr. When you create a HostObject (a C++ object exposed to JavaScript), it's wrapped in a std::shared_ptr. The JavaScript garbage collector holds one reference, and your C++ code may hold others. The HostObject is destroyed only when both JS and C++ have released their references.

HostObject uses shared_ptr — preview of Part 5

// HostObjects are always shared_ptr — JS GC holds one reference
auto storage = std::make_shared<StorageHostObject>(dbPath);
runtime.global().setProperty(
    runtime, "storage",
    jsi::Object::createFromHostObject(runtime, storage)
);
// Now: JS holds a reference (via GC) AND C++ holds 'storage'
// StorageHostObject is freed when BOTH release

Gotcha: shared_ptr has overhead — the reference count is an atomic integer (thread-safe increment/decrement), and each shared_ptr is larger than a raw pointer (it carries the control block). For hot paths and real-time code, prefer unique_ptr. We'll see why this matters in Parts 8 and 9 when we build threaded and audio pipeline code.

Concept 5: Lambdas (C++ Closures)

Lambdas are the C++ concept you'll recognize most immediately. They're closures — anonymous functions that can capture variables from their surrounding scope.

JavaScript closure

function makeCounter() {
    let count = 0;
    return () => ++count;
}

C++ lambda — the same pattern

auto makeCounter() {
    int count = 0;
    return [count]() mutable { return ++count; };
}

The syntax looks different, but the observable output is the same: call the returned function three times and you get 1, 2, 3. The mechanism differs — JS captures the variable binding (shared with other closures from the same scope), while C++ [count] mutable captures a private copy — but for a single returned counter, the result is identical.

Lambda Anatomy

[capture](parameters) -> return_type { body }

The capture list [...] is what makes C++ lambdas different from JavaScript closures. In JavaScript, closures automatically capture the enclosing scope's variable bindings — they see mutations to those variables, similar in behavior to C++ capture-by-reference (though JS keeps the scope alive via GC, so there's no dangling reference risk). In C++, you explicitly choose what to capture and how:

Capture modes

int x = 10;
std::string name = "JSI";

auto byValue   = [x]()       { return x; };          // copies x (snapshot)
auto byRef     = [&x]()      { return x; };          // references x (live alias)
auto everything = [=]()      { return x; };           // copies ALL variables
auto allByRef  = [&]()       { return x; };           // references ALL variables
auto mixed     = [x, &name]() { return name + "!"; }; // x by value, name by ref

Capture	Syntax	JS Analogy	Behavior
By value	`[x]`	`const x_copy = x` then use `x_copy`	Snapshot — changes to `x` outside don't affect the lambda
By reference	`[&x]`	Closest to JS closure behavior	Live alias — sees changes to `x`, and can modify it
All by value	`[=]`	No direct analogy	Copies everything referenced in the body
All by reference	`[&]`	Closest to default JS closures	References everything — most like JavaScript

Figure 6: Lambda capture modes. JavaScript closures always share the enclosing scope's bindings. C++ makes you choose — and the choice matters for thread safety.

Why Captures Matter for JSI

This is where the JSI connection becomes critical. When you create a JSI host function, you typically use a lambda:

JSI host function with lambda capture

void install(jsi::Runtime& runtime, std::shared_ptr<Database> db) {
    auto get = jsi::Function::createFromHostFunction(
        runtime,
        jsi::PropNameID::forAscii(runtime, "get"),
        1,  // argument count
        [db](jsi::Runtime& rt,              // ← capture db by value (shared_ptr copy)
             const jsi::Value& thisVal,
             const jsi::Value* args,
             size_t count) -> jsi::Value {
            auto key = args[0].asString(rt).utf8(rt);
            auto result = db->get(key);     // use the captured database
            return jsi::String::createFromUtf8(rt, result);
        }
    );
    runtime.global().setProperty(runtime, "dbGet", std::move(get));
}

Notice: the lambda captures db by value — but db is a shared_ptr, so capturing by value copies the shared pointer, incrementing the reference count. The lambda now shares ownership of the database. Even if the original db variable goes out of scope, the lambda's copy keeps the database alive.

Think about it: What would happen if we captured db by reference ([&db]) instead of by value ([db])? The install function would return, db (a local variable) would be destroyed, and the lambda would hold a dangling reference — a pointer to memory that no longer exists. The next time JavaScript called dbGet(), it would crash. This is why JSI lambdas almost always capture shared_ptr by value, not by reference.

This pattern — capturing shared_ptr by value inside JSI lambdas — appears in virtually every native module. It's how C++ objects stay alive as long as JavaScript needs them.

Move Semantics: Transferring Ownership

One more concept ties everything together. You've already seen std::move with unique_ptr. Let's understand what it actually does.

In JavaScript, assigning an object doesn't copy it:

JavaScript — objects are shared, not copied

const a = { data: [1, 2, 3] };
const b = a;      // b and a point to the SAME object
b.data.push(4);   // a.data is also [1, 2, 3, 4]

In C++, assigning an object copies it by default:

C++ — objects are copied by default

std::vector<int> a = {1, 2, 3};
std::vector<int> b = a;     // b is a COPY — a and b are independent
b.push_back(4);             // a is still {1, 2, 3}

Copying is safe but expensive. If a holds a megabyte of data, b = a copies that megabyte. std::move says: "I'm done with a — transfer its guts to b without copying."

Move — transfer without copying

std::vector<int> a = {1, 2, 3};
std::vector<int> b = std::move(a);  // b steals a's internal buffer
// a is now in a "moved-from" state — valid but unspecified (typically empty)
// b holds {1, 2, 3} — no copy happened

Think of it like this: a normal copy is photocopying a 100-page document. A move is handing someone the document — instant, but now you don't have it anymore.

Copy:    a ──▶ [1,2,3]         b ──▶ [1,2,3]    (two copies exist)

Move:    a ──▶ []              b ──▶ [1,2,3]    (data transferred, no copy)

Figure 7: Copy vs move. Copy duplicates the data. Move transfers ownership — the source is left in a valid but unspecified state (typically empty).

You'll see std::move in JSI code when:

Transferring a unique_ptr to a new owner
Passing a large object into a function without copying it
Returning a constructed object from a function efficiently

Move in JSI context

// Moving a JSI function into a property (no copy needed)
auto fn = jsi::Function::createFromHostFunction(rt, name, 0, callback);
runtime.global().setProperty(runtime, "myFunc", std::move(fn));
// fn is now empty — runtime.global() owns the function

Putting It All Together: Reading Real JSI Code

Let's apply all five concepts to a real-world JSI module. This is a simplified version of what you'd see in a library like react-native-mmkv:

A complete mini JSI module — every concept in action

#include <jsi/jsi.h>
#include <memory>
#include <string>
#include <unordered_map>

using namespace facebook;

// A simple in-memory key-value store
class KeyValueStore {                                    // RAII: constructor acquires,
public:                                                  //       destructor releases
    void set(const std::string& key,                     // const& — read-only reference
             const std::string& value) {
        data_[key] = value;
    }

    std::string get(const std::string& key) const {      // const method — won't modify state
        auto it = data_.find(key);
        if (it != data_.end()) return it->second;
        return "";
    }

private:
    std::unordered_map<std::string, std::string> data_;  // stack-allocated (inside the object)
};  // destructor frees data_ automatically (RAII)

void installStorage(jsi::Runtime& rt) {                  // reference — aliases the runtime
    // shared_ptr: JS GC and C++ both need access
    auto store = std::make_shared<KeyValueStore>();

    // "set" function — lambda captures store by value (shared_ptr copy, refcount++)
    auto setFn = jsi::Function::createFromHostFunction(
        rt, jsi::PropNameID::forAscii(rt, "set"), 2,
        [store](jsi::Runtime& rt, const jsi::Value&,
                const jsi::Value* args, size_t count) -> jsi::Value {
            auto key = args[0].asString(rt).utf8(rt);    // jsi::String → std::string
            auto val = args[1].asString(rt).utf8(rt);
            store->set(key, val);                        // use captured shared_ptr
            return jsi::Value::undefined();
        }
    );

    // "get" function — same capture pattern
    auto getFn = jsi::Function::createFromHostFunction(
        rt, jsi::PropNameID::forAscii(rt, "get"), 1,
        [store](jsi::Runtime& rt, const jsi::Value&,
                const jsi::Value* args, size_t count) -> jsi::Value {
            auto key = args[0].asString(rt).utf8(rt);
            auto result = store->get(key);
            return jsi::String::createFromUtf8(rt, result);
        }
    );

    // Install into JavaScript global scope — move (no copy needed)
    auto storage = jsi::Object(rt);
    storage.setProperty(rt, "set", std::move(setFn));    // move: transfer ownership
    storage.setProperty(rt, "get", std::move(getFn));
    rt.global().setProperty(rt, "storage", std::move(storage));
}

Using it from JavaScript

storage.set('theme', 'dark');                // synchronous — no await
const theme = storage.get('theme');          // synchronous — returns immediately
console.log(theme);                          // "dark"

output

"dark"

Every concept from this post appears in that code:

Line	Concept	What's Happening
`jsi::Runtime& rt`	Reference	Borrows the runtime — doesn't own it
`const jsi::Value&`	Const reference	Read-only access to the `this` value
`const jsi::Value* args`	Pointer	Points to the argument array
`std::make_shared()`	Smart pointer	Heap allocation with shared ownership
`[store](...) { ... }`	Lambda + capture	Closure capturing `shared_ptr` by value
`std::move(setFn)`	Move	Transfers function ownership to the object
`~KeyValueStore()` (implicit)	RAII	Destructor frees `data_` when store is destroyed

The Concepts You Don't Need (Yet)

C++ is enormous. Here's what you can safely ignore for JSI work:

C++ Feature	Why You Don't Need It
Templates (advanced)	JSI uses them internally, but you rarely write them
Multiple inheritance	JSI uses single inheritance (`HostObject` base class)
Operator overloading (advanced)	JSI uses move-assignment operators and basic comparisons internally, but you won't write custom overloads for JSI modules
`const_cast` / `reinterpret_cast`	Have legitimate uses in systems code, but you won't need them for JSI modules
Manual `new` / `delete`	Use `make_unique` and `make_shared` instead
Preprocessor macros (`#define`)	Occasionally for platform `#ifdef`, but not for logic

If you encounter these in third-party native modules, you can usually understand the surrounding code without understanding the advanced feature.

Key Takeaways

Stack vs heap. Stack memory is automatic — allocated when a function starts, freed when it returns. Heap memory outlives functions but must be managed. For JSI modules, smart pointers manage the heap for you.
References (&) and pointers (*). References are aliases — another name for existing data. const & means "read-only borrow." Pointers hold memory addresses. In JSI code, you'll see jsi::Runtime& (borrow the runtime) and const jsi::Value* (pointer to the argument array).
RAII. Constructors acquire resources, destructors release them. Scope determines lifetime. This is C++'s answer to try/finally — but it's built into the language and can't be forgotten. Every HostObject relies on RAII to clean up native resources when JavaScript garbage-collects it.
Smart pointers. unique_ptr = one owner, automatic cleanup. shared_ptr = shared ownership via reference counting. HostObjects use shared_ptr because both JavaScript's GC and C++ code need to hold references to the same object.
Lambdas capture explicitly. Unlike JavaScript closures (which automatically share the enclosing scope's variable bindings), C++ lambdas require you to declare what they capture and how. For JSI, the key pattern is: capture shared_ptr by value inside lambdas so the native object stays alive as long as JavaScript needs it.

What's Next

You now have the C++ vocabulary. You know where data lives (stack vs heap), how to borrow it (&), how to manage it (unique_ptr, shared_ptr), how to clean it up (RAII), and how to write closures (lambdas with explicit captures).

In Part 4: Your First JSI Function, we put it all together. You'll write a JSI function from scratch — registering it with the runtime, validating arguments, handling errors, and calling it from JavaScript. No boilerplate generators, no codegen. Just raw JSI.

Part 3 gave you the vocabulary. Part 4 gives you the verb.

References & Further Reading

React Native JSI Deep Dive — Part 2: The Bridge is Dead, Long Live JSI

Rahul Garg — Wed, 18 Mar 2026 08:51:20 +0000

"There is no doubt that the grail of efficiency leads to abuse. Programmers waste enormous amounts of time thinking about, or worrying about, the speed of noncritical parts of their programs. We should forget about small efficiencies, say about 97% of the time: premature optimization is the root of all evil." — Donald Knuth, Structured Programming with go to Statements, 1974

Excerpt: Every React Native native module call used to pass through a single chokepoint: the Bridge. It serialized every value to JSON, batched every call into an async queue, and made it impossible to build anything that needed to respond in under 16 milliseconds. JSI replaced it with something deceptively simple — a direct C++ function pointer. No serialization. No queue. No bridge. This post traces a native module call through both architectures so you can see exactly what changed and why it matters.

Series: React Native JSI Deep Dive (12 parts — series in progress) Part 1: The Runtime You Never See | Part 2: The Bridge is Dead, Long Live JSI (You are here) | Part 3: C++ Foundations | Part 4: JSI Functions | Part 5: HostObjects | Part 6: Memory Ownership | Part 7: Platform Wiring | Part 8: Threading & Async | Part 9: Audio Pipeline | Part 10: Storage Engine | Part 11: Module Approaches | Part 12: Debugging

Quick Recap

In Part 1, we established that React Native runs as three execution domains — JS thread (Hermes), UI thread (platform), and native background threads — communicating via message passing. The JS engine exposes a C++ interface called jsi::Runtime. And we left off with a teaser: before JSI, the messaging system between these worlds was a JSON serialization layer called the Bridge.

Now let's open it up and see what was actually inside.

The Problem: The Invisible Tax

Here's a native module you might write in the old architecture:

android/src/main/java/com/myapp/MathModule.java

@ReactMethod
public void multiply(double a, double b, Promise promise) {
    promise.resolve(a * b);
}

And from JavaScript:

App.js

const result = await NativeModules.MathModule.multiply(3, 7);
console.log(result); // 21

Two numbers in, one number out. The actual multiplication takes nanoseconds. But in the old architecture, this call took milliseconds — orders of magnitude slower than the work itself.

Where did all that time go?

The Bridge: How It Actually Worked

The Bridge — formally the BatchedBridge backed by MessageQueue.js — sat between JavaScript and native code. Nearly every JS ↔ native call passed through it. (A few subsystems bypassed it — notably the native animated driver, which serialized the animation graph once and then ran entirely on the UI thread — but all native module calls and most event dispatch went through the Bridge.)

Here's what happened when you called multiply(3, 7):

JavaScript                          Bridge                              Native
    │                                  │                                   │
    │  NativeModules.MathModule        │                                   │
    │     .multiply(3, 7)              │                                   │
    │                                  │                                   │
    │  1. Serialize call:              │                                   │
    │     moduleIDs: [42],             │                                   │
    │     methodIDs: [3],              │                                   │
    │     params: [[3, 7]]             │                                   │
    │     (three parallel arrays —     │                                   │
    │      numeric IDs, not names)     │                                   │
    │                                  │                                   │
    │  2. Enqueue in batch ──────────▶ │                                   │
    │                                  │                                   │
    │                                  │  3. Wait for batch flush          │
    │                                  │     (≥5ms between JS-initiated    │
    │                                  │      flushes, or next native poll)│
    │                                  │                                   │
    │                                  │  4. Flush batch ────────────────▶ │
    │                                  │                                   │
    │                                  │                    5. JSON.parse  │
    │                                  │                    6. Find module │
    │                                  │                    7. Invoke      │
    │                                  │                       method     │
    │                                  │                    8. Compute:    │
    │                                  │                       3 * 7 = 21 │
    │                                  │                                   │
    │                                  │                    9. Serialize   │
    │                                  │                       result     │
    │                                  │  ◀──────────────── 10. Send back │
    │                                  │                                   │
    │  11. Deserialize result ◀─────── │                                   │
    │  12. Resolve promise             │                                   │
    │      result = 21                 │                                   │

Figure 1: A native module call through the Bridge. The actual work (step 8) is a single multiplication. Everything else is overhead.

Count the steps: twelve. The actual computation is step 8 — a single multiplication. The other eleven steps are pure overhead: serialization, queuing, deserialization, dispatch.

Let's break down the two costs the Bridge imposed.

Cost 1: JSON Serialization

Every value that crossed the Bridge was serialized to JSON on one side and parsed back on the other. Numbers, strings, booleans, arrays, objects — everything was converted to a JSON string, transmitted as bytes, and reconstructed from scratch.

For multiply(3, 7), that means the call is encoded into three parallel arrays — moduleIDs, methodIDs, and params — using numeric IDs that map to registered module and method names. The arguments themselves ([3, 7]) are JSON-serialized:

JS side:  Enqueue into batch arrays:
          moduleIDs: [42]        (numeric ID for "MathModule")
          methodIDs: [3]         (numeric ID for "multiply")
          params:    [[3, 7]]    (JSON-serialized arguments)

Native:   Deserialize the batch, look up module 42 / method 3,
          parse the argument array [3, 7]

For two numbers, this is wasteful but survivable. But consider what happens with real data:

Sending a large dataset across the Bridge

// Passing 10,000 items to native for processing
NativeModules.DataProcessor.process(items);

// Bridge must:
// 1. JSON.stringify 10,000 objects (~2-5ms for complex objects)
// 2. Copy the resulting string across the bridge
// 3. JSON.parse on the native side (~2-5ms)
// Total serialization overhead: 4-10ms — before native code even starts

And it wasn't just data size. It was data types. JSON has no concept of typed arrays, binary data, or ArrayBuffers. If you needed to pass image pixels, audio samples, or any binary data to native code, you had two options: Base64-encode it (inflating size by 33% and adding encoding/decoding overhead) or write it to a temporary file and pass the file path.

Neither option let you share memory. Every byte was copied at least twice.

Key Insight: The serialization cost was proportional to the size of data being transferred, not the complexity of the operation. A native function that took 0.1ms to execute could spend 10ms just getting its arguments across the Bridge. The Bridge made cheap operations expensive and made transferring large data impractical.

Cost 2: Async-Only Batching

The Bridge was asynchronous. Every call — even a simple multiplication that could return instantly — was enqueued in a batch queue and processed later. There was no way to make a synchronous native call.

Here's why this mattered. Imagine you're building a key-value store:

The async tax on a simple lookup

// What you WANT to write (synchronous, like localStorage):
const theme = Storage.get('theme');
renderApp(theme);

// What you HAD to write (async, because the Bridge):
const theme = await NativeModules.Storage.get('theme');
renderApp(theme);

The await doesn't just add syntax. It suspends the async function, and because the Bridge dispatched calls to a separate native thread, the result couldn't come back until a future event loop cycle — after the native thread received the batch, executed the call, and sent the result back across the Bridge. For a cache lookup that takes microseconds on the native side, this cross-thread round-trip added milliseconds of latency.

And because the Bridge batched calls, multiple native calls from the same JS execution frame were collected and sent together:

Batching behavior

// These three calls don't execute immediately.
// They're collected into a batch:
NativeModules.Analytics.track('screen_view');
NativeModules.Storage.get('user_id');
NativeModules.Logger.info('App mounted');

// The batch is flushed on the next event loop cycle.
// All three calls cross the Bridge together.
// Results come back asynchronously, in an unspecified order.

Batching was an optimization — sending one message with three calls is cheaper than three separate messages. But it meant you couldn't get a result during the current execution frame. Every native call was a round trip through the event loop.

Gotcha: The Bridge's batching behavior created subtle bugs. If you called two native methods that depended on each other — say, write('key', 'value') followed by read('key') — they were batched together, but execution order on the native side wasn't guaranteed to match call order. Race conditions in Bridge-based native modules were a common source of bugs that were nearly impossible to reproduce.

Where It Broke Down

For simple apps with occasional native calls, the Bridge was fine. Millions of React Native apps shipped on it. But it had a ceiling, and three categories of work hit that ceiling hard:

High-Frequency Events

JS-driven scroll-linked animations were a common pain point. When a scroll event needed to update a JS-driven animation, each event triggered a Bridge round-trip: the event was serialized to JSON on the native side, deserialized on the JS side, processed by JavaScript (which computed the new animation value), and the result serialized back to native for the UI update. If any step took longer than the frame budget, the animation stuttered.

Scroll event driving a JS animation:

  UI Thread                Bridge                 JS Thread
     │                       │                       │
     │  Scroll offset ──▶    │                       │
     │                       │  Serialize ──▶        │
     │                       │                       │  Process event
     │                       │                       │  Compute animation
     │                       │    ◀── Serialize      │
     │  ◀── Deserialize      │                       │
     │                       │                       │
     │  Apply update         │                       │
     └───────────────────────┴───────────────────────┘
                     Must complete in <16ms

Figure 2: A scroll-driven animation round-trip through the Bridge. Each event requires serialization in both directions — all within a single frame budget.

Each round-trip involves serialization and deserialization in both directions — four JSON operations per event. At high scroll velocities, these events can fire dozens of times per second, compounding the overhead quickly. (This is exactly why React Native introduced the native animated driver — useNativeDriver: true — which bypassed the Bridge entirely for animations. But any scroll-linked logic that required JavaScript computation had no escape hatch.)

Large Data Transfers

Passing images, audio buffers, or large datasets across the Bridge required serializing the entire payload to JSON (or Base64). There was no way to share a memory pointer. A 1MB audio buffer became a 1.33MB Base64 string that was copied, transmitted, parsed, and decoded — turning a zero-cost pointer share into a multi-millisecond copy operation.

Synchronous Lookups

Some operations are fundamentally synchronous. Reading a cached value, checking a feature flag, getting the current timestamp from a high-resolution native timer — these operations complete in microseconds on the native side. But the Bridge forced them through an async round-trip, adding milliseconds of overhead to microsecond operations.

This is why libraries like react-native-mmkv couldn't exist in the old architecture. MMKV's entire value proposition is synchronous key-value access — storage.getString('key') returns immediately, no await. That's only possible with JSI.

JSI: The Replacement

The JavaScript Interface (JSI) replaces the Bridge with something fundamentally different: instead of serializing messages between two separate worlds, JSI lets JavaScript hold references to C++ host objects and functions — managed through the runtime, without any JSON serialization layer in between.

No serialization. No queue. No batch. No bridge.

Here's the same multiply operation with JSI:

JavaScript                                    C++ (via JSI)
    │                                             │
    │  multiply(3, 7)                             │
    │                                             │
    │  1. Call C++ function pointer ────────────▶  │
    │     (args passed as jsi::Value,              │
    │      no serialization)                      │
    │                                             │  2. Read args directly:
    │                                             │     a = args[0].asNumber()
    │                                             │     b = args[1].asNumber()
    │                                             │  3. Compute: 3 * 7 = 21
    │                                             │  4. Return jsi::Value(21)
    │                                             │
    │  ◀──────────────────────────────────────────│
    │  5. result = 21                             │
    │     (no deserialization)                    │
    │                                             │

Figure 3: The same multiply call through JSI. Five steps instead of twelve. No serialization, no queue, no batch.

Five steps instead of twelve. And steps 1 and 5 are essentially free — they're a C++ function call and a return value. The entire overhead is a function pointer invocation.

Let's unpack what makes this possible.

How JSI Works: Function Pointers, Not Messages

When you register a JSI function, you're giving the JavaScript runtime a C++ function pointer disguised as a JavaScript function. From JavaScript's perspective, it's just a function. From C++'s perspective, it's a lambda that receives the runtime and arguments directly.

Registering a JSI function (simplified)

// C++ side: install a function into the JS runtime
runtime.global().setProperty(
    runtime,
    "multiply",
    jsi::Function::createFromHostFunction(
        runtime,
        jsi::PropNameID::forAscii(runtime, "multiply"),
        2,  // argument count
        [](jsi::Runtime& rt,
           const jsi::Value& thisVal,
           const jsi::Value* args,
           size_t count) -> jsi::Value {
            double a = args[0].asNumber();
            double b = args[1].asNumber();
            return jsi::Value(a * b);
        }
    )
);

Calling it from JavaScript

const result = multiply(3, 7);  // 21 — synchronous, no await needed

Think about it: Notice what's missing. There's no await. There's no Promise. There's no callback. The function call is synchronous — JavaScript calls it, C++ executes, the result is returned immediately on the same thread, in the same event loop tick. How is that possible when the Bridge required everything to be async?

The answer is thread affinity. The Bridge was async because it sent messages between threads — the JSON payload was produced on the JS thread and consumed on a native thread. JSI functions run on the JS thread itself. The C++ code executes in the same thread that called it. No cross-thread messaging means no async overhead.

This is why Part 1 emphasized that jsi::Runtime is confined to the JS thread. That constraint — which might have seemed limiting — is what makes synchronous calls possible.

Values Without Serialization

The Bridge converted everything to JSON. JSI passes values directly as jsi::Value — a C++ type that can hold any JavaScript value without converting it to a string first.

Here's how JavaScript types map to JSI types:

JavaScript Type	Bridge (old)	JSI (new)
`number`	JSON number → string → parse back	`jsi::Value` wrapping `double` — zero conversion
`string`	JSON string → escaped → parse back	`jsi::String` — engine-native string, no JSON serialization
`boolean`	JSON `true`/`false` → string → parse	`jsi::Value` wrapping `bool` — zero conversion
`object`	JSON.stringify entire tree	`jsi::Object` — direct handle, no copying
`array`	JSON.stringify entire array	`jsi::Array` (a `jsi::Object`) — direct handle
`ArrayBuffer`	Not supported (Base64 workaround)	`jsi::ArrayBuffer` — zero-copy pointer to raw bytes
`function`	Not passable	`jsi::Function` — callable from C++

Figure 4: Value type mapping between the Bridge and JSI. The Bridge serialized everything to strings. JSI preserves native types.

The most important row is ArrayBuffer. The Bridge had no way to pass binary data without encoding it. JSI gives you jsi::ArrayBuffer — a direct pointer to a block of raw bytes shared between JavaScript and C++. No copy, no encoding, no overhead.

Zero-copy access to binary data

// C++ reads directly from JS ArrayBuffer — no copy
auto buffer = args[0].asObject(rt).getArrayBuffer(rt);
uint8_t* data = buffer.data(rt);   // raw pointer to JS memory
size_t length = buffer.size(rt);    // size in bytes

// Process the bytes in-place — JS and C++ see the same memory
for (size_t i = 0; i < length; i++) {
    data[i] = processAudioSample(data[i]);
}

This is how audio pipelines, camera processors, and ML inference can work in React Native — binary data flows between JS and native without a single copy.

Key Insight: JSI doesn't just make the Bridge faster. It makes an entirely new category of operations possible. Zero-copy binary data sharing, synchronous function calls, passing functions and objects between JS and C++ — none of these could work through a JSON serialization layer. JSI isn't an optimization of the Bridge. It's an elimination of the Bridge.

Bridgeless Mode: The Default Path Is JSI

Starting with React Native 0.76, Bridgeless Mode is the default. All new JS ↔ native communication goes through JSI — not the classic Bridge.

The Bridge code is not fully removed from the codebase yet — React Native provides an automatic interop layer so that old-style native modules (those using @ReactMethod and BatchedBridge) continue to work during the migration period. But the interop layer is a compatibility shim, not the primary architecture. New native modules should target JSI directly, and the React Native team has stated that the bridge code and interop layer will be removed entirely in a future release.

React Native ≤ 0.72:    Bridge ON, JSI optional
React Native 0.73–0.75: Bridge ON, JSI encouraged (New Architecture opt-in)
React Native 0.76+:     JSI default (Bridgeless Mode), Bridge interop layer for legacy modules

Terminology: Bridgeless Mode means the classic JSON bridge (BatchedBridge, MessageQueue.js) is no longer the primary communication path. All new JS ↔ native communication uses JSI. An automatic interop layer keeps legacy modules working, but this shim is temporary — full bridge removal is planned. Bridgeless Mode is part of the broader "New Architecture" that also includes Fabric (the new renderer) and TurboModules (codegen-based native modules built on JSI).

The Tradeoffs (Nothing Is Free)

JSI isn't a free lunch. The Bridge had properties that were genuinely useful:

Property	Bridge	JSI
Thread safety	Inherently safe — JSON messages can be sent from any thread	Must only access `jsi::Runtime` from the JS thread
Debugging	Messages are JSON — easy to log, intercept, replay	C++ function calls — harder to trace without native debuggers
Language barrier	Any language can produce/consume JSON	Must write C++ (or Objective-C++ / JNI wrappers)
Crash surface area	Native modules in Java/Kotlin/Swift — managed memory, fewer crash vectors	C++ with manual memory — segfaults, use-after-free, and undefined behavior are possible
Simplicity	`@ReactMethod` annotation, Java/Kotlin/Swift only	C++ required for direct JSI, plus platform wiring

The Bridge traded performance for simplicity. JSI trades simplicity for performance. For most apps — where native calls are infrequent and data payloads are small — the Bridge was perfectly adequate. JSI becomes essential when you need synchronous access, binary data, or high-frequency native calls.

Feynman Moment: Here's where the "Bridge is dead" headline is slightly misleading. The mechanism is dead — no more JSON serialization and async queuing. But the pattern of sending messages between threads is alive and well. When you do heavy work on a background thread and send the result back to the JS thread via CallInvoker, that's still message passing. JSI eliminated the Bridge as an implementation detail, but it didn't eliminate the need for async communication between threads. The three-thread architecture from Part 1 hasn't changed. What changed is the cost of crossing the boundary when you're already on the right thread.

In Practice: Seeing the Difference

Let's make the performance difference concrete. Consider a storage module that reads a cached value:

Bridge (old architecture):

Bridge-based storage read (AsyncStorage)

// Average time: ~0.24ms per read (measured via StorageBenchmark)
const value = await NativeModules.Storage.get('user_theme');
// 1. Serialize call into batch arrays
// 2. Enqueue in batch
// 3. Wait for batch flush
// 4. Send to native thread
// 5. Deserialize on native side
// 6. Read from storage
// 7. Serialize result
// 8. Send back to JS thread
// 9. Deserialize result
// 10. Resolve promise

JSI (new architecture):

JSI-based storage read (react-native-mmkv)

// Average time: ~0.012ms per read (measured via StorageBenchmark)
const value = storage.getString('user_theme');
// 1. Call C++ function pointer
// 2. Read from memory-mapped storage
// 3. Return jsi::String
// Done.

Benchmarks from mrousavy/StorageBenchmark show MMKV at ~0.012ms per read vs AsyncStorage at 0.24ms — roughly a **20x speedup**. The MMKV README reports ~30x faster than AsyncStorage. The exact ratio varies by device and payload size, but the order of magnitude is consistent: not because the storage engine got faster, but because the serialization and async overhead disappeared.

Gotcha: This doesn't mean you should make everything synchronous. A synchronous JSI call that takes 50ms blocks the JS thread for 50ms — no touch events, no timers, no callbacks. Rule of thumb: if the operation completes in under 1ms, synchronous is fine. If it might take over 5ms, use a background thread with CallInvoker and return a Promise. We'll cover this pattern in detail in Part 8.

Key Takeaways

The Bridge serialized everything to JSON. Every native call — no matter how simple — paid the cost of JSON.stringify on one side and JSON.parse on the other. This made data size the dominant factor in call latency, not computational complexity.
The Bridge was async-only. Every call was batched and processed on the next event loop tick. There was no way to get a synchronous result, even for operations that completed in microseconds.
JSI replaces serialization with function pointers. JavaScript holds managed references to C++ host functions and objects through the runtime. Calls are synchronous (on the JS thread), values are passed as jsi::Value (no JSON conversion), and binary data can be shared zero-copy via jsi::ArrayBuffer.
Bridgeless Mode is the default since RN 0.76. JSI is the primary communication path. An interop layer keeps legacy Bridge-based modules working during migration, but the Bridge is no longer the default and will be fully removed in a future release.
JSI trades simplicity for performance. The Bridge let you write native modules in Java/Swift with @ReactMethod. JSI requires C++ for direct access. This is the cost of eliminating the serialization layer — and it's why Part 3 of this series teaches you the C++ you need.

What's Next

JSI gives JavaScript direct access to C++ functions. But to write those functions, you need to write C++. And if you're a JavaScript developer, C++ probably looks like it was designed to cause suffering.

Good news: you don't need to learn all of C++. You need a specific subset — the parts that matter for JSI native modules: stack vs heap, RAII, smart pointers, lambdas, and move semantics. That's it. No templates-of-templates, no operator overloading, no multiple inheritance.

In Part 3: C++ for JavaScript Developers, we'll learn exactly that subset — framed in terms you already understand from JavaScript. unique_ptr is a const reference you can't copy. shared_ptr is a garbage-collected pointer with a reference count. RAII is try/finally built into the language.

You'll write your first JSI function in Part 4. But Part 3 gives you the vocabulary to understand what that function is doing at the memory level — and why it doesn't leak, crash, or corrupt your app.

References & Further Reading

Series: React Native JSI Deep Dive (12 parts — series in progress) Part 1: The Runtime You Never See | Part 2: The Bridge is Dead, Long Live JSI (You are here) | Part 3: C++ Foundations | Part 4: JSI Functions | Part 5: HostObjects | Part 6: Memory Ownership | Part 7: Platform Wiring | Part 8: Threading & Async | Part 9: Audio Pipeline | Part 10: Storage Engine | Part 11: Module Approaches | Part 12: Debugging

React Native JSI Deep Dive — Part 1: The Runtime You Never See

Rahul Garg — Mon, 16 Mar 2026 13:54:13 +0000

"The most dangerous thought you can have as a creative person is to think you know what you're doing." — Bret Victor, The Future of Programming, 2013

Excerpt: You've built React Native apps for years. You know useState, you know FlatList, you know how to call a native module. But do you know what happens in the 16 milliseconds between your onPress handler and the pixel changing on screen? Three execution threads, two runtime environments (JavaScript via Hermes, native via Objective-C/Java/C++), and a message-passing architecture that explains every performance problem you've ever had.

Series: React Native JSI Deep Dive (12 parts — series in progress) Part 1: The Runtime You Never See (You are here) | Part 2: Bridge → JSI | Part 3: C++ Foundations | Part 4: JSI Functions | Part 5: HostObjects | Part 6: Memory Ownership | Part 7: Platform Wiring | Part 8: Threading & Async | Part 9: Audio Pipeline | Part 10: Storage Engine | Part 11: Module Approaches | Part 12: Debugging

The Problem: The Illusion of One World

Here's something that should bother you: when you write a React Native component, it feels like you're writing a single program.

App.tsx

function Counter() {
  const [count, setCount] = useState(0);
  return (
    <TouchableOpacity onPress={() => setCount(count + 1)}>
      <Text>{count}</Text>
    </TouchableOpacity>
  );
}

One file. One function. One mental model: user taps, state changes, screen updates. It feels no different from a web app.

But this is an illusion. When you press that button, your tap crosses three execution threads, passes through two runtime environments — JavaScript (Hermes) and native (Objective-C/Java/C++) — and triggers a cascade of messages between worlds that don't share memory, don't share a clock, and barely speak the same language.

Every performance problem you've ever encountered in React Native — janky scrolling, delayed touch responses, slow native module calls, mysterious frame drops — traces back to this hidden architecture. Understanding it doesn't just explain the problems. It makes the solutions feel inevitable.

The Three Threads

React Native is not a single-threaded JavaScript application that talks to native views. It behaves like a distributed system running on your phone — independent execution domains communicating via message passing. The official architecture docs describe two primary threads — JS and UI — but in practice, native module work runs on background thread pools, making the effective model three execution domains. In the New Architecture, the Fabric renderer may use additional threads for layout and shadow tree operations, but the JS/UI/Background mental model remains the most useful conceptual starting point.

Thread 1: JavaScript

This is where your code runs. Your components, your hooks, your business logic, your API calls — all of it executes here, inside a JavaScript engine.

On React Native 0.76+, that engine is Hermes — a JavaScript VM designed specifically for React Native. Unlike V8 in Chrome — which first interprets bytecode via its Ignition interpreter, then selectively JIT-compiles hot code paths through multiple optimization tiers — Hermes takes a different approach. The Hermes compiler (hermesc) pre-compiles your JavaScript to bytecode as a build step after Metro bundles the JS. The app ships this pre-compiled bytecode. When the app starts, Hermes executes it directly — no parsing, no JIT compilation, no warm-up.

Terminology: Hermes is a JavaScript engine optimized for React Native. It uses ahead-of-time bytecode compilation (via hermesc as a post-bundling build step), a concurrent generational garbage collector (Hades), and a memory model tuned for mobile constraints. It's not V8 (Chrome) or JavaScriptCore (Safari) — it's purpose-built.

The JS thread has one event loop, just like a browser. When your onPress handler fires, it goes into the event loop queue. When a fetch response arrives, its callback goes into the queue. When a timer fires, same queue. One thread processes them one at a time, in order.

This means JavaScript is fundamentally single-threaded. While your event handler runs, nothing else happens on this thread. No other callback fires. No state update processes. If your handler takes 100ms (say, sorting a large array), the UI is frozen for those 100ms — not because the screen can't update, but because the JS thread is busy and can't process the next item in the queue.

Thread 2: UI (Main Thread)

This is the platform's main thread — the one that actually draws pixels and handles touch events. On iOS, it's the thread that runs UIKit. On Android, it's the one that runs the View system.

The UI thread has one overriding constraint: it must submit work to the rendering pipeline within the frame budget — 16.6ms (60fps) or 8.3ms (120fps on newer devices). If it misses a frame, the user sees a stutter. If it misses several, the interface feels broken.

This thread does not run JavaScript. It runs native platform code — layout calculations, view hierarchy updates, animation interpolations, touch hit-testing. Your React components don't exist here. What exists here are native views — UIView on iOS, android.view.View on Android — that React Native's rendering system creates and manages on your behalf.

Key Insight: When you write <Text>Hello</Text> in React Native, no Text component exists on the UI thread. Instead, React Native creates a native platform view — on iOS, a custom UIView subclass (RCTParagraphComponentView in Fabric) that uses TextKit for rendering; on Android, a custom View subclass. These are real native views that the operating system knows how to composite. Your React tree is a description of what the UI should look like. The UI thread holds the reality.

Thread 3: Native Modules (Background)

The third thread — or more accurately, a pool of background threads — handles native module work. When your JavaScript calls AsyncStorage.getItem('key'), the work doesn't happen on the JS thread or the UI thread. It's dispatched to a background thread where native code reads from disk, then the result is sent back to the JS thread.

This is where native modules live: camera access, file I/O, biometric auth, Bluetooth — anything that talks to platform APIs.

How They Talk: Messages, Not Memory

Here's the critical insight: in the old architecture, these three threads did not share memory — they communicated exclusively by passing serialized messages. The New Architecture changes this partially: Fabric uses shared immutable C++ data structures (like the shadow tree) that multiple threads can read, and JSI allows the JS thread to directly invoke C++ code. But the core principle still holds — threads coordinate through well-defined interfaces, not by reading each other's mutable state, and most cross-thread communication still follows a message-passing pattern.

Think of three people in separate rooms. In the old architecture, the rooms were soundproof — you slid notes under the door. In the New Architecture, some rooms have a shared read-only bulletin board (the immutable shadow tree) and a direct intercom (JSI) — but you still can't reach in and rearrange someone else's desk.

┌─────────────┐     messages     ┌─────────────┐     messages     ┌─────────────┐
│             │    ──────────▶   │             │    ──────────▶   │             │
│  JS Thread  │                  │  UI Thread  │                  │   Native    │
│  (Hermes)   │    ◀──────────   │  (UIKit /   │    ◀──────────   │   Modules   │
│             │     messages     │   Android)  │     messages     │             │
└─────────────┘                  └─────────────┘                  └─────────────┘

When your onPress handler calls setCount(count + 1), here's the actual sequence:

JS thread: React runs your handler, computes the new virtual DOM, diffs it against the previous one, and determines that the Text component's content changed from "0" to "1".
JS thread → UI thread: React Native dispatches an update: "Update the text property of native view #42 to '1'."
UI thread: Receives the update, finds native view #42, updates its text property, and includes it in the next frame render.

The user sees "1" on screen. Total elapsed time: anywhere from 1ms (if everything aligns perfectly) to 100ms+ (if either thread is busy).

Feynman Moment: The soundproof rooms analogy is useful but breaks in an important way. Real soundproof rooms have a fixed door — you always pass notes through the same slot. In React Native, the mechanism for passing notes changed completely between the old and new architecture. The old architecture used a JSON serialization bridge (slow, asynchronous). The New Architecture — often called Bridgeless Mode — uses JSI, a C++ interface that lets the rooms share certain objects directly. That's what the rest of this series is about.

Let's Trace a Button Press

Here's the full path a tap takes through the system — from finger to pixel:

User Tap
   │
   ▼
UI Thread (touch hit-testing)
   │
   ▼
EventDispatcher → JSI
   │
   ▼
JS Thread (onPress handler)
   │
   ▼
React reconciliation (diff)
   │
   ▼
Fabric commit
   │
   ▼
UI Thread (native view update)
   │
   ▼
Next frame render → pixel changes

Let's walk through each step. (The timing estimates below are illustrative — actual durations vary by device, load, and complexity. No official benchmarks publish sub-millisecond breakdowns for this path.)

Touch begins. The user's finger contacts the screen. The operating system detects this on the UI thread and begins hit-testing: which native view is under the finger?

Touch dispatched. The UI thread identifies the native TouchableOpacity view and dispatches the event through React Native's EventDispatcher, which delivers it to the JavaScript runtime: "Touch began at coordinates (x, y) on view #37." (In the New Architecture, this delivery goes through JSI rather than the legacy bridge.)

JS processes the event. The JS thread picks up the event from its event loop queue. React's event system maps view #37 to your onPress callback. Your handler runs: setCount(count + 1).

React reconciliation. React runs the component again with the new state. It diffs the new virtual DOM against the previous one. It finds one change: the Text node's children changed from "0" to "1".

Fabric commit. React Native's rendering system — Fabric — packages the change and commits it. Fabric is the modern renderer that replaced the legacy UIManager; it coordinates layout and mounting between the JS and UI threads. The commit: "Set property 'text' to '1' on shadow node #42."

UI thread applies the update. The UI thread receives the update, modifies the native view, and marks the view hierarchy as needing a redraw.

Next frame. The OS composites the updated view hierarchy into the next display frame. The user sees "1".

For a simple counter, the entire pipeline typically completes within a single frame (~16ms at 60fps). The JS thread does its work quickly — reconciliation for a single text change is sub-millisecond. The rest is coordination: waiting for the event to reach JS, waiting for the commit to reach the UI thread, waiting for the next frame boundary.

Now imagine what happens when those 4ms of JS work become 40ms. Or when the UI thread is busy running a complex animation. Or when a native module call inserts another round trip. The messages pile up, the threads fall out of sync, and the user feels the lag.

The Event Loop (Your Friend and Your Bottleneck)

The JS thread runs a single event loop. Everything — touch handlers, timers, network callbacks, native module results — enters the same queue and is processed one at a time.

Event Loop Queue:
┌──────────────────────────────────────────────────┐
│ onPress() │ setTimeout() │ fetch() callback │ ... │
└──────────────────────────────────────────────────┘
     ▲                                        │
     │         Process one at a time           │
     └─────────────────────────────────────────┘

This is conceptually similar to how browsers process JavaScript tasks. And it has the same fundamental implication: any single task that takes too long blocks everything behind it.

Blocking the event loop

function onPress() {
  // This blocks the entire JS thread for ~200ms
  const sorted = hugeArray.sort((a, b) => a.localeCompare(b));
  setData(sorted);
}

While sort() runs, no touch events are processed, no animations are driven from JS, no network callbacks fire, no timers execute. The app appears frozen — not because the UI thread is stuck (it's still rendering the old state perfectly smoothly), but because the JS thread can't tell it to change anything.

Gotcha: This is why React Native animations should use the native driver (useNativeDriver: true) whenever possible. A JS-driven animation means the JS thread must send a position update message to the UI thread every 16ms. If the JS thread is busy, it misses frames and the animation stutters. A native-driven animation runs entirely on the UI thread — the JS thread doesn't need to participate at all.

Hermes: The Engine Under the Hood

The JS thread doesn't run JavaScript directly. It runs Hermes, a JavaScript engine with several properties that matter for React Native:

Bytecode Compilation

V8 in Chrome parses JavaScript source code at runtime, interprets it as bytecode (via Ignition), and then selectively JIT-compiles frequently-executed code paths through multiple optimization tiers (Sparkplug, Maglev, TurboFan). Hermes skips all of this at runtime. The hermesc compiler compiles JavaScript to bytecode as a build step — after Metro bundles your JS, but before the app is packaged. The app ships Hermes bytecode, not JavaScript source.

V8 (Chrome):     Source code → Parse → AST → Bytecode → Interpret (Ignition)
                  [hot paths only] → JIT compile (Sparkplug/Maglev/TurboFan) → Machine code
                  (parsing + interpretation at runtime; JIT warms up over time)

Hermes (RN):     Source code → hermesc → Bytecode (at build time)
                  Bytecode → Execute directly (at runtime — fast startup)

This is why React Native apps with Hermes start faster: there's no parsing step when the app launches. The tradeoff is that Hermes executes bytecode directly without a JIT compiler — no runtime compilation to native machine code. This improves startup time and memory usage at the cost of peak compute performance compared to JIT engines like V8. For most React Native workloads (UI-driven, event-based, not compute-heavy), direct bytecode execution is fast enough. For compute-heavy work, you should be in native code anyway — which is exactly what this series teaches.

The Hades Garbage Collector

Hermes uses a mostly-concurrent generational garbage collector called Hades. "Mostly-concurrent" means it performs the bulk of collection work on a background thread while your JavaScript is running — but it still requires brief stop-the-world pauses for specific phases like root marking and weak reference finalization. "Generational" means it separates objects into young and old generations — young objects (recently allocated, likely short-lived) are collected frequently and cheaply, while old objects (survived multiple collections) are collected less often. (On 32-bit platforms, Hades runs in incremental mode rather than concurrent.)

This matters because GC pauses are one of the most common causes of frame drops in JavaScript applications. Hermes's predecessor GC (GenGC) had average pauses around 200ms on large heaps. Hades dramatically reduces these by doing most work concurrently, keeping its STW pauses short — usually well below the frame budget.

Key Insight: Hades is one reason React Native 0.76+ feels smoother than older versions. JavaScriptCore (the previous default engine) has its own concurrent GC (Riptide, introduced in 2017), but Hermes's GC is specifically tuned for mobile constraints — optimizing for memory footprint and startup time rather than peak throughput. The combination of AOT bytecode (no parse/compile at startup) and Hades (short GC pauses) gives Hermes a clear edge on mobile devices.

The jsi::Runtime Interface

Here's where things get interesting for the rest of this series. Hermes doesn't just run JavaScript — it exposes a C++ interface called jsi::Runtime that native code can use to interact with the JavaScript world.

Through jsi::Runtime, C++ code can:

Create JavaScript objects and functions
Call JavaScript functions
Read and write JavaScript values
Expose C++ functions that JavaScript can call synchronously

This interface — JSI, the JavaScript Interface — is what the New Architecture is built on. It's what replaced the JSON bridge. And it's what the rest of this series teaches you to use.

But we're getting ahead of ourselves. For now, the important thing is: Hermes is not a black box. It has a C++ API surface. Native code can reach into the JavaScript world — and JavaScript can reach into native code — without serializing anything to JSON.

Why This Model Matters

Understanding the three-thread architecture isn't academic. It directly predicts the behavior of every native module you'll build in this series.

Thread affinity: JSI calls must run on the JS thread. Why? Because jsi::Runtime access is confined to the JavaScript runtime thread — accessing jsi::Runtime or any jsi::Value objects from other threads leads to undefined behavior — because JSI values are bound to a specific runtime instance, and that runtime is not thread-safe. This single constraint shapes the entire design of every native module: heavy work goes to background threads, results come back to the JS thread via CallInvoker or RuntimeExecutor.

Message-passing: The old bridge serialized every call to JSON and sent it as a message. The new architecture (JSI) allows synchronous calls — but only on the JS thread. Understanding when to use synchronous calls (fast lookups, <1ms) vs asynchronous calls (I/O, computation, >5ms) is a core skill for native module design.

Event loop: A synchronous native module call that takes 50ms blocks the entire JS thread for 50ms. No touch events, no timers, no callbacks. This is why real-time systems like audio pipelines can't be driven from JavaScript — the event loop has deterministic ordering, but its wall-clock timing varies unpredictably based on what else is in the queue, GC pauses, and device load. You can't guarantee a callback will fire within a specific deadline.

Every part of this series is a consequence of this architecture:

Part	Consequence of the Architecture
Part 2	The bridge serialized messages to JSON. JSI eliminates serialization.
Part 4	JSI functions run synchronously on the JS thread — fast but blocking.
Part 5	HostObjects let C++ objects live in the native heap with JS handles.
Part 6	JS GC and C++ heap are separate — ownership must be explicit.
Part 8	Background threads need CallInvoker to send results back to JS.
Part 9	Audio callbacks can't touch JSI — they run on a different thread.

Key Takeaways

React Native behaves like a distributed system. Three execution domains — JS, UI, Native background — coordinate through well-defined interfaces. The New Architecture allows shared immutable data structures and direct JSI calls, but threads still can't access each other's mutable state freely. Every performance issue traces back to this architecture.
Hermes is the JS engine. It uses ahead-of-time bytecode compilation via hermesc as a post-bundling build step (fast startup, no JIT), a mostly-concurrent generational garbage collector called Hades (short STW pauses), and exposes a C++ interface (jsi::Runtime) that native code can call directly.
The JS thread has one event loop. One queue, one item at a time. Any task that blocks the event loop blocks everything: touch events, timers, network callbacks, animations driven from JS.
The UI thread must produce a frame every 16ms. It doesn't run JavaScript. It runs native platform code. Your React components are descriptions; the UI thread holds the reality.
jsi::Runtime is confined to the JS thread. Accessing the runtime or any JSI values from other threads leads to undefined behavior. Background work must return results through CallInvoker or RuntimeExecutor. This single constraint drives the design of every native module in the New Architecture. If you remember one thing from this post, remember this.

What's Next

Now you know the architecture. Three threads, message-passing, a JS engine with a C++ API. But we skipped a crucial chapter: how did messages get from JS to native before JSI?

Legacy Architecture:          New Architecture (Bridgeless):

  JS Thread                     JS Thread
     │                             │
     ▼                             ▼
  Bridge Queue                  jsi::Runtime
  (batched JSON messages)          │
     │                             ▼
     ▼                          Direct C++ call
  Native deserializes              │
     │                             ▼
     ▼                          Native code
  Native code

The answer is the Bridge — a JSON serialization layer that was simple, reliable, and brutally slow. In Part 2 (coming soon), we'll trace a native module call through the Bridge, understand exactly why it was a bottleneck, and see how JSI eliminates the problem entirely.

Series status: This is Part 1 of a 12-part series currently being written. Follow heart-IT for updates as new parts are published.

References & Further Reading

Series: React Native JSI Deep Dive (12 parts — series in progress) Part 1: The Runtime You Never See (You are here) | Part 2: Bridge → JSI | Part 3: C++ Foundations | Part 4: JSI Functions | Part 5: HostObjects | Part 6: Memory Ownership | Part 7: Platform Wiring | Part 8: Threading & Async | Part 9: Audio Pipeline | Part 10: Storage Engine | Part 11: Module Approaches | Part 12: Debugging

P2P from Scratch — Part 2: Encrypted Pipes

Rahul Garg — Thu, 12 Mar 2026 06:22:35 +0000

"Privacy is necessary for an open society in the electronic age." — Eric Hughes, A Cypherpunk's Manifesto

Excerpt: In Part 1, we punched a hole through two NATs and established a raw UDP path between peers. But raw UDP is the network equivalent of shouting across an open field — anyone standing between you can listen, modify, or impersonate. This post shows how Hyperswarm turns that raw path into an encrypted, multiplexed communication channel — and why a single connection can carry dozens of independent protocols simultaneously.

Series: P2P from Scratch — Building on the Holepunch Stack Part 1: The Internet is Hostile | Part 2: Encrypted Pipes (You are here) | Part 3: Append-Only Truth | Part 4: From Logs to Databases | Part 5: Finding Peers | Part 6: Many Writers, One Truth | Part 7: Trust No One | Part 8: Building for Humans

Quick Recap

In Part 1, we punched through NATs using a DHT-coordinated timing dance and established a raw UDP path between two peers. The hole is open — but the pipe is unprotected.

The Problem: An Open Pipe Is a Dangerous Pipe

At the end of Part 1, Alice and Bob had a working UDP path. Packets flow in both directions. The NAT doors are open.

But here's the thing about UDP: it's just raw bytes on a wire. There's no encryption, no authentication, and no ordering guarantee. Three problems follow immediately.

Anyone on the network path can read the data. Your ISP, the coffee shop Wi-Fi operator, any router between you and your peer — they can all see every byte. For a file-sharing app, that means someone can read your files. For a chat app, your messages.

Anyone can modify the data in transit. A malicious router could rewrite the contents of your packets before forwarding them. You'd receive corrupted data and have no way to detect the tampering.

Anyone can impersonate your peer. Without authentication, you have no way to verify that the packets you're receiving actually come from the person you intended to talk to. A third party could intercept the connection and pretend to be Bob.

This is the classic man-in-the-middle problem. And solving it in peer-to-peer is harder than in client-server, because there's no certificate authority, no TLS handshake backed by a central trust hierarchy, and no domain name to verify.

Key Insight: In client-server HTTPS, trust flows from certificate authorities: your browser trusts DigiCert, DigiCert vouches for example.com, so you trust the connection. In P2P, there's no certificate authority. Trust must be bootstrapped from the keypairs themselves — you trust a connection because you already know the peer's public key, not because a third party vouched for them.

Secret Stream: From Raw Bytes to Encrypted Channel

Secret Stream is the component that transforms a raw Duplex stream (like our holepunched UDP path) into an encrypted, authenticated channel. It uses two cryptographic layers:

Noise XX handshake — for mutual authentication and session key derivation
libsodium's secretstream — for ongoing AEAD encryption of all payload data

The result is a standard Node.js Duplex stream that happens to encrypt everything transparently. Application code writes plaintext; the wire carries ciphertext.

The Noise Protocol Framework

The Noise Protocol Framework isn't a single protocol — it's a framework for building authenticated key-agreement protocols. You compose a Noise protocol by choosing:

A handshake pattern — which messages carry which keys
A DH function — how keys are exchanged (scalar multiplication on Ed25519 points in Hyperswarm, via noise-curve-ed)
A cipher — for encrypting handshake payloads (ChaCha20-Poly1305)
A hash function — for key derivation (BLAKE2b)

Hyperswarm uses the XX pattern. The letters describe what each side does: X means "transmit static key." Since both sides do X, both sides share their long-term public key during the handshake.

Terminology: A handshake pattern in Noise defines the sequence of messages and which cryptographic keys are exchanged at each step. The letters encode the behavior: N = no static key for that party (anonymous), K = static key Known in advance, X = static key Transmitted. XX means both sides transmit their static key — mutual authentication with no prior knowledge required.

Why XX? (And Not IK or NK)

The choice of handshake pattern has real consequences:

Pattern	What It Means	Requires Prior Knowledge?	Used When
NK	Initiator has no static key (anonymous)	Responder's key must be known in advance	Connecting to a known server
IK	Initiator's static key sent Immediately	Responder's key must be known in advance	Both keys known beforehand
XX	Both sides Transmit static key	No prior knowledge needed	General-purpose peer discovery

In a DHT-based peer discovery system, Alice often doesn't know Bob's public key in advance — she discovered him via a topic announcement. And Bob doesn't know Alice's key either. The XX pattern handles this gracefully: both peers learn each other's identity during the handshake.

The tradeoff is that XX requires three messages (one more message than IK), but for Hyperswarm's use case — where peers are strangers meeting via a DHT — this is the right choice.

The Three-Message Dance

The Noise XX handshake has three messages. Each message mixes ephemeral and static keys to progressively build a shared secret.

Terminology: In Noise, an ephemeral key is a fresh keypair generated for this specific handshake. It provides forward secrecy — even if someone later steals your static key, they can't decrypt past sessions. A static key is your long-term Ed25519 identity key. Hyperswarm uses noise-curve-ed, which performs Diffie-Hellman directly on Ed25519 points (crypto_scalarmult_ed25519_noclamp) — no conversion to Curve25519 needed.

Here's what flows over the wire:

sequenceDiagram
    participant A as Alice (Initiator)
    participant B as Bob (Responder)

    Note over A: Generate ephemeral keypair (eA)

    A->>B: Message 1: eA (Alice's ephemeral public key)
    Note over B: Generate ephemeral keypair (eB)
    Note over B: DH(eB, eA) → shared secret
    Note over B: Encrypt Bob's static key with shared secret

    B->>A: Message 2: eB + encrypted(sB)
    Note over A: DH(eA, eB) → shared secret
    Note over A: Decrypt Bob's static key
    Note over A: DH(sA, eB) → additional shared secret
    Note over A: Encrypt Alice's static key

    A->>B: Message 3: encrypted(sA)
    Note over B: DH(eB, sA) → additional shared secret
    Note over B: Derive final session keys

    Note over A,B: Both sides now have: session key, handshakeHash, remotePublicKey

Figure 1: The Noise XX three-message handshake. Ephemeral keys go first; static keys are encrypted.

Let's unpack each step:

Message 1 — Alice introduces herself (ephemerally). Alice generates a fresh ephemeral keypair and sends the public half. This is unencrypted — an eavesdropper can see it. But that's fine: ephemeral keys are disposable and reveal nothing about Alice's identity.

Message 2 — Bob responds with his identity. Bob generates his own ephemeral keypair, performs a Diffie-Hellman with Alice's ephemeral key to derive a shared secret, and uses that secret to encrypt his static public key. An eavesdropper sees Bob's ephemeral key (plaintext) and a blob of ciphertext. They can't decrypt it without performing the DH themselves.

Message 3 — Alice reveals her identity. Alice decrypts Bob's static key, performs additional DH operations mixing static and ephemeral keys, and sends her own static public key — encrypted. After this message, both sides have performed all the DH operations needed to derive the final session keys.

Key Insight: The ephemeral keys serve two purposes. First, they provide forward secrecy for all post-handshake traffic — if an attacker records the handshake and later compromises a static key, they still can't derive the session keys because the ephemeral keys are gone. Second, they protect identity hiding — static keys are encrypted, so a passive eavesdropper can't determine who is talking to whom (though the responder's identity can be probed by an active attacker who initiates a fake handshake — the initiator has stronger identity protection).

What Comes Out of the Handshake

After the three messages, both peers have:

A session key — derived from the combined DH operations, used for all subsequent encryption
The handshakeHash — a cryptographic binding of the entire handshake transcript, useful for channel binding
The remotePublicKey — the peer's verified Ed25519 public key

The handshakeHash is particularly important. It cryptographically binds everything that happened during the handshake — which keys were exchanged, in what order, with what randomness. If a man-in-the-middle had tampered with any message, the hashes wouldn't match and the handshake would fail.

Gotcha: Noise XX provides authentication — you know you're talking to the same keypair throughout the session. But authentication is not trust. You don't know who owns that keypair unless you've verified it out-of-band (pinned it, received it through an invitation flow, etc.). A stranger's keypair is authenticated but untrusted.

Post-Handshake: The Encrypted Stream

Once the handshake completes, Secret Stream switches to libsodium's secretstream for all subsequent data. This uses XChaCha20-Poly1305 — an AEAD cipher that provides both encryption (confidentiality) and authentication (tamper detection) for every chunk of data.

Terminology: AEAD (Authenticated Encryption with Associated Data) means each encrypted message includes a cryptographic tag that proves the data hasn't been modified. If even a single bit changes in transit, the authentication tag verification fails and the recipient knows the data was tampered with.

Why XChaCha20-Poly1305 and not AES-GCM?

Property	XChaCha20-Poly1305	AES-GCM
Nonce size	24 bytes (safe to generate randomly)	12 bytes (nonce reuse = catastrophic for both; 24 bytes makes random collision negligible)
Hardware dependency	No special instructions needed	Needs AES-NI or ARM Crypto Extensions for full speed
Nonce management	Automatic (libsodium secretstream handles it)	Manual (application must track nonces)
Implementation safety	ARX operations are naturally constant-time	Cache-timing risks in table-based software implementations

The 24-byte nonce is the key advantage. With a 12-byte nonce (AES-GCM), you risk catastrophic failure if two messages accidentally use the same nonce. With 24 bytes, the nonce space is large enough that random collision is negligible. In practice, libsodium's secretstream doesn't randomly generate a fresh nonce per message — it uses deterministic nonce evolution with an internal counter and automatic rekeying. The application never touches nonce management.

The result: application code just reads and writes from a standard Node.js Duplex stream. The encryption is invisible.

secret-stream-example.js

const SecretStream = require('@hyperswarm/secret-stream')

// Wrap any raw Duplex stream (e.g., the holepunched UDP path)
const encrypted = new SecretStream(isInitiator, rawStream, {
  keyPair: { publicKey, secretKey }  // Your Ed25519 identity keypair
})

// Wait for the handshake to complete
await encrypted.opened

// Now you have:
console.log(encrypted.remotePublicKey)  // Peer's verified Ed25519 key
console.log(encrypted.handshakeHash)    // Cryptographic binding of handshake

// Read and write just like any stream — encryption is transparent
encrypted.write('Hello, authenticated peer!')
encrypted.on('data', data => console.log('Received:', data.toString()))

Gotcha: Secret Stream wraps the entire connection — not individual messages. You don't choose what to encrypt and what to leave plain. Everything is encrypted, always. This is by design: selective encryption is an anti-pattern that inevitably leaks metadata.

Protomux: One Pipe, Many Protocols

We now have an encrypted Duplex stream. One encrypted pipe between two peers. But a real P2P application needs to do many things simultaneously over that connection:

Replicate a Hypercore (the append-only log from Part 3)
Sync an Autobase (the multi-writer system from Part 6)
Send custom application messages (chat, commands, metadata)

You could design a single protocol that handles all of these in one stream. But that creates a monolithic protocol where changes to one concern affect everything else.

Protomux solves this by multiplexing multiple independent protocol channels over the single encrypted stream. Each channel has its own message types, its own state machine, and its own lifecycle — but they all share the same underlying connection.

Feynman Moment: Think of Protomux like USB. A single USB cable carries power, data, and video — but each protocol runs independently. Your mouse doesn't need to know about your monitor. Similarly, Hypercore replication doesn't need to know about your chat protocol. They share a wire but live in separate channels.

How Channel Pairing Works

When two peers want to communicate over a protocol, they each create a channel with the same protocol name and id. Protomux matches channels across peers by this pair.

protomux-channels.js

const Protomux = require('protomux')

// Create a muxer over the encrypted stream
const mux = Protomux.from(encryptedStream)

// Open a channel for "my-chat-protocol"
const channel = mux.createChannel({
  protocol: 'my-chat-protocol',
  id: Buffer.from('room-42'),    // Optional: distinguishes instances
  handshake: chatHandshakeCodec, // Optional: codec for opening handshake

  onopen (handshakeData) {
    console.log('Channel opened! Peer sent:', handshakeData)
  },
  onclose () {
    console.log('Channel closed by peer')
  }
})

// Define message types on the channel
const textMessage = channel.addMessage({
  encoding: c.string,          // compact-encoding codec
  onmessage (msg) {
    console.log('Chat message:', msg)
  }
})

// Open the channel (triggers pairing with the remote side)
channel.open(myHandshakePayload)

// Send a message
textMessage.send('Hello from the other side')

The pairing is symmetric: both sides must create a channel with the same protocol name and id. If Alice creates { protocol: 'chat', id: roomId } and Bob creates the same, Protomux pairs them. If only one side creates the channel, it stays open but idle until the other side matches.

The Three Lifecycles

Every Protomux channel has three phases:

Opening — The channel sends a handshake message to the remote peer. If both sides have opened, the onopen handler fires with the remote's handshake data. This is where you exchange initial state (capabilities, versions, discovery keys).
Messages — While open, either side can send messages. Each message type is registered with channel.addMessage() and has its own encoding and handler. Messages within a channel are delivered in order.
Closing — Either side can close the channel. The onclose handler fires on the remote. Closing one channel does not close the underlying connection or affect other channels.

Key Insight: Hyperswarm deduplicates connections — if you join multiple topics and discover the same peer through several of them, you still get a single connection. Protomux is what makes this work: each topic or Hypercore gets its own channel on the shared connection. Without multiplexing, connection deduplication would be impossible.

How Hypercore Uses Protomux

When you replicate a Hypercore, the replication protocol opens a Protomux channel with:

Protocol name: 'hypercore/alpha'
Channel id: The Hypercore's discoveryKey (a keyed BLAKE2b-256 hash: BLAKE2b-256(key=publicKey, data="hypercore") — not the public key itself, which would leak what data you're interested in)

The Hypercore replication protocol currently defines 10 message types on this channel:

Message	Direction	Purpose
`sync`	Both	Announce local length and fork ID
`request`	Either	Ask for a specific block
`cancel`	Either	Cancel a pending block request
`data`	Either	Respond with block + Merkle proof
`noData`	Either	Indicate requested data is unavailable
`want`	Either	Express interest in a block range
`unwant`	Either	Cancel interest in a range
`bitfield`	Either	Full bitfield of available blocks
`range`	Either	Download a contiguous range
`extension`	Either	Custom extension messages

When Alice replicates three different Hypercores with Bob, three Protomux channels open — one per discoveryKey — all sharing the same encrypted connection. Each channel independently tracks which blocks Alice has, which Bob has, and what needs to be exchanged.

Cork and Uncork: Batching for Performance

When an application sends many small messages in quick succession — say, responding to multiple block requests during replication — each send() call would normally trigger a separate write to the underlying stream. That means separate encryption operations, separate system calls, and separate network packets.

Protomux (and individual channels) support corking: a pattern that buffers messages and flushes them as a single batch.

corking-example.js

// Without corking: 100 separate writes
for (const block of blocks) {
  dataMessage.send(block)  // Each send = separate packet
}

// With corking: 1 batched write
mux.cork()
for (const block of blocks) {
  dataMessage.send(block)  // Buffered, not sent yet
}
mux.uncork()  // All 100 messages flushed as one batch

Gotcha: Corking is about performance, not correctness. Messages are still delivered in order whether you cork or not. But for high-throughput scenarios like replicating a large Hypercore, the difference between 1,000 individual writes and 10 batched writes is significant. Hypercore replication uses corking internally.

Compact Encoding: The Wire Format

Every message on a Protomux channel needs to be serialized to bytes for transmission and deserialized on the other end. Hyperswarm uses Compact Encoding — a binary serialization library that's both space-efficient and fast.

The pattern is always three steps:

compact-encoding-example.js

const c = require('compact-encoding')

// Define a message schema
const myMessage = {
  preencode (state, msg) {
    c.uint.preencode(state, msg.type)      // 1. Measure: how many bytes?
    c.string.preencode(state, msg.payload)
  },
  encode (state, msg) {
    c.uint.encode(state, msg.type)          // 2. Write: serialize into buffer
    c.string.encode(state, msg.payload)
  },
  decode (state) {
    return {                                // 3. Read: deserialize from buffer
      type: c.uint.decode(state),
      payload: c.string.decode(state)
    }
  }
}

Preencode calculates the exact byte length needed. Encode writes the data into a pre-allocated buffer. Decode reads it back.

Why not just use JSON? Two reasons:

Property	Compact Encoding	JSON
Overhead	Minimal (varint lengths, raw bytes)	High (key names repeated, quotes, escaping)
Speed	Faster decode (binary, no parsing)	Slower parse (string processing)
Types	Native buffers, uints, fixed arrays	Everything is a string
Consistency	Matches the rest of the Holepunch stack	Foreign to the protocol layer

For a wire protocol that might exchange thousands of messages per second during replication, this matters.

The Full Stack: From UDP to Application

Let's trace a single message through the entire transport stack to see how the pieces fit together:

graph TD
    A["Application writes: 'Hello'"] --> B["Protomux: Route to correct channel"]
    B --> C["Compact Encoding: Serialize to bytes"]
    C --> D["Protomux: Frame with channel ID + message type"]
    D --> E["Secret Stream: Encrypt with XChaCha20-Poly1305"]
    E --> F["UDX: Reliable delivery over UDP"]
    F --> G["Wire: Encrypted bytes on the network"]

    G --> H["UDX: Reassemble reliable stream"]
    H --> I["Secret Stream: Decrypt + verify auth tag"]
    I --> J["Protomux: Demux to correct channel"]
    J --> K["Compact Encoding: Deserialize from bytes"]
    K --> L["Application receives: 'Hello'"]

    style A fill:#22272e,stroke:#539bf5,color:#e6edf3
    style L fill:#22272e,stroke:#539bf5,color:#e6edf3
    style E fill:#22272e,stroke:#a371f7,color:#e6edf3
    style I fill:#22272e,stroke:#a371f7,color:#e6edf3

Figure 2: A message travels down the stack on one side and back up on the other. Encryption happens once at the stream level — individual channels don't re-encrypt.

Notice that encryption happens at the Secret Stream level — below the multiplexing. This means:

All channels share the same encryption session (one handshake, not one per channel)
A new Protomux channel doesn't require a new Noise handshake
Channel identities and protocol names are hidden from eavesdroppers (though traffic analysis — packet sizes, timing patterns — can still leak side-channel metadata)

Feynman Moment: Why encrypt below the multiplexer, not above it? If you encrypted each channel separately, an eavesdropper could observe the number of channels, the timing of messages per channel, and the size distribution of each protocol's traffic. By encrypting the entire multiplexed stream, all of this metadata is hidden. The eavesdropper sees one opaque stream of bytes.

The Tradeoffs

What You Gain	What You Pay
Forward secrecy via ephemeral keys	1 extra message vs. IK pattern
Identity hiding (static keys encrypted)	Cannot authenticate before the handshake completes
Mutual authentication without certificate authority	Must distribute public keys out-of-band for trust
Multiplexed protocols over single connection	Channel pairing complexity
AEAD encryption on every byte	Modest CPU overhead for encryption
Corked batch writes	Must remember to cork/uncork in hot paths

The overhead is real but modest. The Noise handshake adds three messages to connection setup (typically < 100ms combined). The XChaCha20-Poly1305 encryption runs at several GB/s on modern hardware. For a P2P application, the NAT traversal from Part 1 dominates the latency budget — the encryption is effectively free by comparison.

In Practice: Building a Multiplexed Chat

Here's a minimal example that combines everything — Secret Stream for encryption, Protomux for multiplexing, and Compact Encoding for wire serialization:

multiplexed-chat.js

const Hyperswarm = require('hyperswarm')
const Protomux = require('protomux')
const c = require('compact-encoding')
const crypto = require('hypercore-crypto')

const swarm = new Hyperswarm()
// Hash the room name to get a 32-byte topic for discovery
const topic = crypto.discoveryKey(Buffer.alloc(32).fill('heartit-chat-room'))

swarm.on('connection', (encryptedStream, info) => {
  // encryptedStream is already a Secret Stream (Hyperswarm wraps it)
  const mux = Protomux.from(encryptedStream)

  // Create a chat channel
  const channel = mux.createChannel({
    protocol: 'heartit-chat',
    id: Buffer.from('general'),
    onopen () { console.log('Chat channel opened with', info.publicKey.toString('hex').slice(0, 8)) },
    onclose () { console.log('Chat channel closed') }
  })

  // Define a text message type
  const chatMsg = channel.addMessage({
    encoding: c.string,
    onmessage (text) {
      console.log(`[${info.publicKey.toString('hex').slice(0, 8)}] ${text}`)
    }
  })

  channel.open()

  // Read from stdin and send
  process.stdin.on('data', data => {
    chatMsg.send(data.toString().trim())
  })
})

// Join the topic as both server and client
const discovery = swarm.join(topic, { server: true, client: true })
await discovery.flushed()
console.log('Waiting for peers...')

This is ~30 lines of code for an encrypted, authenticated, peer-to-peer chat over a multiplexed connection with NAT traversal. No server, no certificate authority, no monthly bill.

Key Takeaways

Secret Stream wraps any Duplex stream in Noise XX + XChaCha20-Poly1305 encryption. Three handshake messages establish mutual authentication and session keys. After that, libsodium's secretstream encrypts every byte with AEAD.
Noise XX is the right pattern for peer discovery. Neither side needs to know the other's public key in advance. Both static keys are transmitted during the handshake, encrypted under ephemeral keys for identity hiding.
Forward secrecy means compromised keys don't expose past sessions. Ephemeral keypairs are generated per handshake and discarded afterward. Recording traffic today is useless if keys leak tomorrow.
Protomux multiplexes independent protocols over a single encrypted connection. Channels pair by protocol name + id. Each channel has its own message types, lifecycle, and state. Hypercore replication uses hypercore/alpha channels keyed by discoveryKey.
Encrypt below the multiplexer, not above it. This hides the number of active channels, per-channel message timing, and protocol-specific traffic patterns from eavesdroppers.
Cork your writes in hot paths. Batching messages with mux.cork() / mux.uncork() reduces system calls and encryption operations for high-throughput scenarios.

What's Next

We have an encrypted pipe that can carry multiple protocols. Now we need something worth transmitting.

In Part 3, we'll build an append-only log — Hypercore — that uses a flat in-order Merkle tree to make every byte cryptographically verifiable. We'll see how a peer can download a single block out of millions and prove it hasn't been tampered with, using only a handful of hashes and one Ed25519 signature. This is the data structure that everything else in the Holepunch stack is built on.

References & Further Reading

Series: P2P from Scratch — Building on the Holepunch Stack Part 1: The Internet is Hostile | Part 2: Encrypted Pipes (You are here) | Part 3: Append-Only Truth | Part 4: From Logs to Databases | Part 5: Finding Peers | Part 6: Many Writers, One Truth | Part 7: Trust No One | Part 8: Building for Humans

P2P from Scratch — Part 1: The Internet is Hostile

Rahul Garg — Thu, 12 Mar 2026 06:17:15 +0000

"The Internet was done so well that most people think of it as a natural resource like the Pacific Ocean, rather than something that was man-made. When was the last time a technology with a footprint so large was so error-free?" — Alan Kay

Excerpt: You want two computers to talk directly to each other. No server in the middle, no middleman, no monthly bill. Sounds simple — the Internet is a network, after all. But the moment you try it, you discover something uncomfortable: the Internet was never designed for this. Here's why, and how Hyperswarm punches through anyway.

Series: P2P from Scratch — Building on the Holepunch Stack Part 1: The Internet is Hostile (You are here) | Part 2: Encrypted Pipes | Part 3: Append-Only Truth | Part 4: From Logs to Databases | Part 5: Finding Peers | Part 6: Many Writers, One Truth | Part 7: Trust No One | Part 8: Building for Humans

The Problem: Your Computer Doesn't Have an Address

Here's something that should bother you: your laptop is connected to the Internet right now, but nobody can reach it.

Try it. Find your IP address. It's probably something like 192.168.1.47. Now ask a friend on a different Wi-Fi network to send a packet to 192.168.1.47. Nothing happens. That address means nothing outside your home.

The IP address the rest of the world sees — the one your ISP gave your router — belongs to your router, not your laptop. And your router has no idea which of the dozens of devices behind it you're trying to reach. Worse, in many countries your ISP doesn't even give your router a real public IP. They put your router behind their own router, so you're behind two layers of address translation.

This is Network Address Translation — NAT — and it's the reason peer-to-peer connectivity is hard.

Terminology: NAT (Network Address Translation) is a technique where a router rewrites the source IP address of outbound packets and maintains a mapping table so it can route responses back to the correct internal device. It was designed to conserve IPv4 addresses, not to enable direct communication.

Every time you visit a website, your router creates a temporary mapping: "outgoing traffic from 192.168.1.47:52301 should appear as 203.0.113.5:41928 to the outside world." When the website responds to 203.0.113.5:41928, the router checks its table, finds the mapping, and forwards the response to your laptop.

This works perfectly for client-server communication. You always initiate the connection. The server always has a fixed public address. The router's mapping table always has the right entry.

But what if there's no server? What if two laptops, both behind NATs, want to talk to each other?

Neither one has a public address. Neither router has a mapping entry for the other. Any packet sent to either router from an unknown source gets silently dropped.

This is the fundamental problem of peer-to-peer networking. It's not a software bug — it's a consequence of address translation and stateful firewalling.

The Mental Model: Two People in Soundproof Rooms

Imagine two people, Alice and Bob, each in a soundproof room with a locked door. The door only opens from the inside, and only for a few seconds. Neither person can hear the other through the walls.

They want to have a conversation.

If Alice opens her door and shouts, but Bob's door is still closed — he hears nothing. If Bob opens his door a minute later and shouts, Alice's door has already closed — she hears nothing. They could each open their doors a thousand times and never connect.

But if someone outside both rooms — a coordinator — passes each of them a note saying "open your door in exactly 10 seconds," and they both do it at the same moment, their voices travel through both open doors and they connect.

That coordinator is the role a DHT (distributed hash table) plays in peer-to-peer networking. The soundproof room is your NAT. The door opening is your router creating a mapping entry. The simultaneous timing is the critical requirement.

Feynman Moment: Here's where the analogy breaks — and where the real engineering begins. In the real world, "opening the door" doesn't just mean creating a NAT mapping. Different routers create mappings with wildly different rules. Some routers assign the same external port no matter who you're talking to. Others assign a different external port for every destination. Some allow any outside address to send traffic through the mapping. Others only allow the specific address you originally contacted. These differences aren't edge cases — they're the entire battlefield.

How NATs Actually Work (The Four Behavioral Classes)

Not all NATs are created equal. The way your router creates and filters its mapping table determines whether holepunching can work at all.

Terminology: NAT Mapping is the entry your router creates in its translation table when an internal device sends a packet. It links your internal IP:port to an external IP:port and governs what traffic can flow back through.

NAT Type	Mapping Behavior	Inbound Filtering	Holepunch Friendly?
Full Cone	Same external port for all destinations	Any source allowed through	Yes — easiest
Restricted Cone	Same external port for all destinations	Only IPs you've contacted	Yes — with coordination
Port Restricted	Same external port for all destinations	Only IP:port pairs you've contacted	Yes — with precise timing
Symmetric	Different external port per destination IP:port	Only the specific destination	No — port unpredictable

Note on terminology: The four names above (Full Cone, Restricted Cone, Port Restricted, Symmetric) come from RFC 3489 (2003). The later RFC 4787 (2007) replaces this with a two-axis model — mapping behavior (Endpoint-Independent / Address-Dependent / Address-and-Port-Dependent) × filtering behavior — which better captures real-world NATs that don't fit neatly into one of four boxes. Internally, HyperDHT uses a three-level classification — OPEN, CONSISTENT (predictable port mapping), and RANDOM (unpredictable) — which maps to what matters for holepunching: can you predict the port or not?

The first three types share a critical property: the external port stays the same regardless of destination. If your laptop sends a packet to server A and gets mapped to external port 41928, it also uses port 41928 when talking to server B. This consistency is what makes holepunching possible — a coordinator can observe the port from one connection and tell a peer to aim at that same port.

Symmetric NAT breaks this entirely. Every new destination gets a fresh, unpredictable external port, and symmetric NATs typically combine this with address-and-port-dependent filtering — making both mapping and filtering unpredictable. A coordinator can observe the port your router assigned when talking to the DHT, but that port is useless for connecting to another peer — the router will assign a completely different one.

Key Insight: Holepunching is fundamentally about port prediction. If the coordinator can predict what external port your router will use, peers can aim their packets at it. Symmetric NAT makes this prediction impossible.

The Dance: How Holepunching Actually Works

Let's walk through what Hyperswarm does when two peers want to connect. This isn't abstract protocol theory — this is what happens on your network right now.

Step 1: Both Peers Join the DHT

Both Alice and Bob connect to HyperDHT — a Kademlia-based distributed hash table. This establishes their presence in the network and — critically — creates NAT mappings. The DHT nodes can now observe each peer's external IP and port.

Step 2: Signaling via DHT Nodes

Alice wants to connect to Bob. She finds Bob's announcement in the DHT and sends a connection request. But she doesn't send it directly to Bob — she can't, because Bob's NAT would drop it. Instead, she sends it to one of Bob's designated relay nodes in the DHT.

This is a key design choice: Hyperswarm doesn't rely on external STUN/TURN servers like WebRTC does. Instead, the DHT nodes themselves perform the equivalent functions — NAT type detection (STUN's role) and connection relay when holepunching fails (TURN's role). The protocol is different, but the jobs are the same. No single company controls the infrastructure.

Step 3: The Simultaneous Send

The relay delivers Alice's intent to Bob. Now both peers know about each other's external address (IP + port, as observed by the DHT). Both peers simultaneously send UDP packets toward each other's external address.

Here's the critical moment: when Alice sends a packet to Bob's external address, Alice's router creates a mapping entry that says "I'm expecting a response from Bob's IP." When Bob's packet arrives at Alice's router — from Bob's IP — the router matches it against the fresh mapping and lets it through.

The same thing happens on Bob's side. Both doors open at the same moment. The hole is punched.

sequenceDiagram
    participant A as Alice (behind NAT)
    participant AR as Alice's Router
    participant DHT as DHT Relay Node
    participant BR as Bob's Router
    participant B as Bob (behind NAT)

    A->>DHT: 1. "I want to connect to Bob"
    DHT->>B: 2. "Alice wants to connect" (relayed)
    Note over DHT: DHT shares external addresses

    A->>BR: 3. UDP packet → Bob's external addr
    Note over AR: Alice's NAT creates mapping
    B->>AR: 3. UDP packet → Alice's external addr
    Note over BR: Bob's NAT creates mapping

    Note over AR,BR: Both NATs now have mappings for each other

    B-->>AR: 4. Packet arrives, matches mapping ✓
    AR-->>A: 4. Forwarded to Alice
    A-->>BR: 4. Packet arrives, matches mapping ✓
    BR-->>B: 4. Forwarded to Bob

    Note over A,B: Direct P2P connection established

Figure 1: The holepunching dance. Both peers must send before either receives.

Implementation detail: The diagram above shows the logical flow. In practice, HyperDHT sends multiple probe rounds with retries — the first packets sent to an unopened NAT mapping are expected to be dropped. The holepunch succeeds when at least one packet from each side arrives after the other side's outbound packet has created the necessary mapping. This is why timing coordination matters more than single-packet delivery.

Note: All of this refers to UDP holepunching. Hyperswarm uses UDP for the holepunch dance because UDP NAT mappings are simpler and more predictable. TCP holepunching is significantly harder — it requires simultaneous SYN packets and many NATs don't support it reliably. This is why Hyperswarm establishes the UDP path first and then upgrades it to a reliable, encrypted stream.

Step 4: Encrypted Stream

Once the UDP path is established, Hyperswarm upgrades the connection to a reliable, encrypted stream using Secret Stream — a Noise XX handshake with Ed25519 keypairs, followed by libsodium's AEAD encryption for all payload data. We'll cover this in detail in Part 2.

Gotcha: The timing requirement isn't just "roughly at the same time." NAT mappings have expiry timers. If Alice sends her packet but Bob's router takes too long to relay the signal, Alice's mapping may expire before Bob's packet arrives. Connection failures that look like "peer unreachable" are often timing desynchronization in disguise.

When the Dance Fails: Symmetric NAT and Relay Fallback

Holepunching works when at least one side has a predictable port mapping. If Alice is behind a symmetric NAT but Bob is behind a cone or restricted NAT, Bob's external port is still predictable — so the holepunch can target it. Alice's side creates a fresh mapping for the outbound packet to Bob, and Bob's response arrives at that mapping. One predictable side is enough.

Relay is only needed when both peers are behind randomized (symmetric) NATs. Neither side can predict the other's port, so there's no target to aim at. No amount of timing coordination can overcome both ports being unpredictable.

Hyperswarm handles this with relay fallback: the connection routes through a DHT node that both peers can reach. Each peer can specify up to 3 relay nodes. The data still flows — just through an intermediary.

Scenario	NAT A	NAT B	Method	Result
Best case	Full Cone	Full Cone	Direct holepunch	Low latency, direct path
Common case	Restricted	Port Restricted	Coordinated holepunch	Slightly higher latency
One-sided	Symmetric	Restricted	Direct holepunch	Works — B's port is predictable
Worst case	Symmetric	Symmetric	Full relay	Both ports unpredictable, must relay

On typical consumer networks, Holepunch achieves roughly 95% direct connections and only ~5% relayed. The ~5% happens specifically when both peers are on randomized NATs — since it requires both sides to be unpredictable simultaneously, the probability is low. But it's not uniformly distributed: environments where symmetric NATs are common (like corporate networks) see a higher local relay rate when peers within those environments connect to each other. The application should handle both paths transparently.

Key Insight: The fallback isn't a failure — it's a design requirement. Any P2P system that doesn't account for symmetric NAT will silently fail for a significant fraction of users. Hyperswarm makes the fallback automatic so applications don't need to handle it manually.

Beyond NAT: What Makes Hyperswarm's DHT Different

The DHT isn't just a signaling helper — it's the peer discovery layer, and it has its own engineering challenges.

Sybil Resistance via Node ID Derivation

In a standard Kademlia DHT, nodes choose their own IDs. An attacker could generate thousands of IDs strategically positioned near a target, surrounding it with malicious nodes. This is a Sybil attack.

dht-rpc prevents this by deriving node IDs from the node's network identity: nodeID = hash(publicIP + publicPort). You can't choose your ID — the network determines it from your address. An attacker would need control of specific IP addresses to position themselves near a target in the keyspace.

This is one defense layer. Round-trip tokens prove IP ownership (preventing spoofing), and the ephemeral-to-persistent transition (described below) prevents rapid routing table pollution.

The Ephemeral-to-Persistent Transition

New nodes don't immediately become permanent members of the DHT's routing tables. They start in ephemeral mode — participating in queries but not stored in other nodes' routing tables.

After approximately 20–30 minutes of stable uptime (the base threshold is 240 ticks × 5 seconds, but NAT assessment and network conditions add overhead), the node transitions to persistent mode and takes a permanent position in the routing table. After a sleep/wake cycle, this timer resets to ~60 minutes.

This protects the DHT from short-lived nodes churning the routing tables and from attackers spinning up thousands of nodes to flood the network. If you're running a server on an open NAT, you can bypass this with ephemeral: false, but for consumer devices behind NATs, the transition period is a feature, not a limitation.

The Tradeoffs: Nothing Is Free

Holepunching and DHT-based discovery solve the fundamental connectivity problem, but they come with costs.

What You Gain	What You Pay
No central server dependency	Connection setup is slower (DHT lookup + holepunch negotiation)
No monthly infrastructure bill	~5% of connections relay through intermediaries (only when both sides are on randomized NATs)
Resistant to single-point-of-failure	First connection takes seconds, not milliseconds
Works across ISPs and countries	Both-sides-symmetric connections get relay latency
DHT nodes are the infrastructure	~20–30 minute warmup for new DHT nodes (~60 min after wake)

The connection setup cost is a one-time tax. Once the hole is punched, the direct UDP path is as fast as any other Internet connection. But that initial negotiation — DHT lookup, signaling, simultaneous send, handshake — takes real time. Your UX needs to account for this (we'll cover P2P UX design in Part 8).

In Practice: Watching It Happen

You can observe Hyperswarm's holepunching in action with a minimal script. Install the module and create two peers that discover each other via a shared topic:

holepunch-demo.js

const Hyperswarm = require('hyperswarm')

// Both peers must join the same topic — a 32-byte buffer.
// Use a fixed value so both machines connect to the same swarm.
const topic = Buffer.from(
  'a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6a7b8c9d0e1f2a3b4c5d6a7b8c9d0e1f2',
  'hex'
)

const swarm = new Hyperswarm()
swarm.on('connection', (conn, info) => {
  console.log('Connected to peer!', info.publicKey.toString('hex').slice(0, 8))
  conn.on('data', data => console.log('Received:', data.toString()))
  conn.write('Hello from ' + (process.argv[2] || 'anonymous'))
})
const discovery = swarm.join(topic, { server: true, client: true })
await discovery.flushed()
console.log('Announced on topic, waiting for peers...')

Note: Code examples in this series use require() with top-level await for clarity. To run them, either wrap the body in (async () => { ... })() or save with an .mjs extension and use import instead of require. The Pear Runtime supports this syntax natively.

Run this same script on two different machines (or two different networks) — e.g., node holepunch-demo.js Alice on one and node holepunch-demo.js Bob on the other. Because the topic is hardcoded, both peers discover each other automatically. You'll see the connection event and the data exchange. If both peers are behind randomized (symmetric) NATs, Hyperswarm silently falls back to relay — the connection event fires either way. If only one side is symmetric, holepunching still works directly.

Gotcha: If you run both peers on the same machine or the same LAN, you're not testing holepunching at all — you're testing local discovery. Real holepunching only happens across NAT boundaries. To test properly, use two different networks or a cloud VM as the second peer.

Key Takeaways

NAT is the fundamental obstacle to P2P connectivity. Your device doesn't have a reachable address. Your router drops unsolicited inbound packets. This isn't a bug — it's how the Internet was designed.
Holepunching is a timing dance. Both peers must create outbound NAT mappings simultaneously so that each peer's inbound packet matches the other's fresh mapping. The DHT coordinates this timing.
Both-sides-symmetric is the only case that requires relay. If only one peer is behind a symmetric NAT, holepunching still works — the other side's port is predictable. Relay is only needed when both peers have randomized port mappings, making prediction impossible on both ends.
Hyperswarm's DHT is more than a phone book. Node IDs derived from hash(IP + port) resist Sybil attacks. Ephemeral-to-persistent transitions resist routing table pollution. DHT nodes double as relay infrastructure.
Budget for ~5% relayed connections. On consumer networks, Holepunch achieves ~95% direct connectivity. The ~5% relay fraction occurs specifically when both peers are on randomized NATs — since it requires both sides to be unpredictable, the probability is low. But it's not uniformly distributed: environments where symmetric NATs are common (corporate networks) see higher local relay rates. Your architecture and UX must handle relayed connections as a first-class path, not an error state.

What's Next

We've established that two peers can find each other and create a connection path — even through hostile network conditions. But that path is just raw UDP packets. Anyone between the two peers can read them, modify them, or inject fake ones.

In Part 2, we'll look at how Hyperswarm turns that raw UDP path into an encrypted, multiplexed communication channel using the Noise protocol, Secret Stream, and Protomux. We'll see how a single encrypted connection carries multiple independent protocol channels — and why that matters when you start replicating data structures in Part 3.

References & Further Reading

Series: P2P from Scratch — Building on the Holepunch Stack Part 1: The Internet is Hostile (You are here) | Part 2: Encrypted Pipes | Part 3: Append-Only Truth | Part 4: From Logs to Databases | Part 5: Finding Peers | Part 6: Many Writers, One Truth | Part 7: Trust No One | Part 8: Building for Humans