Guide · v0.13.8

Plugins

A plugin is an npm package that adds commands to an app, optionally over a native library of its own: Rust, C, Zig or anything with a C ABI.

Using a plugin

app.tsx
import hello from "tarve-plugin-hello";

const app = createApp(View, { plugins: [hello] });
await hello.client(app).add(2, 3);   // typed: Promise<number>
await app.invoke("hello.add", 2, 3); // the same command by id

app.invoke rejects when no installed plugin registered the command.

Writing one

definePlugin takes the package name, its semver version and setup(ctx), which runs once per app before the window opens. The functions setup returns become commands named <namespace>.<name>; ctx.registerCommand adds more.

plugin.ts
import { definePlugin } from "@tarve/core";

export default definePlugin({
  name: "tarve-plugin-hello",
  version: "0.1.0",
  namespace: "hello",
  tarvePluginApi: 1,
  root: import.meta.dirname,
  setup(ctx) {
    const lib = ctx.loadLibrary({ hello_add: { args: ["i32", "i32"], returns: "i32" } });
    ctx.onReady(() => { /* the window is up */ });
    ctx.onClosed(() => { /* release resources; libraries close after this */ });
    ctx.onOpenUrl(url => { /* the app's protocols, as app.onOpenUrl */ });
    return { add: (a: number, b: number) => lib.symbols.hello_add(a, b) };
  },
});
ContextDoes
ctx.loadLibrary(symbols) / ctx.loadLibrary(pathsByTarget, symbols)Opens the library with the runtime's FFI: bun:ffi, node:ffi (Node.js 26.10+) or tjs:ffi (txiki.js); elsewhere it throws PluginFfiUnsupportedError. Types: i8…u64, f32, f64, bool, ptr, buffer, void.
ctx.request(command, { expect, timeoutMs })Sends a protocol request to the Tarve runtime and checks the answer type.
ctx.onReady, ctx.onClosed, ctx.onOpenUrl, ctx.onOpenFilesLifecycle hooks.
ctx.registerCommand(name, fn)Adds a command.

package.json

The tarve field makes a package discoverable (discoverPlugins, loadPlugins) and tells tarve build which library to embed for each target.

package.json
{
  "tarve": {
    "tarvePluginApi": 1,
    "plugin": "./dist/plugin.js",
    "native": {
      "win32-x64": "./native/hello.dll",
      "linux-x64": "./native/libhello.so",
      "darwin-arm64": "./native/libhello.dylib",
      "android-arm64": "./native/android/libhello.so"
    }
  }
}

tarve build and tarve package (Bun, Node.js and txiki.js builds) embed the target's library of every plugin among the app's dependencies and extract it once on first use; macOS bundles get it in Contents/Frameworks. A declared library missing for the build target fails the build.

Android APKs pack the android-arm64 / android-x64 library as lib/<abi>/, so its file must be named lib<name>.so (Cargo's cdylib name for cargo ndk -t arm64-v8a build --release). On the default QuickJS-ng engine, ctx.loadLibrary calls functions with up to 8 integer/pointer and 8 floating-point arguments on arm64 (6 and 8 on x86_64); a declaration that needs more fails when the library opens, and variadic C functions are not supported. 64-bit results above 253 come back as BigInt: on arm64 Android that includes heap pointers, whose top byte holds a tag, so pass ptr values back as they came. --runtime bun uses bun:ffi. examples/plugin-hello/android-smoke.tsx checks all of this on a device.

tarvePluginApi is the major version of the plugin API (currently 1). Additions keep the number; Tarve refuses plugins that ask for a newer one. The repository's examples/plugin-hello is a complete plugin with a Rust cdylib, a TypeScript wrapper, a demo and tests.