@owncast/plugin-sdk

SDK for authoring Owncast plugins in JavaScript or TypeScript. Plugins ship as source and run sandboxed inside the Owncast server, on a JavaScript engine the host embeds, so there's no wasm toolchain to install.

Most authors don't install this directly, instead, scaffold a new project with npx create-owncast-plugin@latest <slug> and the generated package.json already lists it as a dependency.

Quick start

npx create-owncast-plugin@latest my-plugin
cd my-plugin
npm install     # postinstall fetches the prebuilt test/serve host binaries
npm run build   # bundles src/plugin.{js,ts} into my-plugin.js
npm test        # builds, then runs scenarios from __tests__/
npm run package # zips manifest + my-plugin.js + assets + icon.png into my-plugin.ocpkg

Then install my-plugin.ocpkg in Owncast. From the admin's Plugins page click Upload plugin and pick the file, or copy it directly to the server's data/plugins/ directory. Toggle Enabled on the plugin's row to load it.

Writing a plugin

const { definePlugin, owncast, filter } = require("@owncast/plugin-sdk");

module.exports = definePlugin({
  onChatMessage(msg) {
    owncast.chat.send(`echo: ${msg.body}`);
  },

  filterChatMessage(msg) {
    return msg.body.includes("spam") ? filter.drop("spam") : filter.pass();
  },
});

Declare the permissions your plugin uses (chat.send for the example above) in plugin.manifest.json. The full author guide covers every event handler, host API, and the testing harness:

→ Owncast Plugin Author Guide

What's in the package

• index.js, runtime: definePlugin, the owncast.* host wrappers, the filter constructor.
• index.d.ts, TypeScript declarations for editor autocomplete on every event payload and host API.
• testing.js, JS test API (runScenarios) for writing __tests__/*.test.js with the full ergonomics of JavaScript instead of static JSON.
• bin/owncast-plugin, CLI: build, test, serve, package subcommands.
• scripts/postinstall.js, downloads the Go test/serve host binaries on install. Plugins ship as source and run on the engine the host embeds, so no wasm toolchain (extism-js, binaryen) is fetched (that's a maintainer-only dependency of the engine build).

License

MIT