Native

What is the native bridge?

Some capabilities live in React Native modules rather than JavaScript. The native API resolves those modules and exposes the handles Unbound uses most often. The loader also installs two JSI globals:

NativePlugin is the versioned generic native plugin bridge.
NativePlatform contains platform-wide helpers that are not plugin-specific.

Feature-specific native implementations do not belong in either global. Plugins use the generic bridge to implement their own behavior in JavaScript.

Resolving native modules

A native module’s name varies across Discord versions. getNativeModule checks each candidate in order against both NativeModules and the TurboModule registry.

import { native } from '@unbound-app/api';

const FileManager = native.getNativeModule('NativeFileModule', 'DCDFileManager', 'RTNFileManager');

Built-in handles

BundleInfo, BundleManager, DeviceInfo, and the file manager are resolved for you. Prefer fs for file operations because it handles paths and encodings.

Reloading

reload() persists pending settings before asking the bundle manager to reload.

import { native } from '@unbound-app/api';

await native.reload();

Platform helpers

NativePlatform is optional because it is only present inside a running Unbound loader environment. It exposes device information, app provenance, and Hermes bytecode evaluation.

import { native } from '@unbound-app/api';

const model = native.NativePlatform?.device.getDeviceModel();
const source = native.NativePlatform?.app.getAppSource();

NativePlatform.evaluateBytecode accepts a Hermes ArrayBuffer and evaluates it in the current runtime. It throws when the argument is not valid Hermes bytecode or when evaluation fails.

Generic plugin bridge

NativePlugin is the public JavaScript view of the native ABI. The loader publishes it as globalThis.NativePlugin; the client scopes it to each plugin according to the manifest capabilities.

import { native } from '@unbound-app/api';

export default {
	start(context) {
		const bridge = context?.native;
		if (!bridge) return;

		const messageClass = bridge.objc.getClass('DCDMessage');
		if (!messageClass) return;
		const message = bridge.objc.alloc(messageClass);
		bridge.objc.call(message, 'content');
	},
};

The bridge exposes these version and capability fields:

string

The version of the JavaScript API consumed by plugins.

string

The version of the native ABI implemented by the loader.

string[]

The native capabilities available in this loader build.

Objective-C operations

The objc namespace supports class lookup, allocation, selector calls, superclass calls, ivar access, associated objects, registered structs, arrays, data conversion, and generic hooks.

const { native } = pluginContext;
const cell = native.objc.getClass('DCDMessageTableViewCell');

const token = native.objc.hook(cellName, 'prepareForReuse', {
	before(context) {
		const viewModel = native.objc.getIvar(context.self, '_viewModel');
		if (viewModel) native.objc.call(viewModel, 'description');
	},
});

Hook arguments are borrowed until the callback returns. Retain values explicitly when they need to outlive the callback. original() is synchronous only when the callback runs on the hook thread; cross-thread calls fail closed to avoid deadlocks. Disposing a plugin context removes its hooks, associations, and bridge resources, and all later calls through that context are rejected. call runs on the current runtime thread. invoke accepts an explicit thread policy such as current or main; unsupported synchronous crossings fail with a structured error. Objective-C NSData results are returned as Uint8Array values. Native bridge failures are JavaScript errors with a stable code property; native runtime failures use NATIVE_BRIDGE_ERROR. Client-side negotiation errors distinguish unavailable bridges, missing capabilities, disposed scopes, and unsupported minimum API versions through their respective error codes.

Raw FFI operations

The ffi namespace resolves symbols from already-loaded images and invokes non-variadic signatures made from supported scalar, pointer, Objective-C, and registered struct types.

const symbol = native.ffi.symbol('SomeLoadedSymbol');
if (symbol) {
	const value = native.ffi.call(
		symbol,
		{
			returnType: 'i32',
			args: ['pointer'],
		},
		pointer,
	);
}

The v1 bridge does not expose arbitrary memory access, dlopen, variadic calls, unknown structs, vectors, unions, bitfields, or plugin-supplied native closures.

Fabric surfaces

The fabric namespace mounts a registered React Native component into an existing UIKit view. This is the bridge used when a plugin needs Discord’s real native message component rather than a second JavaScript-only approximation.

const surface = native.fabric.mount(container, 'MessageLinkSurface', {
	surfaceId,
	targetMessageId,
});

const bounds = native.fabric.measure(container);
native.fabric.setSize(
	surface,
	{ width: bounds.width, height: 1 },
	{ width: bounds.width, height: 480 },
);
native.fabric.setFrame(surface, { x: 0, y: 120, width: bounds.width, height: 168 });
native.fabric.update(surface, { targetMessageId });
native.fabric.unmount(surface);

Fabric surfaces are created and destroyed on the UIKit main thread, while the JavaScript API remains synchronous and fail-closed on timeout. Surface handles are owned by the plugin scope and are unmounted automatically when the scope is disposed.

Capabilities and lifecycle

Declare only the capabilities a plugin needs in its manifest:

native.objc.classes
native.objc.invoke
native.objc.ivars
native.objc.associations
native.objc.hooks
native.ffi.symbols
native.ffi.call
native.fabric.mount

The addon manager validates capability names and the optional minimum API version before calling start(context). context.native is scoped to the plugin. context.dispose() is called during stop, unload, reload, and failed startup cleanup. Existing plugins can continue to accept a context-less start function, but new plugins should use the scoped context so native resources cannot escape their lifecycle.

Overview

Loader

Addons

Plugins

Themes

Icon Packs

Developer API

What is the native bridge?

Resolving native modules

Built-in handles

Reloading

Platform helpers

Generic plugin bridge

Objective-C operations

Raw FFI operations

Fabric surfaces

Capabilities and lifecycle

​What is the native bridge?

​Resolving native modules

​Built-in handles

​Reloading

​Platform helpers

​Generic plugin bridge

​Objective-C operations

​Raw FFI operations

​Fabric surfaces

​Capabilities and lifecycle

What is the native bridge?

Resolving native modules

Built-in handles

Reloading

Platform helpers

Generic plugin bridge

Objective-C operations

Raw FFI operations

Fabric surfaces

Capabilities and lifecycle