Plugins Not built yet

A plugin is code somebody else wrote that you install into your instance by name, instead of copying a hook file out of a gist and hoping. pb_plugins does not exist yet: there is no format, no loader, and nothing to install. This page is the design, written down so it can be argued with before it is built.

What one will be

A directory beside your own code, holding things you did not write. That placement is the whole idea: a plugin registers hooks, owns collections and adds panel screens the same way your own code does, so nothing about it is a special case at runtime.

my-instance/
├─ pb_hooks/            your own code
├─ pb_migrations/       your own schema
└─ pb_plugins/          installed plugins, one directory each
   └─ backups-r2/
      ├─ plugin.json    what it is, what it needs, what it may touch
      ├─ hooks/         handlers it registers
      ├─ migrations/    collections it owns
      └─ panel/         screens it adds to the admin panel

A stack app calls it vb_plugins, beside vb_hooks, because that is what the stack calls everything else.

Using one

voidbase plugins                 # what is installed
voidbase plugins add backups-r2  # install by name from the marketplace
voidbase plugins update          # bring them up to date
voidbase plugins remove backups-r2

Installed by name, versioned, and recorded in a lock file, so what is running is what your repository says is running. Each page under Run an instance has a section on what this looks like for that shape, because a downloaded executable, a committed project and a cloud instance cannot all install things the same way.

What is decided

• Plugins live in a directory beside your hooks, installed and updated by name rather than copied in.
• A plugin declares what it needs and can add routes, hooks, collections and admin panel screens.
• Core plugins ship with voidbase, official ones are ours and versioned with it, and anyone can publish their own through the marketplace or a registry of their own.

What is not

• The manifest: what plugin.json declares, and how strictly.
• Permissions. A plugin that can add routes and read collections can do damage. What it has to ask for, and how that is checked against what it actually does, is the question that decides whether any of this is safe to install, and it is the one we are least sure about.
• Versioning: what happens to an installed plugin when voidbase changes underneath it.
• Isolation: whether a plugin runs in the same isolate as your hooks, and what its failures do to yours.

What you can do now

Register the plugin you would write. The form asks what it would need from voidbase, and those answers are what the format gets designed around. A format designed against imagined plugins fits none of the real ones, which is the whole reason this page exists before the code does.

If you have built a plugin system before and something above looks wrong, that is more useful than a feature request. The roadmap carries the design as it stands.