Admin UI
Contribute admin menu items, pages, settings, and collection-view overrides from a plugin — and control where they appear in the sidebar.
A plugin can extend the Nextly admin in two complementary ways:
contributes.admin. The declarative surface: menu entries, custom pages, a settings panel, and per-collection view overrides.admin(on the plugin definition) — placement & appearance: where the plugin's items sit in the sidebar and how they look.
Both are @public. Admin dashboard widgets are declared with defineWidget under
contributes.dashboard, and are rendered on the admin dashboard today, but the contract
remains @experimental while its shape settles.
Component paths
Admin contributions reference React components by string path, not by import, so the declarative surface stays serializable and Node-safe:
"<package>/<subpath>#<ExportName>"
// e.g. "@acme/nextly-plugin-reports/admin#ReportsView"Register the components those paths resolve to from your plugin's /admin entry, which
runs inside the admin shell:
// src/admin/index.ts
import { registerComponents } from "@nextlyhq/plugin-sdk/admin";
import { ReportsView } from "./ReportsView";
registerComponents({
"@acme/nextly-plugin-reports/admin#ReportsView": ReportsView,
});An app loads these through its component map, two generated files beside its generated types:
plugin-admin-imports.generated.tsimports and registers every plugin admin component, and the app's admin page imports it. That includes the views a collection names for its own screens underadmin.components(itsEditandListviews, and what is drawn before and after its list table and edit form), whether the collection is a plugin's or the site's own. The admin imports no module by name at run time, so a component the map doesn't list draws its fallback, andnext devnames it.plugin-admin-components.generated.tslists the same paths as plain strings, and the admin's server layout passes them tocheckAdminComponentsfromnextly/runtime.
The app commits both. nextly generate:types writes them, and next dev rewrites them when
they fall behind the config. NEXTLY_GENERATED_FILES_WRITE=0 turns that off, for a read-only
checkout or a test run, and the server log then names each missing component and the switch.
An app that has not installed @nextlyhq/admin still gets both files, but its map imports
nothing from the admin and registers nothing, so the app type-checks without it. After you
install the admin, run npx nextly generate:types again so the map registers its components.
Check the committed map in CI with nextly generate:types --check. It writes nothing, and
exits 2 naming each missing component and each path no longer declared, or 1 when it cannot
load the config:
npx nextly generate:types --check--check and --dry-run are refused together: --check exits non-zero when the map is out
of date, while --dry-run lists the files a real run would write and exits 0.
Production never reads, checks or writes the map. A dashboard widget whose component is missing from it draws its own card's error state, and every other card and page draws as usual. In development the error names the widget, its owner and the missing path; in production it says only that the card could not be drawn. Other components missing from the map draw empty.
After a map change in development, the request that finds the map out of date is already being served when the map is rewritten, so that one render can still draw the new widget's card in its error state. The rewritten map is what the next render loads.
next dev keeps the map current once the admin layout calls the check. New apps do both:
their admin page imports the map and their admin layout calls the check. An app made from an
older template may have neither, so a plugin's components are not registered: its widget cards
draw their error state, and its other components draw empty, until it adds them:
// src/app/admin/[[...params]]/page.tsx: with the other imports
import "../../../types/generated/plugin-admin-imports.generated";// src/app/admin/[[...params]]/layout.tsx
import { connection } from "next/server";
import { Suspense } from "react";
import config from "../../../../nextly.config";
import { registeredComponentPaths } from "../../../types/generated/plugin-admin-components.generated";
export default function AdminLayout({
children,
}: {
children: React.ReactNode;
}) {
return process.env.NODE_ENV === "development" ? (
<Suspense fallback={null}>
<ComponentMapKeptCurrent>{children}</ComponentMapKeptCurrent>
</Suspense>
) : (
children
);
}
async function ComponentMapKeptCurrent({
children,
}: {
children: React.ReactNode;
}) {
await connection();
const { checkAdminComponents } = await import("nextly/runtime");
await checkAdminComponents({ config, registeredComponentPaths });
return children;
}Keep anything your layout already renders, such as branding styles, around that choice. The check runs in development only, and beneath a Suspense boundary because, under Cache Components, request work outside one fails the build. A production build leaves it out, so the admin page is prebuilt: the same page for every visitor, served at once, even while the server is still starting.
Then run npx nextly generate:types once and commit the two generated files. The paths
assume the default types location (./src/types/generated/); use the folder your
typescript.outputFile names.
UI building blocks (@nextlyhq/ui)
Build your admin components out of the shared plugin UI kit, @nextlyhq/ui — the
semver-protected surface of React primitives the admin itself is built from.
The host provides it (and React) as a peer dependency, so you and the admin share one
version and one theme:
// src/admin/ReportsView.tsx
import {
Button,
Input,
Checkbox,
Select,
Card,
Table,
FormLabelWithTooltip,
} from "@nextlyhq/ui";Which of these primitives are covered by a stability guarantee is recorded in
packages/ui/STABILITY.md:
a component becomes @public once a first-party plugin depends on it, and everything
else is @experimental and may change in any release.
Register components and reference admin contribution types through
@nextlyhq/plugin-sdk/admin; import UI primitives from @nextlyhq/ui.
Never import from
@nextlyhq/admin. It is an application, not a published API — reaching into it (e.g.@nextlyhq/admin/lib/*) is unsupported and will break. That includes@nextlyhq/admin/kitand its areas (@nextlyhq/admin/kit/<area>), the internal paths@nextlyhq/plugin-sdk/adminre-exports its parts from: their exports change in any release, while the SDK's names keep the stability their tags state. Importing through the SDK also keeps your admin module light: it brings only the parts you name. If a primitive you need isn't yet exported from@nextlyhq/ui, open an issue so it can be promoted to the kit rather than copied.
Styling your admin UI
The admin ships a single, precompiled, isolated stylesheet (every rule scoped under
.nextly-admin). Because it is built ahead of time, Tailwind cannot see utilities that
live only in your package — so there are three ways to style a plugin, in order of
preference:
1. Compose from the kit. @nextlyhq/ui components are already styled by the admin
sheet, so a plugin built from them needs no styling work at all. Reach for the layout
primitives for common structure:
import { Card, Stack, Grid, Stat } from "@nextlyhq/plugin-sdk/admin";
<Card>
<Stack gap={4}>
<Grid cols={3} gap={4}>
<Stat label="Submissions" value={1280} />
<Stat label="This week" value={64} />
<Stat label="Conversion" value="4.2%" />
</Grid>
</Stack>
</Card>;Stat also takes tone (success, warning, destructive or info), a dot in that
status's colour before the value, and size="compact", a smaller figure under a semibold
label for one that leads a small card.
2. Use safelisted utility classes. A curated, token-driven set of Tailwind utilities is
always present in the admin sheet, so you can use them directly in your components with no
build step: layout (flex, grid, grid-cols-{1..6}, gap-{0..8}, items-*,
justify-*), spacing (p-*, m-*, space-*), sizing (w-*, max-w-*, size-*),
typography (text-{xs..2xl}, font-*, truncate, line-clamp-*), token colors
(bg-primary, text-muted-foreground, border-border, …), and borders/radius/shadow.
These are token-driven only — no arbitrary values or raw colors, so your UI themes in
light and dark automatically.
3. Ship your own CSS (admin.styles). For anything beyond the safelist, compile a
scoped, token-driven stylesheet with the nextly-build-admin-css CLI (from
@nextlyhq/admin-css, add it as a devDependency) and declare it in your manifest.
Your CSS is compiled in your package, not by the host. That is deliberate: the admin
sheet is built when Nextly is released, so it can never scan a plugin that is installed
later, and pointing Tailwind at an installed package with @source is not a reliable
substitute — it does not accept package references, and it resolves inconsistently under
pnpm, which is what this repository and many plugin projects use. Compiling ahead of time
means your styles do not depend on the host's build at all.
/* src/admin.css — author against the shared token preset */
@import "tailwindcss";
@import "@nextlyhq/ui/theme.css";
@source "./src";// package.json
{
"scripts": {
"build:css": "nextly-build-admin-css src/admin.css dist/admin.css",
},
}// your plugin definition
contributes: {
admin: {
styles: "@acme/plugin/dist/admin.css";
}
}Then side-effect-import the built file from your admin entry so the host app's bundler loads it:
// src/admin/index.ts
import "../../dist/admin.css";The CLI compiles your Tailwind, scopes every rule under .nextly-admin, and refuses to
emit if a rule would escape that wrapper or if it finds a hardcoded color — so your styles
can never leak into the host page and always theme correctly. Use --nx-* tokens (via
var() or the token utilities), never literal colors.
Declarative contributions
contributes: {
admin: {
// Sidebar entries. One level of children is supported.
menu: [
{ label: "Reports", to: "/admin/plugins/reports", icon: "BarChart",
order: 10, requiredPermission: "read-reports" },
],
// Custom pages, namespaced under /admin/plugins/<slug>/<path>, RBAC-gated.
pages: [
{ path: "summary", component: "@acme/nextly-plugin-reports/admin#ReportsView",
requiredPermission: "read-reports",
// Read as the page opens, in the admin's first request (experimental).
startupReads: [{ path: "/summary/totals" }] },
],
// A settings panel rendered at /admin/plugins/<slug>.
settings: { component: "@acme/nextly-plugin-reports/admin#ReportsSettings" },
// Per-collection view overrides + injection points, keyed by slug.
views: {
posts: {
beforeList: "@acme/nextly-plugin-reports/admin#PostsBanner",
edit: "@acme/nextly-plugin-reports/admin#PostsEditor",
},
},
},
}menu and pages honour requiredPermission for client-side gating (see
Permissions). View override slots are list, edit,
beforeList, afterList, beforeEdit, afterEdit.
The data a page reads first
Experimental.
startupReadsmay change before it is marked stable.
A page can name the reads of your plugin's own routes it makes as it opens, with
startupReads, as the summary page above does. Name each read as the page's
usePluginRoute names it: path, and mount: "root" for a route mounted at the root.
When a tab opens on that page, the admin asks for them in the same request as the
session, the menu and the settings, before its own code has loaded. Your page's
usePluginRoute read then takes that answer instead of waiting a round of its own.
- Each read is answered by its route with the route's own permission check. A read the person may not make is refused on its own, and your page then reads it as usual.
- The whole request waits for its slowest part, so name only quick reads the page needs first, never a count or a report. A page may name at most four.
- The admin layout carries the reads in the prebuilt admin page, so they take effect
once the app is built again. The layout
create-nextly-appscaffolds writes them withadminStartupScreensJson(config.plugins). - The app refuses to start if a page names more than four, or a path that isn't a
route path starting with
/.
The data a place's part reads first
Experimental.
startupReadson a place contribution may change before it is marked stable.
A part you add to an editor's places (whatever kind the place takes: a block, a tab, a
side panel section) can name the reads of your plugin's own routes it makes as it opens, with the same
startupReads a page takes. The places whose page starts them are collection.edit,
single.edit and entry.form (the form inside both); the app refuses to start if a
part names startupReads anywhere else, where nothing would start them. Its paths may
name the place's ids in braces, which the page fills in from its address:
{
id: "acme-designs.design",
kind: "sidebarSection",
place: "collection.edit",
label: "Design",
component: "@acme/designs/admin#Design",
before: "status",
startupReads: [{ path: "/designs?collection={collection}&entry={entryId}" }],
}The page starts these reads as it first renders, beside its own reads, rather than once
your component has mounted, so their answers arrive a round sooner. Your component's
usePluginRoute read of the same path takes the started read instead of asking again.
An editor (collection.edit, single.edit) waits for them before it is drawn, for
250 ms at most after its document, so your part is drawn in its place with the editor
rather than pushing the parts below it down when it lands. (It also waits for its claim
on the document, for up to a second, since that decides whether the fields may be
written.)
- The ids a path may name are the place's context ids other than
userId:{collection}and{entryId}atcollection.edit,{single}atsingle.edit, and{kind},{slug}and{entryId}atentry.form. On a Single's page the form's{entryId}is not known until the Single has loaded, so a read naming it is not started there. - Each id is filled in URI-component encoded. Build the path your component asks for
the same way, with
encodeURIComponent, and with its parameters in the same order, or the started read and your component's read are two different reads. - A read naming an id the page does not have (a new entry has no
entryId) is not started, and your component reads as it always would. A part withvisibleWhenis started anyway, since its entry has not arrived yet: keep such reads cheap. - Name only quick reads, at most four. A read that can be slow belongs outside
startupReads: the editor would wait its 250 ms for it. - The app refuses to start if a part names more than four reads, a path that isn't a
route path starting with
/, an id its place doesn't give, orstartupReadsat a place other than these three. - A part that can't declare its reads, and draws nothing until they answer, can sit
last in its place instead (
after: "details"in the side panel), where it moves nothing when it lands.
Where your own item goes
Experimental. The
placeoption may change before it is marked stable.
A plugin may add one item of its own to the admin's frame, under header, and choose
where it goes:
place | What it takes | Mounted |
|---|---|---|
"bar" (the default) | a component, slot | for as long as the top bar is |
"rail-foot" | a component, slot | for as long as the top bar is |
"menu" | a declared item, never a component | only while the person's menu is open |
Choose the bar or the rail's foot for a component that must stay mounted: one that draws a button on every page, or one that draws nothing and only registers what a page needs. The bar puts it at the top bar's right end; the rail's foot puts it just above the Inbox, where it moves into the navigation drawer on a narrow window and into the bar while a screen hides the rail, without remounting. Choose the menu for a simple link or action: it is drawn under "Help and community" in the person's menu, after the built-in links.
The bar, as plugins have always declared it (nothing changes for an existing plugin, and
the deprecated headerSlot still means the bar):
contributes: {
admin: {
header: { slot: "@acme/nextly-plugin-reports/admin#PublishBadge" },
},
}The rail's foot:
contributes: {
admin: {
header: {
slot: "@acme/nextly-plugin-reports/admin#ReportsHelper",
place: "rail-foot",
},
},
}The person's menu, with a link: an admin path opens in place, and an absolute URL opens in a new tab.
contributes: {
admin: {
header: {
place: "menu",
item: { label: "Reports help", icon: "BookOpen", to: "/admin/plugins/reports" },
},
},
}Or with an action, the same action a row action takes: { open } draws your component
in a dialog, and { run } calls one of your routes with
{ action: "<plugin-slug>.user-menu", rows: [] }. The route is then reachable as that
item, as a route a row action runs is reachable only as that action (see the
API reference).
contributes: {
admin: {
header: {
place: "menu",
item: {
label: "Rebuild reports",
icon: "RefreshCw",
action: { run: { method: "POST", path: "/rebuild" } },
},
},
},
}icon names a Lucide icon from the admin's icon set. The menu takes no slot: the
compiler refuses one, and an item with neither to nor action, or both, is refused by
the compiler too. An action is checked as a row action's is: open names a component,
and run names one of your own staff routes by method, path and mount. An item that fails
any of this, as one written in plain JavaScript can, is left out of the menu and reported
when the app starts in development. hideDefaults and hide work alongside any place,
and hide only the built-in buttons. Several plugins in one place are ordered by their
admin order, then, in the menu, by label.
Pages that look like core pages
Experimental.
PageFrameandPageHeadermay change before they are marked stable.
A page you contribute under pages is drawn inside the admin's shell, with its top bar,
rail and panel. Draw it from the same two pieces core pages use, both from
@nextlyhq/plugin-sdk/admin, and it looks like one.
PageFrame takes the page's type, and the type decides how wide the page is:
| Type | Width | Use it for |
|---|---|---|
list | Full width, inset by the page gutter | A table or a list of records |
form | A column of at most 56rem, under the page's left edge | Settings and other forms you read top to bottom |
editor | Full width with no gutter, so a side panel meets the edge | An editor that lays out its own field column and side panel |
workspace | Full width with no gutter and no padding | A surface you lay out yourself, such as a canvas or a board |
PageHeader draws the page's title as its heading, with an optional description,
actions on the title's line, meta chips beside the title, a leading media visual and
a tabs row (PageTabs, with a PageTab per section).
// src/admin/ReportsPage.tsx
import { Button, PageFrame, PageHeader } from "@nextlyhq/plugin-sdk/admin";
export function ReportsPage() {
return (
<PageFrame type="list">
<PageHeader
title="Reports"
description="Every report your team has saved."
actions={<Button>New report</Button>}
/>
{/* The page's table */}
</PageFrame>
);
}A page that uses neither is drawn as a Workspace page: full width, with no gutter and no
padding, so the page lays itself out. A page that draws its own PageFrame is not framed
a second time. To put something in the admin's top bar, such as a Save button, use
TopBarPlace.
Building blocks core pages use
Experimental. These may change before they are marked stable.
@nextlyhq/plugin-sdk/admin also exports the parts core pages are assembled from, so a
plugin page draws the admin's own list, trail, checklist and settings rows rather than a
copy of how they look.
| Export | What it draws |
|---|---|
Breadcrumbs | The page's trail, in the admin's top bar. Pass it as PageHeader's breadcrumbs; the last item is the page itself. |
ListView | DataTableView with the admin's list toolbar (search, filters, the columns menu, list actions), its empty state and slots above and below the table. |
useTableColumns, useListColumns | The columns menu's control, with each reader's choice remembered per list. |
ListToolbar, ListColumnsMenu, ListEmptyState | The parts of ListView, for a list laid out by hand. |
Badge | A status chip. success, warning, destructive and info draw a quiet chip with a status dot. |
SegmentedChoice | A short choice kept in view, such as a View / Edit switch. size="bordered" for a setting in a form. |
Checklist, ChecklistItem | A setup list with a progress bar; steps are open, done or skipped. Takes columns={2} and doneStyle="struck". |
FieldShell with layout="row" | A settings row: the label and its help on the left, the control on the right. |
SettingsRowGroup | The same row for a group of controls, named as one group. |
ListView with grouping, rowDetail | Rows in groups, each under a header row with its title, a badge, a count and actions; and rows that open a region below them. |
Stepper | Where a flow of a few steps is: each step done, current or to come, with a way back from a done step. |
FormActions | The form's one action bar, held at the bottom of the page, saying when there are unsaved changes, or the page's own message. |
Alert, AlertTitle, AlertDescription | A notice above the content. variant is info, success, warning or destructive. |
Sheet and its parts | A panel that slides in from an edge of the screen (side on SheetContent). |
Tabs, TabsList, TabsTrigger, TabsContent | Tabs inside a page. For tabs that are routes, use PageTabs. |
Progress | A progress bar: value out of max (100 by default). |
DropdownMenu and its parts | The menu behind a button, such as a row's actions. |
Tooltip and its parts | A hint on hover or focus. The admin provides TooltipProvider. |
FileDropArea | A drop area a file is dragged onto or chosen from, as the Media library draws it, for a screen that reads the file itself; onFiles gets it as it is. |
A list page with a trail, a search, a status filter, the columns menu and row actions:
// src/admin/RedirectsPage.tsx
import { useState } from "react";
import {
Badge,
Breadcrumbs,
ListView,
PageFrame,
PageHeader,
useTableColumns,
type NextlyColumn,
} from "@nextlyhq/plugin-sdk/admin";
interface Redirect {
id: string;
from: string;
to: string;
live: boolean;
}
const COLUMNS: NextlyColumn<Redirect>[] = [
{ name: "from", header: "From" },
{ name: "to", header: "To" },
{
name: "live",
header: "Status",
cell: ({ row }) => (
<Badge variant={row.live ? "success" : "warning"}>
{row.live ? "Served" : "Not served"}
</Badge>
),
},
];
// The identifying column stays out of the columns menu.
const ALWAYS_VISIBLE = new Set(["from"]);
export function RedirectsPage({ redirects }: { redirects: Redirect[] }) {
const [search, setSearch] = useState("");
const { columns, columnsControl } = useTableColumns({
storageKey: "my-plugin-redirects",
columns: COLUMNS,
alwaysVisible: ALWAYS_VISIBLE,
});
const rows = redirects.filter(row => row.from.includes(search));
return (
<PageFrame type="list">
<PageHeader
title="Redirects"
breadcrumbs={
<Breadcrumbs
items={[
{ label: "My plugin", href: "/admin/plugins/my-plugin" },
{ label: "Redirects" },
]}
/>
}
/>
<ListView<Redirect>
search={{
value: search,
onChange: setSearch,
placeholder: "Search redirects",
}}
columnsControl={columnsControl}
columns={columns}
rows={rows}
getRowId={row => row.id}
rowActions={() => [{ id: "edit", label: "Edit", onSelect: () => {} }]}
empty={{ title: "No redirects yet" }}
emptyFiltered={{ title: "No redirect matches" }}
/>
</PageFrame>
);
}empty is shown for a list with nothing in it and emptyFiltered for a search or filter
that matched nothing, so the second never invites the reader to create a first record.
Filters go in filters (inside the toolbar's Filter menu) or inlineFilters (kept in
view, such as a status Select). A SelectTrigger fills its container by default, so give
an inline one a width, or it takes the whole row.
A settings form in the admin's settings rows:
// src/admin/SettingsPage.tsx
import { useState } from "react";
import {
Button,
FieldShell,
FormActions,
FormSection,
Input,
PageFrame,
PageHeader,
SegmentedChoice,
SettingsRowGroup,
} from "@nextlyhq/plugin-sdk/admin";
export function SettingsPage() {
const [separator, setSeparator] = useState("|");
const [dirty, setDirty] = useState(false);
return (
<PageFrame type="form">
<PageHeader title="Settings" />
<FormSection label="General">
<FieldShell
layout="row"
label="Site name"
description="Ends every title."
>
<Input onChange={() => setDirty(true)} />
</FieldShell>
<SettingsRowGroup label="Title separator">
<SegmentedChoice
aria-label="Title separator"
size="bordered"
options={["|", "-", "/"].map(value => ({ value, label: value }))}
value={separator}
onSelect={next => {
setSeparator(next);
setDirty(true);
}}
/>
</SettingsRowGroup>
</FormSection>
<FormActions dirty={dirty}>
<Button onClick={() => setDirty(false)}>Save changes</Button>
</FormActions>
</PageFrame>
);
}FieldShell points its label at the control and its help and error at the control's
description. Use SettingsRowGroup where the right column holds several controls, or one
that is itself a group such as SegmentedChoice, which a <label for> cannot name.
A setup checklist. The bar is a picture, so say the count in words beside the title:
// src/admin/SetupCard.tsx
import {
Button,
Card,
CardContent,
CardHeader,
CardTitle,
Checklist,
ChecklistItem,
} from "@nextlyhq/plugin-sdk/admin";
export function SetupCard() {
return (
<Card>
<CardHeader>
<CardTitle>Set up · 1 of 2 done</CardTitle>
</CardHeader>
<CardContent>
<Checklist label="Setup steps" done={1} total={2}>
<ChecklistItem status="done" label="Name the site" hint="Done" />
<ChecklistItem
status="open"
label="Import old values"
hint="Nothing imported yet"
actions={
<Button size="sm" variant="outline">
Import
</Button>
}
/>
</Checklist>
</CardContent>
</Card>
);
}Rows in groups, each row opening a region that lists what it counts. Every listed group is
drawn in its listed order, even one with no rows; its header counts its rows ("2 rows")
unless you pass a count, such as a total when the list is paginated:
// src/admin/ProblemsList.tsx
import {
Badge,
Button,
ListView,
type DataTableGroup,
type NextlyColumn,
} from "@nextlyhq/plugin-sdk/admin";
interface Problem {
id: string;
severity: "error" | "warning";
title: string;
pages: { id: string; title: string; path: string }[];
}
const COLUMNS: NextlyColumn<Problem>[] = [
{ name: "title", header: "Problem" },
{
name: "pages",
header: "Pages",
accessor: row => row.pages.length,
},
];
const GROUPS: DataTableGroup[] = [
{
id: "error",
title: "Errors",
badge: <Badge variant="destructive">Fix first</Badge>,
},
{
id: "warning",
title: "Warnings",
actions: (
<Button size="sm" variant="outline">
Check again
</Button>
),
},
];
export function ProblemsList({ problems }: { problems: Problem[] }) {
return (
<ListView<Problem>
columns={COLUMNS}
rows={problems}
getRowId={row => row.id}
ariaLabel="Problems"
grouping={{
groups: GROUPS,
groupOf: row => row.severity,
collapsible: true,
}}
rowDetail={{
hasDetail: row => row.pages.length > 0,
toggleLabel: row => `Pages with ${row.title}`,
render: row => (
<ul>
{row.pages.map(page => (
<li key={page.id}>
{page.title} <code>{page.path}</code>
</li>
))}
</ul>
),
}}
empty={{ title: "No problems found" }}
/>
);
}Each group is a row group named by its title, and with collapsible the title is the
button that folds its rows. A row's toggle is a button in its first column that says
whether its region is open; the region below the row is named by the row's identifying
cell. Both states belong to the list unless you pass collapsedIds or expandedIds
with their change handlers. In the narrow card view the groups are sections and each
card carries its own toggle.
A flow of a few steps, with the steps already done linking back, and a save bar that says what changed:
// src/admin/ImportPage.tsx
import {
Button,
FormActions,
PageFrame,
PageHeader,
Stepper,
} from "@nextlyhq/plugin-sdk/admin";
export function ImportPage({ changed }: { changed: number }) {
return (
<PageFrame type="form">
<PageHeader title="Import" />
<Stepper
aria-label="Import steps"
current={2}
steps={[
{
label: "Choose the source",
href: "/admin/plugins/my-plugin/import",
},
{
label: "Match the fields",
href: "/admin/plugins/my-plugin/import/fields",
},
{ label: "Check the result" },
]}
/>
<FormActions
dirty={changed > 0}
message={changed === 1 ? "1 page changed" : `${changed} pages changed`}
>
<Button>Import</Button>
</FormActions>
</PageFrame>
);
}current is the current step's index from 0, marked aria-current="step". A done step
with an href links back to it, or with onSelect runs it from a button; a step not yet
reached never does. FormActions shows its message only while dirty is true.
Document views
Experimental.
documentViewsandDocumentViewPropsmay change before they are marked stable.
A document view is a full-screen screen for one document, at its own address under the document's:
/admin/collections/<slug>/<id>/<path>for a collection entry;/admin/singles/<slug>/<path>for a Single.
A view declared under views[slug] is for that collection, like every other
slot there. A Single, or any document wherever a field type appears, is reached
by a field-type view (below).
views: {
pages: {
documentViews: [
{ path: "builder", component: "@acme/nextly-plugin-builder/admin#Builder",
label: "Builder" },
],
},
},A plugin that contributes a field type can instead offer a view on every collection and Single that has a field of that type. This includes collections created in the Schema Builder later:
contributes: {
fieldTypes: [{ type: "blocks", storage: "json", component: "@acme/x/admin#Blocks" }],
admin: {
documentViews: [
{ path: "builder", fieldType: "blocks",
component: "@acme/x/admin#Builder", label: "Builder" },
],
},
},A view can be scoped only to a field type the same plugin contributes. A field
counts at the top level, inside named groups, and inside a repeater's rows, at
any depth. The address names it by its path from the document's root
(?field=hero.body). A field inside an unnamed group is named as if it were at
the top level, because the group only arranges the form. Inside a repeater, the
row is named by its saved id, not its position (?field=sections.<rowId>.body),
so the address opens the same row after the rows are reordered:
- An address whose row is gone is refused, and so is one that names a row by its
position (
sections.1.body). The admin says the row can't be opened and offers the way back. It never opens the row that now stands where the named one stood, and it never corrects a row address to the document's only field. - A row gets its id when it is saved. A row added since the last save has no
address yet, and a field inside it offers no way in until the entry is saved
once.
useFieldAddress(control, name)gives a field its address, or the reason it has none. - A repeater whose rows declare their own
idfield gives its rows no saved id, so a field in its rows doesn't count.
A field-type view's path must be unique among every document view any plugin
declares.
The admin keeps the document's own behaviour around your view, so you don't build any of it yourself:
- It loads the document and holds its form state.
- It holds the document's soft lock, and shows who else is editing (see Editing with others).
- It saves with the version of the document the form started from. A save refused because someone changed the document since opens the admin's conflict dialog (see When your save is refused).
- It offers unsaved work recovered after a crash or a reload. Restoring it unmounts your view, replaces the form's values, then mounts your view again. A view that keeps its own copy of the document, read when it mounts, starts from the restored work, and anything it writes into the form as it unmounts is replaced by the restore.
- It asks before the author leaves with unsaved changes.
- It saves on the form's own shortcut, through the same actions as the edit form.
Your component replaces the form's body and receives DocumentViewProps from
@nextlyhq/plugin-sdk/admin:
| Prop | What it is |
|---|---|
collectionSlug, entryId | The collection entry being shown. |
singleSlug | The Single being shown, instead of the two above. |
control | The document form's react-hook-form control. Write to the fields through it. |
readOnly | true while someone else holds the document. Don't offer edits then. |
exit | Goes back to the document's edit form. Commit any state you hold into the form first. |
field | For a field-type view, the declaration (FieldConfig, as a field editor receives it) of the field it edits. When the document has several such fields, it is the one the address names (?field=<path>). If the address names none of them, the admin asks the author which one before it draws your view. |
fieldPath | For a field-type view, where that field sits in the form, from the document's root: layout at the top level, hero.body inside a named group. Bind to the field through this, not field.name, which names the field within its own group only. Experimental. |
fieldAddress | For a field-type view, the field's address, which the view's own address carries: the same as fieldPath, except inside a repeater's row, which it names by the row's saved id (sections.<rowId>.body) where fieldPath names its position (sections.1.body). It stays the same when the rows are reordered, so key anything that must stay with the field by it. Experimental. |
fieldLocation | For a field below the top level, where it sits in words: each container's label and each row's title, as the form's row header shows it, then the field's label (Sections · Hero banner · Body). Experimental. |
fieldPathIn | For a field inside a repeater's row, where it sits in a copy of the document's values (the values as stored, a recovery point, or, given none, the form's own values now), finding the row by its id, or undefined where the row isn't there. Ask it at the moment you write, and write only where it answers: a path read earlier could put the value in another row once the rows have moved. Experimental. |
Opening that address requires the same permission as editing the document. A field-type view also opens only for a field the edit form would let the author edit. If the field, or any group around it, is read-only, disabled, hidden, or hidden by its condition, the admin says why and offers the way back instead of drawing your view.
To open a view from inside the admin, for example from a field editor, call
navigateTo(path) from @nextlyhq/plugin-sdk/admin. It accepts a path
starting /admin/, and refuses anything else by throwing. Moving between a
document's edit form and its own views doesn't prompt about unsaved
changes, because the same form stays mounted. Pass { replace: true } as its
second argument to move without leaving the current address in the history,
such as a page at an old address sending the reader on to its new one, so
Back doesn't land on it and move them forward again.
Startup is refused, naming the plugins involved, when a view's path:
- is not one segment of lowercase letters, digits and single dashes;
- is
versionsorapi, which the document already uses; - is declared twice on the same collection or Single, or is the path of a field-type view and declared anywhere else;
- belongs to a field-type view scoped to a field type the plugin does not contribute.
Where an entry opens
Experimental.
opensFirstand a collection's or Single'sadmin.opensInmay change before they are marked stable.
Every admin link meant to open an entry opens it in the same place: a list row, the row menu's Edit and a row's language dots; the dashboard's Continue, Recent entries and Recent activity cards; a release's documents; and the documents a media item is used in. The place is chosen by one rule:
- The collection's
admin.opensIn, when it declares one:"form", or the path of a document view the collection has. - Otherwise, a field-type view that declares
opensFirst: "mainField", when the collection's main field is of that view's type. The main field is the first top-level field (reading into unnamed groups, as the form lays them out) that is not hidden, not the title field and notslug. - Otherwise, the form.
admin: {
documentViews: [
{ path: "builder", fieldType: "blocks", opensFirst: "mainField",
component: "@acme/x/admin#Builder", label: "Builder" },
],
},The admin opens the form instead, whatever the rule says, for a reader who may
not update the entry (they get it read-only) and for an entry opened in a
language other than the site's default. A view that isn't published, because
its plugin is switched off, opens the form too. The form's own address,
/admin/collections/<slug>/<id>, always opens the form, so old links and
bookmarks keep working, and nothing is remembered per person: the same click
always opens the same place. A view opened this way is addressed on the field it
edits (?field=<main field>). Collections made in the Schema Builder can't
declare opensIn, so they follow steps 2 and 3, as their fields are now.
A Single follows the same rule, read from its own fields and its own
admin.opensIn, from the sidebar, the Content screen, the dashboard's cards
and every other link that opens it; its form's address is
/admin/singles/<slug> and a view's is /admin/singles/<slug>/<path>. A view
declared on a slug (views[slug]) is a collection's, so it is never a
Single's, even one with the same slug.
Startup, and every CLI command, is refused, naming the collection or Single and
the view, when its opensIn names a view it doesn't have, or a field-type view
whose field type isn't among its top-level fields. Every plugin's views
count, switched-off ones included, so switching a plugin off never stops a
start. Startup is also refused when opensFirst is declared on a view scoped to
a collection, takes a value other than "mainField", or is declared by two
views on one field type.
The way into the other view
Experimental.
openLabelmay change before it is marked stable.
Wherever an entry opens, its other view is one step away. When a collection's
entries open in a view, each list row's menu offers Edit details, which
opens the form. When they open as the form, the row's menu offers each view the
entry can be opened in, and so does the form's document bar, beside History.
The admin words these from the view, never from the plugin's name: declare the
words with openLabel beside the view's label, as in
{ path: "builder", fieldType: "blocks", label: "Builder", openLabel: "Open in builder", … }.
A view without openLabel is offered as "Open in" its label ("Open in
Builder" there), and a view with neither isn't offered. None is offered to a
reader who may not update the entry, on an entry opened in a language other
than the default, or on a Single. Startup is refused when openLabel isn't
text with words in it.
A create dialog for "+ New"
Experimental.
createDialogandDocumentCreateDialogPropsmay change before they are marked stable.
A view can offer its own short create dialog: declare createDialog, a
component path like component, on the view. On a collection whose entries
open in that view (by the rule above), the list's "+ New" opens a dialog over
the list instead of going to the create form. The admin draws the dialog,
titled "New" and the collection's singular name ("New page"), with its focus, Escape and overlay
handling; your component draws its body, including its own buttons, creates
the entry through its own route or the REST API, and receives
DocumentCreateDialogProps from @nextlyhq/plugin-sdk/admin: the
collection (its slug and labels) and close(createdId?). Call
close(id) with the new entry's id and the admin opens it where its
collection opens entries; call close() to leave the list as it was.
The dialog opens only where "+ New" is offered at all, and only for a reader
whose entries open in the view (one who may update them, in the default
language). A collection that opens as the form, a view without a
createDialog, or a dialog component the admin can't load keeps the create
form, whose address, /admin/collections/<slug>/create, keeps working.
Startup is refused when createDialog names no component.
The header's controls in your view
Experimental. These may change before they are marked stable.
Your view replaces the header, and the header's save state and Publish with it.
Place <DocumentSaveIndicator /> and <DocumentPrimaryAction />, from
@nextlyhq/plugin-sdk/admin, wherever your view draws its toolbar:
DocumentSaveIndicatorsays whether the work is stored: Saving…, Unsaved changes, Saved (when, in its tooltip) or Not saved with Retry. It keeps the width of its longest state, so nothing beside it moves, and screen readers hear it as they hear the header's.classNameplaces it.DocumentPrimaryActionis the action that leads (Publish, Publish changes or Save, as in the header). Its arrow holds Save draft, the other ways to publish, such as Schedule publish…, and Unpublish. An action that can't run right now is disabled, with the reason it is held.
Both are the admin's own controls, run through the same actions as the header. Outside a document they render nothing.
Your view also replaces the header's More actions menu. Two more exports let it offer what that menu offers and word its way out:
useDocumentOpensIn()answers where the entry or Single being edited opens, by the rule in Where an entry opens:opensInis"form"or the path of the view a click on the document opens, andlistis where it is opened from, itslabeland itsaddress: a collection's list, labelled by its plural label as the list's heading shows it, or, for a Single, the Content screen, labelled"content". A view the document opens in has no form to go back to, so its way out is that place: "Back to Pages" or "Back to content", throughnavigateTo(list.address), which asks first about unsaved work as any leave does. It answersnulloutside a document's editor, on a new entry and while the collection or Single is still loading.PIN_TO_DASHBOARD_ACTIONis the id of the header's Pin to dashboard / Unpin from dashboard amonguseDocumentActions().actions. Find it there and run it withrun(id), so the pin, its words, its toast and its Undo are the admin's own, and any reason it can't run now comes with it.
Editing a second document in place
Experimental.
useDocumentSessionmay change before it is marked stable.
A view sometimes edits another document while its own stays open: the page
builder edits a site header right on the page it sits on. The admin holds the
lock, saving and recovery for your view's own document only, so
useDocumentSession(target) from @nextlyhq/plugin-sdk/admin gives you the
same for the other one. target names an entry, { collection, id }, with an
optional locale. Pass null when you stop editing it.
openis the document as its own editor reads it: its working draft in place of the live row where the collection keeps drafts, related items by id, and in thelocalenamed alone. Oncestatusis"ready"it has the storedvalues,published,unpublishedChanges,changedAt(when the version read last changed), anddraftable. Use the last one to tell whether a draft can be saved without changing what is live.lockis the admin's soft lock on it."held"means you hold it, and"held-by-other"comes with theholder's name (ornullwhen it isn't known). Show that instead of letting the person edit. The lock is let go when you passnull, when your view unmounts, and when the page goes away.saveDraft(changes)andpublish(changes)write the fields you pass, through the admin's own update, as the signed-in person. The status is the operation's, judged by the language's own state: astatusamong the fields is ignored. Each sends the version your copy started from (the first read's, then each of your own writes'), so a save made since is refused, even after a refresh. Saving a draft of a published document stores its working draft and leaves what visitors see. Both resolve to{ ok: true, values }once stored. Otherwise they resolve took: falsewith the server'smessageand areason:"stale", withchangedBy: someone saved a newer version;"locked": you don't hold the lock;"no-drafts": the collection keeps no drafts for a published document;"unread": the document hasn't been read yet;"moved": you named another document before it was sent;"refused": the server refused it, in its own words.
mayPublishis whether the person may publish documents of that collection, as the admin's Publish button decides it. It isfalsefor alocaleother than the one on screen, whose grants the admin doesn't know.record(changes)records the whole document with your changes over it as the person's recovery point, once the editing pauses. After a crash, that document's own editor offers it, as it offers any recovery point.discard()empties the point again when the changes are thrown away.
import { useDocumentSession } from "@nextlyhq/plugin-sdk/admin";
export function HeaderSession({
headerId,
edited,
}: {
headerId: string | null;
edited: unknown;
}) {
const session = useDocumentSession(
headerId === null ? null : { collection: "components", id: headerId }
);
if (session.lock.status === "held-by-other") {
// Say who has it, and don't start editing.
return <p>{`${session.lock.holder ?? "Someone"} is editing this.`}</p>;
}
return (
<button
type="button"
onClick={() => void session.publish({ definition: edited })}
>
Publish
</button>
);
}Document actions and panel sections
Experimental.
documentActions,panelSectionsand the props below may change before they are marked stable. Collections only: a Single's document screen is not changed by them yet.
Two more keys under views[slug] change what a collection's document screen
offers, for that collection only. Every other collection keeps the admin's own
screen.
documentActions hides or replaces a built-in action in the document's
More actions menu. It takes delete and unpublish, each set to
"hidden" or to { component, label? }. For example,
documentActions: { unpublish: "hidden", delete: { component: "@acme/plugin-layouts/admin#RemoveLayoutDialog", label: "Remove layout…" } }
takes Unpublish away and routes Delete to the plugin's own dialog.
- A hidden action is not offered at all, from the menu or from
useDocumentActions().run, which refuses it as not offered. - A replaced action keeps its row: its place, the permission it needs, and
every reason it can't run right now (a colleague holding the document, a past
version on screen) still apply. Choosing it mounts your component instead of
the admin's own confirmation and write, so a dialog renders open. Running it
with
run("delete")opens your component too, and answers once it closes.
Until the admin has loaded which plugins are installed, Delete and Unpublish can't be chosen on any collection's document, because a plugin that hides or replaces one isn't known yet and the built-in write must not run in the meantime. Each row says why:
- While the list loads, the row reads "Loading this collection's plugin actions…" and clears itself once the list arrives.
- If the list failed to load, the row names its action, for example "Couldn't load this collection's plugin actions, so Delete is paused.", with a Retry row under it. Retry asks for the list again, the row reads as loading while it does, and then the plugin's own override applies.
useDocumentActions().run refuses the action with the same words. Running a
replaced action that is already open joins it, and both callers get the same
answer when it closes.
Your component receives DocumentActionReplacementProps from
@nextlyhq/plugin-sdk/admin:
| Prop | What it is |
|---|---|
action | Which action the author chose: "delete" or "unpublish". |
collectionSlug, entryId | The document. |
documentLock, mayWrite() | What holds the document, kept current while your component is open, and whether it may be written right now. Call mayWrite() immediately before your write, after anything you awaited: the document can change hands while a dialog is open. |
close(result?) | Ends it. close("deleted") leaves the document for its collection's list, as the built-in Delete does. close("changed") reads the document again. close() means the author backed out. |
Both your replacement and your panel section are drawn inside the document's
editor, so useDocumentLocale() names the language being edited (the one a
replaced Unpublish of a translation acts on) and useDocumentActions() answers
for the same document.
If your component isn't registered, or throws while drawing, the admin closes
it, tells the author the action couldn't open, and answers a waiting
run("delete") as cancelled. When you report "changed", the document is read
again and the author's unsaved edits stay over it, as after their own save.
panelSections adds sections to the document panel, after Details, in the
order given: panelSections: [{ title: "Used by", component: "@acme/plugin-layouts/admin#LayoutUsage" }].
The admin draws each section's heading, spacing and divider, as it does for its
own sections, so the section reads as part of the panel in light and dark. Your
component draws only what goes under the heading. Nothing is drawn while a
document is being created. It receives DocumentPanelSectionProps:
| Prop | What it is |
|---|---|
collectionSlug, entryId | The document. |
documentLock | { readOnly, actionsDisabled }, what holds the document right now. readOnly follows the fields: a colleague's claim, a past version on screen, a reader's page, or the editor still readying the document. actionsDisabled follows the built-in Delete: a colleague's claim, a past version, a collection removed from code, or the editor readying it. A reader's page alone doesn't hold your writes, because your route judges its own permission. Hold your writes while actionsDisabled. |
mayWrite() | Whether the document may be written right now. Call it immediately before a write, after anything you awaited. |
documentChanged(result) | Tell the editor your section changed the document: "deleted" leaves for the collection's list, "changed" reads the document again. |
Startup is refused, naming the plugins involved, when an override names an
action other than delete or unpublish, when a replacement or a section has
no component (or a section no title), or when two plugins override the same
action on the same collection.
A document screen that needs the width
Experimental.
foldedPanelmay change before it is marked stable.
An editor that lays out several columns of its own (a field list, a preview and
a settings panel) can ask for the rail's panel to start folded away on a
collection's document screens: views: { forms: { foldedPanel: true } }. It
applies to an entry's editor, a new entry's, and the pages of the collection's
own edit view. The rail stays, the bar shows a toggle that brings the panel
back, and each reader's choice is remembered for that collection.
Declare it here rather than calling useFoldedPanel from the editor: the
admin then draws the screen's outline folded from its first frame, before any
request has answered, so nothing moves when the editor arrives. A value other
than true or false is refused at startup. useFoldedPanel remains for a
plugin page outside a collection's documents.
Who is signed in
useCurrentUserId() from @nextlyhq/plugin-sdk/admin answers the signed-in user's id, for a
plugin that keeps something per user, such as its own preferences on a browser several
people share. It reads what the admin already knows about the user, so it makes no request.
It answers null while that isn't known yet, when no one is signed in, and when the read
failed. Keep nothing then, rather than keeping it for a guess.
import { useCurrentUserId } from "@nextlyhq/plugin-sdk/admin";
const userId = useCurrentUserId();
const key = userId === null ? null : `my-plugin.layout:${userId}`;This hook is experimental while its first consumer settles. Its name and its
string | null answer are meant to stay.
Translating your strings
A plugin declares its admin strings in contributes.translations, by interface language and
then by key, and its components read them with usePluginTranslate() from
@nextlyhq/plugin-sdk/admin:
// In definePlugin({ ... })
contributes: {
translations: {
en: { "acme-shop.cart.title": "Cart", "acme-shop.cart.count": "{count} items" },
fr: { "acme-shop.cart.title": "Panier" },
},
}
// In a component
const t = usePluginTranslate();
t("acme-shop.cart.title"); // "Panier" in French, "Cart" in English
t("acme-shop.cart.count", { count: 3 }); // "3 items"Every key begins with your plugin's admin slug and a dot (@acme/shop is acme-shop). A string
is read in the interface language, then English, then the key itself. Startup refuses a key
outside your namespace, a malformed key or language, a language not spelled as browsers report it
(pt-BR, not pt-br), a value that isn't text, and a key another plugin declares. A disabled
plugin's strings are still served, since its field editors still show. The admin's own strings begin with nextly., so a plugin slugged nextly can
declare none. The strings reach signed-in readers only, so they are not yet on the sign-in
screen.
This surface is experimental while its first consumer settles.
Dashboard widgets
A plugin adds dashboard widgets under contributes.dashboard.widgets, each declared with
defineWidget from @nextlyhq/plugin-sdk (experimental). A declaration says what the
widget is (id, title, description, size), who is offered it (access), where its data
comes from (load, run on the server for each card, as the person viewing it) and how it is
drawn (view): one of core's views, or a component of your own. Startup checks every
declaration with the rest of the config.
import { definePlugin, defineWidget } from "@nextlyhq/plugin-sdk";
export const publishedReports = defineWidget({
id: "reports/published",
title: "Reports",
description: "How many reports there are.",
size: { default: { w: 3, h: 2 } }, // 12-column grid units: w 1–12, h 2–12
access: "read-reports", // decided on the server, before the card is offered
view: "figure",
load: async ({ services }) => ({
total: await services.count("reports"),
}),
});
export const reports = definePlugin({
name: "@acme/nextly-plugin-reports",
version: "1.0.0",
nextly: "*",
contributes: { dashboard: { widgets: [publishedReports] } },
});access is a permission spelled as stored ("read-reports"), { anyOf } or { allOf } of
several, { collections } (the reader must be able to read each), or a function of the person.
Without it, everyone who can open the dashboard is offered the widget. load reads through the
services it is handed, bound to the viewer, so a card only ever counts and lists what that
person may read. Settings, sizes, what a load can read, and testing a widget are on
Dashboard Widgets.
Let the host draw it
Name one of core's views and ship no UI code. Core draws the card from what load returns, and
the answer's shape is checked against the view twice: when the declaration compiles, and when
an answer arrives.
view | Draws | load returns |
|---|---|---|
"figure" | One number | { total }, with atLeast: true for a floor |
"list" | One line per row | { items }, with fields and total if it has them |
"table" | A column per field | { items }, with fields and total if it has them |
"bars" | A bar per group | { buckets: [{ value, count }] } |
"series" | Counts over time | { points: [{ start, count }], interval } |
A
listdraws one line per row. Its fields are the answer'sfields, in order, or the first row's keys when it names none: the first titles the row, a field of choices (a status) sits at its end, and up to three others join the line under the title. On a large card the rows become a table with every field.A
tabledraws a column per field, headed by thelabelits entry infieldsgives, so a heading reads "Published at", notpublishedAt. A load that reads through itsservicesreads as the viewer, so a field they may not read is absent from their rows, and its column with it.A list or table whose rows carry no field to draw says so on the card rather than guessing.
totalis how many rows the read matched in all, for the card's "View all (N)" link.
There is no core view for a column of shortcuts, for prose, or for several numbers in one card.
A widget declared with defineWidget under contributes.dashboard draws one of those with its
own component, below, handed its load's data. access gates the whole card: nothing in a
declaration gates one item inside it.
Where a card sits
Someone who has never arranged their dashboard sees the default dashboard, and there is
one: the site's admin.dashboard.defaultLayout, or core's own when the site gives none.
Everyone gets the same default, less the cards they may not see: a widget whose permission or
access refuses them, or whose shows answers no.
Core's own default holds, in order: Set up your project across the row; Needs attention beside Upcoming releases; Continue where you left off beside Content; then the form builder's new submissions card, where the form-builder plugin is installed, beside Team activity. While only one of Needs attention and Upcoming releases is on show, it is drawn across the whole row; its saved size does not change.
No widget a plugin declares with defineWidget is placed on any dashboard on its own: the add
panel offers it, and a reader adds it from there. A site that wants a plugin's widget on its
default names it in defaultLayout, as below, marked optional where the plugin may be absent.
contributes.dashboard.suggest is deprecated: it is still checked at startup (each id must be
one of the plugin's own widgets), and it places nothing. A plugin that used it to put a card on
the default dashboard should say in its README which defaultLayout entry a site adds for it.
The site's admin.dashboard.suggestions is deprecated for the same reason: it is still checked
(true or false) and changes nothing, since no card follows the default to turn off.
A site writes its own default as widget ids, or as cards with a size in grid units and
starting settings. An entry marked optional is left out where its widget is not installed,
such as a plugin's on a site without that plugin, and takes none of the dashboard's room; any
other entry must name a widget the install has, or startup refuses it. A widget that allows
several cards may be listed more than once: each further card names an id of its own, which
no other card and no widget has, and keeps its own settings under it:
admin: {
dashboard: {
defaultLayout: [
"core/needs-attention",
{ widget: "acme/orders-by-state", w: 6, h: 4, optional: true },
"core/continue",
{ widget: "core/count", settings: { collection: "posts" } },
{ widget: "core/count", id: "pages-count", settings: { collection: "pages" } },
],
},
}A plugin adds widgets only under contributes.dashboard.widgets, each declared with
defineWidget. Startup refuses a plugin that still carries contributes.admin.widgets or
contributes.widgetSources, naming the plugin and the key.
A reader's saved layout, once they have arranged their dashboard, wins over all of this. Think of the default as where a card starts, not where it stays.
Hiding, replacing and overriding widgets
The site config can change any widget, built-in or a plugin's, for everyone:
admin: {
dashboard: {
hide: ["core/team"],
replace: { "core/continue": "acme/recent-orders" },
overrides: {
"core/team-activity": {
title: "Latest changes",
size: { max: { w: 6, h: 6 } },
settings: { limit: 5 },
},
},
},
}hide: nobody is offered a hidden widget and no card of it is drawn. Cards already saved are kept, and come back where they were once the widget is no longer hidden.replace: a plugin offers an alternative to a built-in incontributes.dashboard.alternatives, and the site puts it in the built-in's place. The default places the alternative where the built-in was, at the alternative's own starting size. The built-in is then kept off the dashboard like a hidden widget, and an alternative noreplacenames is never offered.overrides: a new title, description, starting settings, or sizes narrowed within the widget's own. An override never widens a widget's sizes; startup refuses one that would.
Each holds on every door at once: the add panel, the default, the cards a dashboard draws and the card data the server answers.
The card frame and its states
Every card draws in one frame: a header of one fixed height, the body, and at most one footer
link. The header shows the card's subject as its title (a collection card set to Posts reads
"Posts"), with the widget's own name beneath it when the two differ ("Count"), then the card's
quick control and its menu, in the same place on every card. A widget may mark up to three
settings quick: the header draws the first it can (a select or a checkbox). Every setting
is changed in the card's settings drawer, opened from Settings… in its menu: a preview of the
card, then Content, Display and Size (its width), saved on Save. The menu lists Settings…,
Refresh and Remove. A card does not say when its data arrived.
The frame also owns the states, so a card never draws its own: a skeleton while data has never
arrived, the last value marked busy while it refreshes, an empty state, one "Not available to
you" state for a source the reader cannot see (forbidden, missing and hidden all read the same),
and an error that keeps the title and offers Retry for that card only. Figures go through
formatCount from @nextlyhq/ui/format, so a number reads the same on every card.
A component whose own data says the card is not ready (the answer holds nothing it can show, or
something it cannot read) returns FrameState from @nextlyhq/plugin-sdk/admin with that state,
and the frame draws it in the body's place: for an empty answer, for example,
<FrameState state={{ kind: "empty", empty: { title: "No orders yet" } }} />.
A widget that should leave the dashboard while it has nothing to show, rather than say so,
declares hidesWhenEmpty: true. A card that failed, or whose source the reader cannot see, is
never hidden, and customise mode still shows it, marked "Hidden while empty".
Every card is framed: there is no way to decline the frame, and a widget that names chrome is
refused at startup.
core# is reserved. Core's own dashboard cards resolve their components under
that prefix, and the admin refuses to let anything else register or unregister
one — a plugin claiming the path would replace the body drawn for a card the
registry still attributes to core.
Items in Needs your attention
A plugin adds a line to the Needs your attention card, rather than a card of its own, through
contributes.dashboard.attention (experimental). Each item has an id in your plugin's
namespace, a one-line label, a count taken as the person asking, a link inside the admin,
and exactly one of permission or collections saying who sees it. An optional one-line
reason is drawn under the label, saying why the item is waiting; without one, the row has no
reason line. Plugin items rank as warnings, after core's critical items.
import { defineAttentionItem } from "@nextlyhq/plugin-sdk";
export const unanswered = defineAttentionItem({
id: "forms/submissions",
label: "Form submissions",
reason: "Read and answer them",
collections: ["form-submissions"],
count: ({ services, signal }) =>
services.count("form-submissions", { signal }),
link: "collections/form-submissions",
});Draw it yourself
Name a component path as the view, and register the component from your plugin's /admin
entry, as every admin component is (see Component paths). The host still
draws the card's frame: the header, the footer that holds your body's one link, and the loading,
not-available and error states. Your component draws the body:
import { defineWidget } from "@nextlyhq/plugin-sdk";
export const recentReports = defineWidget({
id: "reports/recent",
title: "Recent reports",
description: "The latest reports, newest first.",
size: { default: { w: 6, h: 4 } }, // 12-column grid units: w 1–12, h 2–12
access: "read-reports",
view: { component: "@acme/nextly-plugin-reports/admin#RecentReports" },
load: async ({ services }) => {
const { items } = await services.find("reports", {
sort: "-createdAt",
limit: 8,
});
return { items };
},
// Required for a component of your own: only you can tell when its data is empty.
isEmpty: data => data.items.length === 0,
});The component is handed WidgetProps<typeof recentReports>, typed from the declaration, so its
data is what that load returns:
import type { WidgetProps } from "@nextlyhq/plugin-sdk/widgets";
import type { recentReports } from "./widgets";
export function RecentReports({
data,
size,
refreshing,
}: WidgetProps<typeof recentReports>) {
const shown = size.tier === "large" ? data.items : data.items.slice(0, 4);
return (
<ul aria-busy={refreshing}>
{shown.map((report: Record<string, unknown>, index: number) => (
<li key={index}>{String(report.title)}</li>
))}
</ul>
);
}| Prop | What it is |
|---|---|
widgetId | The widget's id. |
placementId | The card's id. One widget may sit on a dashboard twice, and everything belonging to a card, its settings and its answer, is keyed by this, not by widgetId. |
settings | This card's settings, already resolved: the reader's stored values where they are usable, your declared defaults everywhere else, typed from the declaration. |
size | The card's w and h in grid units, and its tier: "small", "medium" or "large". |
data | The card's answer, always present: the frame draws loading, not available and error itself, and calls your component only once there is data. |
refreshing | Whether a newer answer is on its way; data is the last one until it lands. |
retry | Asks for the card's data again. |
A load that throws fails its own card, which shows the frame's error with Retry, while every
other card keeps its answer. The types come from @nextlyhq/plugin-sdk/widgets, which carries
no runtime code, so importing them adds nothing to your bundle.
Widgets are drawn on the admin dashboard by WidgetGrid, in a 12-column grid that collapses to
one column on small screens, and every card on the page is answered in one batched request. A
widget its reader may not be offered (access) is neither drawn nor answered for them.
The contract is still @experimental and is expected to grow. Pin your Nextly version while it
settles.
Everything else on this page is @public today.
Placement & appearance
The plugin's own admin field controls where its items live:
import { definePlugin } from "@nextlyhq/plugin-sdk";
definePlugin({
name: "@acme/nextly-plugin-reports",
version: "1.0.0",
nextly: ">=0.0.2-alpha.63",
// ...
admin: {
placement: "collections", // collections | singles | users | settings | plugins | standalone
order: 10, // lower = higher; default 100
after: "collections", // anchor for standalone icons
},
});Placement defaults to plugins. standalone gives the plugin its own top-level icon,
anchored after the section named by after.
A standalone plugin's icon opens the page named by landing, written the way a menu
item's to is: one of the plugin's own pages (/admin/plugins/<slug>/<path>, a
contributes.admin.pages path) or one of its own collections
(/admin/collections/<slug>, which follows a host's rename). A reader who may not open
that page goes where the icon would go without one. Without landing, the icon
opens the first collection its panel lists for the reader, and with none, the first menu
item the panel lists. A landing naming anything else is ignored, and a development
start warns about it, as it does about a standalone plugin with menu items but no
collections and no landing.
The value is written out rather than read from the AdminPlacement constant, which ships
from nextly and not from @nextlyhq/plugin-sdk. The SDK is the only surface a plugin
should depend on, so reaching into core for a constant would tie your plugin to core's
layout for the sake of one string. A host config, which already imports from nextly,
can use the constant, and does so below.
A standalone plugin's panel
A standalone plugin's panel lists its collections, then its menu items. The plugin can group those items under headings, and show a number beside each, all as data: no code of yours runs in the browser to draw the panel. This is experimental.
contributes: {
collections: [patterns],
dashboard: { attention: [bindingsToFix] }, // id "acme/bindings-to-fix"
admin: {
pages: [{ path: "bindings", component: "@acme/plugin/admin#Bindings" }],
panel: {
groups: [
{ id: "library", label: "Library" },
{ id: "checks", label: "Checks" },
],
},
menu: [
{
label: "Patterns",
to: "/admin/collections/patterns",
collection: "patterns",
group: "library",
count: { collection: "patterns" },
},
{
label: "Bindings to fix",
to: "/admin/plugins/acme-plugin/bindings",
group: "checks",
badge: { attention: "acme/bindings-to-fix" },
},
],
},
},Groups are drawn in the order declared, each under its heading; items naming no group come first, under no heading, as every item does today. A heading with no item the reader may see is not drawn.
An item takes a count or a badge, never both. A count is a quiet number, shown at 0
too: how many there are. A badge is a pill shown only while its number is above 0: how
many need doing. Either names what it counts in one of two forms:
{ collection, where? }counts one of the plugin's own collections, by its declared slug (a host's rename is followed), narrowed bywherein the entry list's grammar. The number is the reader's: a collection they may not read shows no number. A collection hidden from the navigation (admin.hidden) is counted all the same, so a library the plugin lists only in its own panel can show its size there.{ attention }reads one of the plugin's own Needs your attention items, by its id: the count that item's line shows the reader, and 0 when nothing is waiting for them.
The numbers are read while the panel is open, in one request for the whole panel that names only the plugin: the server counts what the plugin declared, so nothing the browser sends chooses what is counted. They never hold the panel up: the items are drawn first, and a number that cannot be read is left out. A link's accessible name includes its number ("Patterns, 12").
A development start reports a group the plugin does not declare (the item is listed
with the ungrouped ones), a count naming a collection the plugin does not contribute or
an attention item it does not declare (the item is drawn without a number), and a menu
item linking to one of the plugin's own pages (/admin/plugins/<slug>/<path>) that
contributes.admin.pages does not register, which is left out of the admin in every
environment. It also reports a count or badge reading an attention item gated on
collections that are all hidden from the navigation: Needs your attention leaves hidden
collections out, so that item is shown to nobody and its number is always 0.
Host overrides
An integrator can override a plugin's placement without forking it, via
defineConfig({ admin: { pluginOverrides } }) — keyed by the plugin's admin slug: its
package name lower-cased, with every run of other characters turned into one dash and
leading and trailing dashes dropped (@acme/nextly-plugin-reports →
acme-nextly-plugin-reports). A key written as the package name is never looked up, and
the override is ignored without an error:
// nextly.config.ts
import { AdminPlacement, defineConfig } from "nextly";
import { reports } from "@acme/nextly-plugin-reports";
export default defineConfig({
plugins: [reports()],
admin: {
pluginOverrides: {
"acme-nextly-plugin-reports": {
placement: AdminPlacement.SETTINGS, // move it
order: 5,
after: "users",
appearance: { label: "Analytics" }, // shallow-merged
},
},
},
});The override wins over the plugin's own admin config, so operators stay in control of
their sidebar.
See also: Permissions · Author guide.