Build a plugin
A plugin is a manifest.json plus one JavaScript file. A sample lives in the repo at examples/plugin-greeter.
manifest.json
{
"id": "com.example.hello",
"version": "0.1.0",
"displayName": "Hello",
"minTypressVersion": "0.0.0",
"entry": "index.js",
"capabilities": ["posts:read", "posts:write"],
"permissionReasons": {
"posts:write": "Creates one welcome post on first run"
}
}id: reverse-domain, e.g.com.example.hellocapabilities: the permissions you want. Whoever installs it approves them one by one.permissionReasons: a reason per permission (up to 200 characters), shown as "Author's reason" on the approval screen.httpAllowlist: allowed destinations. Required withhttp:fetch:allowlist.
Permissions
posts:read/posts:write: read and write postshooks:register: register for eventssettings:read:own/settings:write:own: the plugin's own settingshttp:fetch:allowlist: talk only to destinations inhttpAllowlist
index.js
export default async function init(host, { granted }) {
if (!granted.includes("posts:read") || !granted.includes("posts:write")) return;
const existing = await host.posts.read.list({ limit: 1 });
if (existing.length === 0) {
await host.posts.write.create({ title: "Hello", slug: "hello", body: [], status: "draft" });
}
}granted holds only the permissions that were actually approved. APIs for the rest are undefined, so check before using them.
Where it runs
- In its own process, locked down by Landlock and seccomp on Linux and sandbox-exec on macOS.
- No direct network. typress performs
fetchfor it, over https and only tohttpAllowlist. Internal addresses are refused. Requests are capped at 1 MiB and responses at 5 MiB, with a 15-second timeout. - Three failed starts in a row disable it automatically.
Pack and sign
bun tools/tpkg/src/main.ts pack examples/plugin-greeter
bun tools/tpkg/src/main.ts sign examples/plugin-greeter/com.typress.greeter-0.1.2.tpkg --key devSign updates with the same key and install them the same way. A different key is treated as a different author and the update is refused.