Plugin system

Overview

Each QVAC AI capability maps to a built-in plugin in the SDK. This lets you enable only what you need for your project and reduce your application's final bundle size.

In addition, you can add custom plugins — both your own and community ones — that extend QVAC's capabilities. In both cases, you'll use the QVAC configuration file and then bundle either with QVAC CLI or programmatically via @qvac/sdk/commands.

Built-in plugins

Catalog

All the built-in plugins you can select, along with the AI tasks that depend on each one:

Enabling

{
  "plugins": [
    "@qvac/sdk/llamacpp-completion/plugin",
    "@qvac/sdk/onnx-ocr/plugin"
  ]
}

qvac bundle sdk

Only the selected plugins are included in your bundle, significantly reducing your application size. If plugins is omitted or an empty array, it bundles all built-in plugins by default.

Custom plugins

Custom plugins are consumed as npm packages. Install the package, enable it in your qvac.config.* file like any built-in plugin, then import and use its API alongside the SDK's regular API.

Enabling

npm i qvac-echo-plugin

{
  "plugins": [
    "@qvac/sdk/llamacpp-completion/plugin",
    "qvac-echo-plugin/plugin"
  ]
}

qvac bundle sdk

Usage

Custom plugins are consumed as npm packages. Install the package, enable it in your qvac.config.* file like any built-in plugin, then import and use its API alongside the SDK’s regular API.

import { loadModel, unloadModel } from "@qvac/sdk";

// 1. Import the API you need from the custom plugin package:
import { echo, echoStream } from "qvac-echo-plugin";

// 2. Load the model(s) required by the custom plugin:
const modelId = await loadModel({
  modelSrc: "/path/to/echo-model.bin",
  modelType: "echo",
});

// 3. Call functions exposed by the custom plugin API:
const result = await echo({ modelId, message: "Hello, plugin system!" });
console.log(result);

for await (const char of echoStream({ modelId, message: "Streaming test!" })) {
  process.stdout.write(char);
}

await unloadModel({ modelId });

Runtime registration on Bare

The plugins array in qvac.config.* is bundle-time configuration — it controls which addons get packed into your worker. That is separate from runtime registration, which determines the plugins live in the worker process when an SDK call runs.

On Node.js and Expo the SDK spawns a worker that auto-registers the full built-in set, so you never register manually. Bare runs in-process with no spawned worker, so nothing auto-registers — register the plugins you use before the first SDK call:

import { plugins } from "@qvac/bare-sdk";
import { llmPlugin } from "@qvac/bare-sdk/llamacpp-completion/plugin";

const sdk = plugins([llmPlugin]); // or registerPlugin(llmPlugin) from "@qvac/bare-sdk/plugins"

Calls made before any plugin is registered raise WorkerPluginsNotRegisteredError.

Notes

• In qvac.config.*, if plugins is omitted or set to an empty array, the SDK bundles all built-in plugins. If plugins is set, it bundles only the listed plugins.
• Each plugin maps to one QVAC addon.
• Write a custom plugin.
• Programmatic bundling: you can also prepare and validate the SDK bundle programmatically via API from a Node script. For example:

import { bundleSdk, verifyBundle } from "@qvac/sdk/commands";

await bundleSdk({
  projectRoot: process.cwd(),
  configPath: "./qvac.config.json",
  quiet: true,
});

const result = await verifyBundle({
  projectRoot: process.cwd(),
  addonsSource: "./qvac/worker.bundle.js",
  hosts: ["android-arm64", "ios-arm64"],
});