DocsPlugins
Plugins
Install plugins from a registry, with versions, checksums and requirements, write your own, and keep them in a registry of your own, public or private.
Plugins add features to Sluurp without a new release of it: Pages, Forms, AI, billing, an invoice format for a country, a file type, a database Sluurp doesn’t speak. They are installed into an app from a registry, at exact versions, checked by their checksums, with the plugins they require. To install one:
sluurp plugin add peppol # the newest version
sluurp plugin add peppol@^1 # the newest 1.x
sluurp plugin list # what is installed, and what the registries have
sluurp plugin update # each to the newest its range allows
sluurp plugin update peppol # only peppol
sluurp plugin remove peppolFeatures include:
- Exact versions, checked by their checksums, with npm-style ranges for dependencies
- Routes, browser code, admin screens, hooks, jobs and migrations, laid out like an app
- Plugins written in any language, as WebAssembly or as a program
- Commercial plugins, sealed and sold through the Marketplace
- Registries of your own, public or private
Install plugins
Run them in the app’s folder, or give it with --app ./app. A plugin from Sluurp’s registry is a package in the app’s package.json, pinned by bun.lock; one from another registry, or from a folder, is listed under "sluurp" in the same file. The server keeps the installed files in its own store, with each plugin’s version, its files’ checksums and what it requires, so the app’s folder holds no lock of its own. Commit package.json and bun.lock: a new server installs exactly the same versions, and a file that differs from its checksum is refused.
Adding a plugin never moves the ones you already have: they stay at their versions until you update them. plugin update with names moves only those plugins, and you can name one that another plugin brought in, such as blocks for Pages; plugin update alone moves them all.
A plugin can also come from a folder on your machine, such as one you are writing or a sealed build you were given:
sluurp plugin add ../my-plugins/invoicesIt is copied in as it is and listed in package.json as "invoices": "file:../my-plugins/invoices", so update leaves it alone and a new server copies it from there again; the plugins it requires come from the registry as usual.
By default, plugins come from Sluurp’s registry at https://sluurp.org/registry, the one the Marketplace shows.
Versions and dependencies
Each release of a plugin is a git tag in its registry, name@version. Its plugin.json says which Sluurp versions it runs on, and lists its dependencies in deps, with npm-style ranges. A bare name is another plugin. A name with npm: before it is an npm package, added to the app with bun add.
{
"name": "acme-invoices",
"version": "1.2.0",
"main": "acme-invoices.ts",
"sluurp": ">=0.2.0",
"deps": {
"peppol": "^1.0.0",
"npm:pdfmake": "^0.2.20",
"font:Inter": ""
}
}Installing resolves the whole graph before it writes a single file. That graph is what you ask for, the plugins those need, and every package any of them names. Each plugin gets the highest version every range allows.
A plugin from another registry is named with that registry first: "acme/plugins:invoices": "^2.0.0". Its registry is read only when the app already takes plugins from it (sluurp plugin registry add acme/plugins). Otherwise the install stops and says so, so a dependency never brings in a source you didn’t choose.
Nothing is installed when a dependency is missing or when two ranges leave no version. The error names each plugin and the range it asked for.
A plugin’s npm packages ("npm:pdfmake": "^0.3" in its deps) are added to the app’s package.json with bun add. Plugins then import them by name, in browser code and server code alike: import pdfMake from "pdfmake".
Removing a plugin that another plugin needs is refused. Removing one also removes the plugins nothing needs any more.
Routes
A plugin answers at addresses of its own when its plugin.json claims them:
{
"routes": [
{ "base": "/api/billing" },
{ "base": "/api", "paths": ["shared/*"], "maxBody": 10 }
]
}A request under base that matches one of paths goes to functions/api.ts, or to the function named by fn. paths defaults to **. In a path, * matches one segment and ** matches any number of segments. The function’s router sees the part of the address after base: /api/billing/invoices/1 reaches it as /invoices/1. maxBody is the largest request body in MB; by default, 2.
Sluurp’s own routes always come first. When two plugins claim the same address, the longer base wins. Routes work as soon as a plugin is installed, without a restart.
Private hosts
A plugin’s code can fetch any address unless the admin turns on Public addresses only. So that it still reaches a private host then, such as a model running on the same machine, its plugin.json names the host:
{ "fetch": ["localhost", "127.0.0.1"] }Installing the plugin allows these hosts, and the Marketplace shows them on the plugin’s page. A host the admin blocks under Outbound requests stays blocked.
Browser code
A plugin’s client/index.ts (or .js) is what the app imports as plugin:<name>. A plugin can add its own part to the browser SDK there, so the app calls it on the client it already has:
import { Sluurp } from "@sluurp/client";
Sluurp.extend("invoices", function () {
const client = this;
return {
list: () => client.send("/invoices"),
};
});import "plugin:invoices";
const { items } = await sluurp.invoices.list();Its types go in client/index.d.ts, added to Sluurp’s own with declare module "sluurp" { export interface Sluurp { readonly invoices: … } }. An app’s editor finds a plugin’s browser code and types where the plugin is installed, so they never fall behind it.
Using one plugin from another
A plugin imports another as plugin:name, and its own files as ./file.ts:
import { money } from "plugin:peppol@^1/format.ts";
import { rules } from "./rules.ts";plugin:name is its main file; a range after the name is checked against the version installed. A plugin reads nothing else: not the app’s files, not the disk.
Call another plugin
To use what another plugin keeps, such as its settings or its collections, call it. ctx.plugins.call(plugin, name, body) runs that plugin’s calls/<name>.ts as the caller, under the other plugin’s own name, and answers what it answered:
const { id, url } = ctx.plugins.call("payments", "start", { payee: "shop", cents: 1200, what: "Concert ticket", back, ref });The called plugin is told who asked in ctx.query.from, which the caller can’t change, so it can answer each plugin for its own things only.
Ask every plugin
ctx.plugins.ask(file, body) runs each installed plugin’s <file>.ts that exists, as the system, and gives back [{ plugin, answer }]. A plugin lets others add to what it does this way: Payments asks every plugin’s payees.ts who it takes payments for.
What’s in a plugin
A plugin is a folder laid out like an app. Where a file lives decides what it does, so a plugin needs only the parts it uses:
plugin.json # name, version, what it requires, routes, private hosts
functions/ # server functions, and functions/api.ts for its routes
hooks/ # record hooks, run before the app's own
jobs/ queues/ # scheduled jobs and queue handlers
migrations/ # its collections and data, run when it is installed
admin/ # screens, cards and actions in the admin
client/index.ts # browser code, imported as plugin:<name>
islands/ # islands for server pages, as <name>:<island>
migrate.ts # takes its section of an app's migration ({ "feeds": … })
mcp.ts # tools it gives coding agents
model.ts # a language model for Sluurp (see AI)
site/ # head tags, sitemap entries and feeds for the site's pagesA plugin marked "dev": true in its plugin.json (such as the Storyboard and Hawkeye) is a dev tool: it stays installed in production but does nothing there, and a swarm never runs it.
What a plugin’s main module can do
A plugin’s main module is TypeScript or JavaScript, run in a worker as server code is, with the same time limits. It has the web’s standard objects, fetch, and Sluurp (YAML, TOML, JSON5, XML and the rest), but none of the app’s data: it works only on what it’s handed. It exports what it provides:
| Export | What it adds |
|---|---|
invoiceFormat | An e-invoice format billing offers beside the PDF, for the issuers’ countries it lists: { name, label, countries, contentType, extension, build(invoice) } |
extensions, transform(source, path) | A file type the app can import, made into a module |
Calling a plugin from server code
Functions, hooks, jobs and REST routes import a plugin as any module, and call its exported functions:
import { count } from "plugin:wordcount";
export default async (ctx) => count(ctx.query.text);Arguments and answers cross as data, so a plugin never runs inside your script, and your script never runs inside it.
To use one of a plugin’s modules in your own code instead, name its file after the plugin. The module is then part of your script, as your own files are, whether the plugin is a folder or a sealed package:
import { dueSoon } from "plugin:invoices/server/core.ts";
export const schedule = "0 7 * * *";
export default async (ctx) => dueSoon(ctx);Import a plugin’s files this way rather than by a path into plugins/: an installed package has no folder there, and your editor finds its types under the name.
Plugins in other languages
WebAssembly
Write the plugin’s heavy part in any language that compiles to WebAssembly (Rust, Go, Zig, C), and ship the .wasm file with a small TypeScript file that imports it:
import engine from "./engine.wasm";
export async function count(text: string) {
const out = await engine.run({ stdin: text });
return JSON.parse(out.stdout);
}The module is compiled to machine code once, and runs in its own memory with only what it is handed: no disk and no network, but no time limit, and as much memory as WebAssembly allows (4 GB). Call a function it exports with engine.call("name", 1, 2), or run it as a program that reads its input and writes its answer, as above. Two plugins in Sluurp’s registry work this way: wordcount, in Go, and jseval, QuickJS built with Rust, which runs code you don’t trust with nothing but its input.
Programs
For work that’s best kept in a program of its own (a library in another language, a device, a service you’d rather keep out of the server’s process), a plugin can be a program. Sluurp starts it the first time it is called and keeps it running:
{ "name": "oracle", "version": "1.0.0", "run": "bin/{platform}/oracle" }Server code calls it like any other plugin, and can use transactions:
import oracle from "plugin:oracle";
const rows = await oracle.query("select * from orders where id = :1", [id]);
await oracle.transaction(async (tx) => {
await tx.execute("update stock set n = n - 1 where id = :1", [item]);
await tx.execute("insert into orders …", [item]);
});transaction commits when your function returns and rolls back when it throws. A transaction a script leaves open, with begin(), is rolled back when the script ends.
How it talks. Calls and answers go over the program’s stdin and stdout as CBOR, a compact binary format: a 4-byte length, then the message. Every call has an id, so many are answered at once, in any order. CBOR keeps exact what JSON would round: big integers arrive as BigInt, decimals as exact strings, dates as Date, bytes as Uint8Array. A large table can be answered as Arrow, a columnar format, which Sluurp turns into rows without converting value by value.
Writing one in Go takes the SDK, go get github.com/SluurpHQ/releases/sdk/go:
package main
import "github.com/SluurpHQ/releases/sdk/go"
func main() {
sluurp.Serve(sluurp.Functions{
"hello": func(c *sluurp.Call) (any, error) { return "hello " + c.String(0), nil },
})
}Each call runs in a goroutine of its own. A plugin with transactions has begin (answering the transaction’s id), commit and rollback, and finds the transaction a call is made in in c.Tx. The kv example shows all of it, Arrow included.
Builds for each machine go in bin/<platform>/: linux-x86_64, linux-aarch64, macos-aarch64, windows-x86_64. Installing downloads only this machine’s. The plugin’s sources can sit in its src/ folder, which isn’t released.
Trust. A program runs with the server’s own access to the machine, so none runs unless the server allows it by name: SLUURP_NATIVE_PLUGINS=oracle,kv.
Writing your own
Keep your plugins in a repository: a folder per plugin with its plugin.json, and an index.json listing every release. sluurp plugin new and sluurp plugin release lay it out for you.
sluurp plugin new acme-invoices --registry . # its folder, plugin.json and main file
sluurp plugin release acme-invoices --registry . # checksums into index.json, committed and tagged acme-invoices@0.1.0
git push --follow-tagsEvery release needs a section in the plugin’s CHANGELOG.md for its version (## 1.2.0). The release refuses to go out without one, and the Marketplace shows it under “What changed”.
How a plugin shows in the Marketplace comes from its plugin.json and its folder:
title | the name people see ("Billing BE"). Without one, its name with dashes as spaces and a capital first letter (“billing-be” reads “Billing be”). name stays its id |
description, pitch, keywords | what it says it does, one line for its card, and the words it is found by |
kind, category | what sort of thing it is (feature, integration, UI component, template, theme, example) and where it is filed |
license, commercial | its licence, and whether commercial use is free, needs a business-licence, is pro (SluurpHQ’s own: included with every business licence, and bought on its own for the free Sluurp), or is sold separately, even to licensed servers |
icon, cover, homepage, author | an emoji, a picture’s address, or one of the admin’s icons (icon:card); a wide picture for its tile; its web page; who made it |
price | its price when it is sold, { "amount": 49, "currency": "usd" }: see Commercial plugins |
README.md | the page about it |
docs/*.md | its documentation, with front matter (title, description, section, order) and its pictures beside it |
media/ | pictures and short videos (PNG, JPEG, WebP, GIF, AVIF, MP4, WebM). They are listed with the release but not installed into apps |
A plugin’s docs
A plugin keeps its documentation in its own folder, as docs/*.md with its pictures beside them, so the docs travel with the code they describe. The Marketplace shows them on the plugin’s page. The official plugins’ docs are also pages of this site, taken from each plugin’s newest release in Sluurp’s registry: docs/hawkeye.md is /docs/hawkeye, filed in the sidebar by its front matter’s section and order, and found by the docs search.
hawkeye/
plugin.json
docs/
hawkeye.md --- title: Hawkeye, section: Frontend, order: 10 ---
hawkeye-frames.png A commercial plugin’s docs are public like any other’s: they are released in the clear beside its sealed code.
An installed plugin’s docs are also in the admin’s Help, beside Sluurp’s own, and agents read them through the MCP’s help tool. Write them for the people who set the plugin up and the people who build with it: what to do in the admin, then how to use it in an app.
A page can hold something to try, such as a live demo. Name it in the page, and export it from one of the plugin’s admin extensions as islands:
Try it here:
<sluurp-island src="note-demo"></sluurp-island>function NoteDemo() {
const [added, setAdded] = React.useState(0);
return <Button onClick={() => setAdded(added + 1)}>Add a note ({added})</Button>;
}
export const islands = { "note-demo": NoteDemo };Help draws it between the words around it, with the admin’s components and signed in as the person reading.
main names the plugin’s server-side module, the one that adds file types or exports. Leave it out when the plugin has none, for example when it only has functions, migrations, browser code and admin screens.
Commercial plugins
A plugin can be sold. Its code, for the browser (admin/ and client/) and for the server (functions, server modules, queues, jobs, hooks, migrations), is released compiled, obfuscated and encrypted with a key of its own, and a server opens it in memory only once the store has given it the key: plain code is never written to disk. A server gets the key by owning the plugin, either because it has a business licence that includes it, or because the plugin was bought for that server in the Marketplace. See SluurpHQ’s Pro plugins for which are included.
To sell a plugin you need a publisher licence from SluurpHQ; free plugins need none. Give the plugin a price, keep its source out of your registry, and release it from its own folder:
SLUURP_PUBLISHER_KEY=SLUURP-PUBLISHER-… sluurp plugin release charts-pro --registry ../my-registry --source ./charts-proThe release compiles each module, obfuscates it with javascript-obfuscator (through npx), seals the lot, registers the key with the store under your publisher licence, and puts only the sealed file and what the Marketplace shows (plugin.json, README.md, CHANGELOG.md, LICENSE, docs/, media/) in the registry. Two more files go beside the sealed one, in the clear, so that apps can build on the plugin without reading its code. The first is the types of every module an app can import, its server modules included, as .d.ts files beside where the code was. TypeScript’s own compiler (tsgo, through npx) writes them with your repository’s tsconfig.json and the plugin’s own .d.ts files, so they say what the code does rather than any. Folders that only Sluurp runs, such as functions/, jobs/ and migrations/, get none. The second is classes.txt, the Tailwind classes the code uses, keeping only words that make a style. Buyers pay through Stripe; you are paid through Stripe Connect, less the store’s 10%.
A plugin’s server code is never sent to a browser, sealed or not: under /plugins/<name>/ a server serves only its client/, admin/, docs/ and media/ folders and the plain files at its top.
The store gives one key per release, and a version is released once. Releasing the same version again with another key is refused, so that a key never changes under the people who bought it.
Using a sealed plugin in an app
An app imports a sealed plugin’s browser code as it would any plugin’s, and the server opens it in memory when the app is bundled. For your editor and the type check, map @/plugins/* to the installed packages as well as to the app’s own folder, so that the plugin’s .d.ts files are found:
{
"compilerOptions": {
"paths": {
"@/*": ["./*"],
"@/plugins/*": ["./plugins/*", "./node_modules/@sluurp-plugins/*"]
}
}
}The app’s stylesheet scans the installed packages for classes, which picks up each sealed plugin’s classes.txt:
@source "./node_modules/@sluurp-plugins";To build an app ahead with sluurp build, the build needs the keys, just as the server does. It reads them from the data folder, sluurp_data unless --dir names another. Your development server’s data folder has them once the plugins are installed there:
sluurp build --public appEach piece of the bundle that holds a sealed plugin’s code is written to dist/ sealed with that plugin’s key, so the deployed files never hold its code in the clear. The server you deploy to opens those pieces in memory with its own keys. A server without a key for the plugin serves the rest of the app and refuses those pieces, saying why.
Pro plugins
SluurpHQ’s own commercial plugins:
| Plugin | What it does | |
|---|---|---|
| Storyboard, Hawkeye | Design and development tools for your app’s screens | Included |
| Board | A whiteboard inside any document, edited by everyone on the page at once | Included |
| Calls | Video calls in your app | $49 |
| Pages | A Notion-style editor: blocks, folders, boards, forms and sign-ups | $49 |
| Invoicing | Issuers, a catalogue, subscriptions, invoices, bank transfers matched, a prepaid wallet. Payments comes with it | $49 |
| Payments | Payments online through Stripe, Mollie or Paddle, each provider a free plugin of its own | $49 |
| Store | Sell digital goods (e-books, courses, downloads, plugins), with sellers paid through Stripe Connect, purchases, reviews and delivery to buyers only. With Licences installed, a product can sell a licence key | $149 |
| Licences | Run a licence server for software you sell: products with their own key prefix, licences signed with your Ed25519 key, activation bound to one server, revocation, and a ledger of what was issued | $99 |
Storyboard, Hawkeye and Board come with a business licence; on the free, non-commercial Sluurp, each can be bought on its own in the Marketplace. The others are always bought on their own, even with a business licence. Each is paid once per server, and a swarm counts as one server: its nodes share what it bought. The Store builds on a free plugin: the Store’s screens come from Storefront, the app-store screens (a rail, search, sections, item pages, Updates, Library) that the Marketplace is made of too.
Licences
The Licences plugin signs with a key kept encrypted in the server’s environment, as LICENSES_SIGNING_KEY. Make one, or bring in a key you already sign with, on the server’s data folder:
sluurp license keygen # prints the public key
sluurp license import-key old-key.txt # or bring in your existing key
sluurp license import-ledger ledger.jsonlIssuing, activating and revoking are then on its admin screen, and on its API at /api/licenses.
The Marketplace
Install the marketplace plugin, and the admin gets a Marketplace, shaped like an app store: Home with featured plugins and sections, a page per category, search, a page for each plugin, Updates, a Library of what this server has and owns, and What’s new. A plugin’s page shows its docs, pictures and videos, reviews, requirements, licence, and what changed in each version. A plugin is shown as Free, Included with a business licence, or with its price and a Buy button; one bought, or included with this server’s licence, is Owned. You can install any version that runs on your Sluurp, update a plugin, or remove one. A plugin another one needs can’t be removed.
When an update is out, the number of updates shows beside Marketplace in the sidebar, and the Updates tab updates them one by one or all at once. Sources, at the bottom, adds or removes registries.
It works on an app served from its folder (sluurp serve --public app). Installing adds the plugin to the app’s package.json and the server’s store, runs the new plugins’ migrations, and adds their admin screens without reloading the admin. The same actions are on the API, for a superuser: GET /api/plugins (?fresh=1 reads the registries again), and POST /api/plugins/install, /remove, /update and /registries.
Your own registries
An app takes plugins from a registry of yours once it names it:
sluurp plugin registry add acme/sluurp-plugins
sluurp plugin add acme/sluurp-plugins:acme-invoicesA registry is a GitHub owner/repo, any git address (git@gitlab.com:acme/plugins.git, ssh://…, https://….git), or a folder.
Private registries are read with the git installed on the machine, with whatever access it already has: an SSH key, a credential manager, gh auth login, a deploy key on a server. Sluurp keeps no passwords of its own for them. Where git can’t be used, give a token instead: SLUURP_PLUGIN_TOKENS=acme/sluurp-plugins=… (or acme=… for all of an owner’s), or GITHUB_TOKEN. A token may be written encrypted, ENC(…), and is only ever sent to GitHub, for its own registry.
Which registries a server allows: Sluurp’s own, at https://sluurp.org/registry, always. Others only when the app names them, and, if the server sets it, only those in SLUURP_PLUGIN_REGISTRIES=acme/sluurp-plugins,….