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:

admin/orders.tsx
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

ExportShows up as
defaulta screen, listed under Extensions in the sidebar and kept on reload
Blocka card at the end of a record, titled with title
Actionan item in a record’s More actions menu, opening a dialog
Bulka button on the selection bar, opening a dialog
Toola button in a collection’s toolbar, beside New record
Stripa row above a collection’s records, such as the drafts in progress
Editoropens 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
badgesan 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
countan async function that returns a number, shown beside the extension’s own screen in the sidebar (the Marketplace’s updates waiting)
Preferencesa section of each person’s Preferences screen, such as the devices the Storyboard’s frames are offered
HeaderToola 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
labelsan async function that returns names for collections ({ _page_x1: "Trips" }), which the sidebar shows in place of their own names
titlethe name everywhere (by default, the file’s name: sales-report → “Sales report”)
iconthe icon in the sidebar and menus
collectionswhich 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
frametrue 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:

admin/tsconfig.json
{
  "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, .jsx or .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.

View as Markdown