typress
An editorial workshop.日本語

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.hello
  • capabilities: 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 with http:fetch:allowlist.

Permissions

  • posts:read / posts:write: read and write posts
  • hooks:register: register for events
  • settings:read:own / settings:write:own: the plugin's own settings
  • http:fetch:allowlist: talk only to destinations in httpAllowlist

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 fetch for it, over https and only to httpAllowlist. 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 dev

Sign 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.