# 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

```tsx title="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.

```tsx title="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) };
  },
});
```

| Context | Does |
| --- | --- |
| `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.onOpenFiles` | Lifecycle 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.

```tsx title="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.

---

Tarve v0.13.8 · HTML version: https://tarve.dev/docs/plugins · Index for agents: https://tarve.dev/llms.txt
