---
title: Plugins
description: 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.
section: Plugins
order: 1
---

# 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:

```sh title="Terminal"
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 peppol
```

Features 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:

```sh title="Terminal"
sluurp plugin add ../my-plugins/invoices
```

It 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](#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`.

```json title="plugin.json"
{
  "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:

```json title="plugin.json"
{
  "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:

```json title="plugin.json"
{ "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:

```js title="client/index.js"
import { Sluurp } from "@sluurp/client";

Sluurp.extend("invoices", function () {
  const client = this;
  return {
    list: () => client.send("/invoices"),
  };
});
```

```ts title="app.tsx"
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`:

```ts title="acme-invoices.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:

```ts title="plugins/tickets/functions/api.ts"
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:

```text title="plugins/my-plugin/"
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 pages
```

A 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:

```ts title="functions/count.ts"
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:

```ts title="jobs/reminders.ts"
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:

```ts title="wordcount.ts"
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:

```json title="plugin.json"
{ "name": "oracle", "version": "1.0.0", "run": "bin/{platform}/oracle" }
```

Server code calls it like any other plugin, and can use transactions:

```ts title="functions/order.ts"
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`:

```go title="main.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.

```sh title="Terminal"
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-tags
```

Every 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 `separate`ly, 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](#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.

```text
hawkeye/
  plugin.json
  docs/
    hawkeye.md          ---  title: Hawkeye, section: Frontend, order: 10  ---
    hawkeye-frames.png  ![Hawkeye's frames](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`:

```md title="docs/using-it.md"
Try it here:

<sluurp-island src="note-demo"></sluurp-island>
```

```tsx title="admin/notes.tsx"
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](/business) that includes it, or because the plugin was bought for that server in the Marketplace. See [SluurpHQ's Pro plugins](#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:

```sh title="Terminal"
SLUURP_PUBLISHER_KEY=SLUURP-PUBLISHER-… sluurp plugin release charts-pro --registry ../my-registry --source ./charts-pro
```

The 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:

```json title="tsconfig.json"
{
  "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`:

```css title="styles.css"
@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:

```sh title="Terminal"
sluurp build --public app
```

Each 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](/docs/storyboard), [Hawkeye](/docs/hawkeye) | Design and development tools for your app's screens | Included |
| [Board](/docs/board) | A whiteboard inside any document, edited by everyone on the page at once | Included |
| [Calls](/docs/calls) | Video calls in your app | $49 |
| [Pages](/docs/pages) | A Notion-style editor: blocks, folders, boards, forms and sign-ups | $49 |
| [Invoicing](/docs/payments#invoicing) | Issuers, a catalogue, subscriptions, invoices, bank transfers matched, a prepaid wallet. Payments comes with it | $49 |
| [Payments](/docs/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](/business); 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:

```sh title="Terminal"
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.jsonl
```

Issuing, 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:

```sh title="Terminal"
sluurp plugin registry add acme/sluurp-plugins
sluurp plugin add acme/sluurp-plugins:acme-invoices
```

A 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,…`.
