Publish a plugin

A plugin is a repository with a manifest.json in its root and the files an instance loads beside it: hooks, migrations, public files, and a main.js when it does more than hooks. Nobody builds anything. Once listed, the marketplace records the commit it audited, an instance fetches the files at that commit and verifies them, and anyone installs it with voidbase plugins add <name>.

What the repository needs

voidbase-plugin-echo/
├─ manifest.json    name, version, tier, the voidbase range, provides, requires, collections, config
├─ main.js          what the plugin does, when it does more than hooks: plain JavaScript, default export
├─ lib/             modules main.js imports, if any
├─ pb_hooks/        hooks, loaded after the project's own
├─ pb_migrations/   its schema, if it has one
├─ pb_public/       files it serves, if any
├─ LICENSE          one GitHub can identify
└─ README.md        what it does for someone running voidbase

{
  "name": "echo",
  "version": "0.1.0",
  "tier": "community",
  "voidbase": ">=1.0.0",
  "provides": [],
  "requires": []
}

The manifest is what voidbase's loader reads, checked with its own checkManifest: the name (^[a-z][a-z0-9-]*$, and a marketplace serves each name once), the version, the tier, the voidbase range, and the interfaces it provides and requires, which may be ones voidbase defines or names of your own (a near-miss of one it defines is refused as a typo). main.js is plain JavaScript, because nothing is compiled: its default export is the plugin (apply, and info if it reports anything), and the instance attaches the manifest to it when it loads. It and lib/ may import only what an instance provides, @voidbase-cloud/voidbase/* and hono, plus their own files; Node built-ins are out because an instance may be a Worker. The plugins page has the format, the interfaces, owning collections and the deploy-time half; the official plugins in voidbase's own repository (packages/plugin-*, one directory each) show the shape.

• The repository is public.
• It has a licence GitHub can identify. A LICENSE file GitHub cannot recognise counts as none.
• It has a README saying what the plugin does for someone running voidbase.

What the marketplace does with it

On approval the pipeline audits what an instance would load at the repository's current commit: public, a licence, a manifest.json valid against voidbase's checkManifest, something to load, nothing to compile, imports only of what an instance provides and nothing outside the plugin, not oversized, nothing alarming. Then it writes the version record naming that commit (and the directory, for a repository holding several plugins) and regenerates the index. Nothing is installed, built, bundled or hosted. What every check found is recorded with the version and shown on the listing, so you can read it and disagree with any one of them. A published version never changes; a change is a new version.

Submitting

1. Open the plugin submission form: the repository, a title, a one-line summary, a category and tags.
2. The audit comments on the issue within a minute or two. If it flags something, edit the issue: that runs it again.
3. A maintainer labels it approved. The commit is audited and recorded in the registry, which is pushed; the push deploys, the issue is answered and closed, and the plugin is installable by name.

Versions

A new version is a new commit of your repository with a bumped version in manifest.json, tagged. The marketplace's daily check asks every listed repository for its tags and queues the versions it does not serve yet, each audited the same way and held for a maintainer to approve; a maintainer can also record one by hand against a ref. An instance moves with voidbase plugins update, or from inside with its installer, and the loader refuses a version whose voidbase range does not fit.

Removal

Open an issue titled [remove] owner/name. Once a maintainer approves it, the entry leaves the listing and the served versions leave the registry, in one commit. Instances that installed it keep what they have. A listing can also be removed if the repository disappears, becomes something other than what was listed, or turns out to be someone else's work.

If you would rather ask before you spend time on it, we are on Discord. If you have built a plugin system before and any of this looks wrong, that is the most useful thing you could tell us.