DocsDeploy & operate
Admin extensions
Your app’s own screens, cards and actions in the admin, from an admin/ folder.
Add your own screens, record cards and actions to the admin UI. What a file exports decides where it shows up, so there’s no manifest to write and nothing to register. To add one, put a file in your app’s admin/ folder:
import * as React from "react";
import { ShoppingCartIcon } from "lucide-react";
import { Button } from "@/components/ui/button";
import { api, notify } from "@/session";
import { Page } from "@/screens/parts";
export const title = "Orders";
export const icon = ShoppingCartIcon;
export const collections = ["customers"];
// A screen of its own.
export default function Orders() {
const [open, setOpen] = React.useState<number | null>(null);
React.useEffect(() => {
api().send("/collections/orders/records", { query: { perPage: 1, filter: "status = 'open'" } }).then((p) => setOpen(p.totalItems));
}, []);
return <Page>{open ?? "…"} open orders</Page>;
}
// A button in the collection's toolbar.
export const Tool = ({ refresh }) => <Button variant="secondary" onClick={refresh}>Sync</Button>;
// A card at the end of a record.
export const Block = ({ record }) => <p>Customer since {record.created_at.slice(0, 4)}</p>;
// An item in the record's More actions menu, opening a dialog.
export const Action = ({ record, close }) => (
<Button onClick={() => { notify(`Invoice sent to ${record.email}`); close(); }}>Send invoice</Button>
);Features include:
- Screens of your own, listed in the sidebar
- Cards on records, and actions for one record or many
- Buttons in a collection’s toolbar, and rows above its records
- Editors of your own for a collection’s records
- Counts and names in the sidebar
What goes where
| Export | Shows up as |
|---|---|
default | a screen, listed under Extensions in the sidebar and kept on reload |
Block | a card at the end of a record, titled with title |
Action | an item in a record’s More actions menu, opening a dialog |
Bulk | a button on the selection bar, opening a dialog |
Tool | a button in a collection’s toolbar, beside New record |
Strip | a row above a collection’s records, such as the drafts in progress |
Editor | opens the records of its collections in place of the standard sheet. Use it for a collection whose records are edited differently, such as drafts that are published later |
badges | an async function that returns counts by collection name ({ posts: 3 }). Each count shows beside the collection in the sidebar, and is asked for again whenever the record counts are |
count | an async function that returns a number, shown beside the extension’s own screen in the sidebar (the Marketplace’s updates waiting) |
Preferences | a section of each person’s Preferences screen, such as the devices the Storyboard’s frames are offered |
HeaderTool | a button at the end of every screen’s header, such as the AI plugin’s agent |
sidebar | { takes, pick, active, drag }: while the extension’s screen shows, the sidebar’s collection rows it takes are its own. A click on one calls pick, active says which is shown as current, and drag is told a row is being dragged |
labels | an async function that returns names for collections ({ _page_x1: "Trips" }), which the sidebar shows in place of their own names |
title | the name everywhere (by default, the file’s name: sales-report → “Sales report”) |
icon | the icon in the sidebar and menus |
collections | which collections get Block, Action, Bulk, Tool, Strip and Editor: a list of names, or a function that takes a collection’s name and says yes or no. By default, all collections |
frame | true puts the admin’s bar, with the title, over the screen, and pads it. Without it, the screen draws its own header |
A file can export any combination of these.
What each one receives
Block and Action get collection and record. Tool gets collection and refresh(), which reads the records again. Strip gets collection and open(record). Editor gets collection (its name and schema), record (null for a new one), prefill, onClose and onChanged. Bulk gets collection and the ticked ids. Action and Bulk get close(), which shuts their dialog; after a bulk action the table is read again.
The admin’s own parts
An extension is part of the admin’s React app, so it imports what the admin’s own screens are built from: its components (@/components/ui/…, @/components/sluurp/…), @/session (api(), the admin’s client signed in as the superuser, and notify, complain), and @/screens/parts (Page and the rest). These are the admin’s internals, so they can change between Sluurp versions.
For your editor to know these, give the admin/ folder a tsconfig.json of its own. While you develop, Sluurp writes the admin’s types into .sluurp/admin, and this file points @/ at them:
{
"extends": "../.sluurp/admin/tsconfig.json",
"include": ["**/*.ts", "**/*.tsx"]
}Leave admin out of your app’s own tsconfig.json ("exclude": ["admin"]), and check it on its own with sluurp bun check -p admin.
Good to know
- Files are
.tsx,.ts,.jsxor.js, compiled like the rest of your app, and they import components the way your pages do (@/components/ui/…, the admin’s own). - They run in the admin with no sandbox: extensions are your own code, trusted like a hook. They do run in the browser, though, so keep secrets out of them. Call a server function for anything secret.
- If an extension fails to load or throws, it shows the error in its own place and the rest of the admin keeps working.