You're reading docs for Nextly Alpha. APIs may change between releases.

Plugins

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.ts imports 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 under admin.components (its Edit and List views, 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, and next dev names it.
  • plugin-admin-components.generated.ts lists the same paths as plain strings, and the admin's server layout passes them to checkAdminComponents from nextly/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/kit and its areas (@nextlyhq/admin/kit/<area>), the internal paths @nextlyhq/plugin-sdk/admin re-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. startupReads may 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-app scaffolds writes them with adminStartupScreensJson(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. startupReads on 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} at collection.edit, {single} at single.edit, and {kind}, {slug} and {entryId} at entry.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 with visibleWhen is 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, or startupReads at 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 place option 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:

placeWhat it takesMounted
"bar" (the default)a component, slotfor as long as the top bar is
"rail-foot"a component, slotfor as long as the top bar is
"menu"a declared item, never a componentonly 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. PageFrame and PageHeader may 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:

TypeWidthUse it for
listFull width, inset by the page gutterA table or a list of records
formA column of at most 56rem, under the page's left edgeSettings and other forms you read top to bottom
editorFull width with no gutter, so a side panel meets the edgeAn editor that lays out its own field column and side panel
workspaceFull width with no gutter and no paddingA 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.

ExportWhat it draws
BreadcrumbsThe page's trail, in the admin's top bar. Pass it as PageHeader's breadcrumbs; the last item is the page itself.
ListViewDataTableView with the admin's list toolbar (search, filters, the columns menu, list actions), its empty state and slots above and below the table.
useTableColumns, useListColumnsThe columns menu's control, with each reader's choice remembered per list.
ListToolbar, ListColumnsMenu, ListEmptyStateThe parts of ListView, for a list laid out by hand.
BadgeA status chip. success, warning, destructive and info draw a quiet chip with a status dot.
SegmentedChoiceA short choice kept in view, such as a View / Edit switch. size="bordered" for a setting in a form.
Checklist, ChecklistItemA 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.
SettingsRowGroupThe same row for a group of controls, named as one group.
ListView with grouping, rowDetailRows in groups, each under a header row with its title, a badge, a count and actions; and rows that open a region below them.
StepperWhere a flow of a few steps is: each step done, current or to come, with a way back from a done step.
FormActionsThe 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, AlertDescriptionA notice above the content. variant is info, success, warning or destructive.
Sheet and its partsA panel that slides in from an edge of the screen (side on SheetContent).
Tabs, TabsList, TabsTrigger, TabsContentTabs inside a page. For tabs that are routes, use PageTabs.
ProgressA progress bar: value out of max (100 by default).
DropdownMenu and its partsThe menu behind a button, such as a row's actions.
Tooltip and its partsA hint on hover or focus. The admin provides TooltipProvider.
FileDropAreaA 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. documentViews and DocumentViewProps may 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 id field 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:

PropWhat it is
collectionSlug, entryIdThe collection entry being shown.
singleSlugThe Single being shown, instead of the two above.
controlThe document form's react-hook-form control. Write to the fields through it.
readOnlytrue while someone else holds the document. Don't offer edits then.
exitGoes back to the document's edit form. Commit any state you hold into the form first.
fieldFor 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.
fieldPathFor 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.
fieldAddressFor 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.
fieldLocationFor 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.
fieldPathInFor 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 versions or api, 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. opensFirst and a collection's or Single's admin.opensIn may 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:

  1. The collection's admin.opensIn, when it declares one: "form", or the path of a document view the collection has.
  2. 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 not slug.
  3. 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. openLabel may 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. createDialog and DocumentCreateDialogProps may 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:

  • DocumentSaveIndicator says 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. className places it.
  • DocumentPrimaryAction is 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: opensIn is "form" or the path of the view a click on the document opens, and list is where it is opened from, its label and its address: 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", through navigateTo(list.address), which asks first about unsaved work as any leave does. It answers null outside a document's editor, on a new entry and while the collection or Single is still loading.
  • PIN_TO_DASHBOARD_ACTION is the id of the header's Pin to dashboard / Unpin from dashboard among useDocumentActions().actions. Find it there and run it with run(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. useDocumentSession may 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.

  • open is 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 the locale named alone. Once status is "ready" it has the stored values, published, unpublishedChanges, changedAt (when the version read last changed), and draftable. Use the last one to tell whether a draft can be saved without changing what is live.
  • lock is the admin's soft lock on it. "held" means you hold it, and "held-by-other" comes with the holder's name (or null when it isn't known). Show that instead of letting the person edit. The lock is let go when you pass null, when your view unmounts, and when the page goes away.
  • saveDraft(changes) and publish(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: a status among 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 to ok: false with the server's message and a reason:
    • "stale", with changedBy: 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.
  • mayPublish is whether the person may publish documents of that collection, as the admin's Publish button decides it. It is false for a locale other 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, panelSections and 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:

PropWhat it is
actionWhich action the author chose: "delete" or "unpublish".
collectionSlug, entryIdThe 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:

PropWhat it is
collectionSlug, entryIdThe 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. foldedPanel may 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.

viewDrawsload 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 list draws one line per row. Its fields are the answer's fields, 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 table draws a column per field, headed by the label its entry in fields gives, so a heading reads "Published at", not publishedAt. A load that reads through its services reads 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.

total is 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 in contributes.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 no replace names 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>
  );
}
PropWhat it is
widgetIdThe widget's id.
placementIdThe 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.
settingsThis card's settings, already resolved: the reader's stored values where they are usable, your declared defaults everywhere else, typed from the declaration.
sizeThe card's w and h in grid units, and its tier: "small", "medium" or "large".
dataThe card's answer, always present: the frame draws loading, not available and error itself, and calls your component only once there is data.
refreshingWhether a newer answer is on its way; data is the last one until it lands.
retryAsks 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 by where in 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.