React admin extensions
Native plugins can load trusted React components into the EmDash admin. The host keeps control of navigation, page routing, dashboard cards, editor layout, content tables, authentication, and error boundaries. The plugin supplies the components and the metadata needed to place them.
If the plugin only needs a settings form, start with admin.settingsSchema. It uses the host’s form components and does not require a React entrypoint. Sandboxed plugins can also use this generated form; the custom React extensions on this page require a native plugin.
Generated settings form
Section titled “Generated settings form”Declare settingsSchema inside the runtime definition. The following schema produces a multiline text field, a select, a number input, a switch, and a write-only secret input:
return definePlugin({ id: "plugin-activity", version: "0.1.0", admin: { settingsSchema: { projectName: { type: "string", label: "Project name", description: "Name shown in activity exports", }, notes: { type: "string", label: "Internal notes", multiline: true, }, mode: { type: "select", label: "Recording mode", options: [ { value: "creates", label: "New entries only" }, { value: "all", label: "New and updated entries" }, ], default: "all", }, retentionDays: { type: "number", label: "Retention in days", min: 1, max: 365, default: 30, }, enabled: { type: "boolean", label: "Record activity", default: true, }, exportToken: { type: "secret", label: "Export token", }, }, },});The available fields have the following options. label is required and description is optional for every type.
type |
Value | Additional fields |
|---|---|---|
string |
string | default, multiline |
number |
number | default, min, max |
boolean |
boolean | default |
select |
string | required options: Array<{ value, label }> and optional default |
secret |
string | no additional fields; the stored value is never returned to the browser |
url |
string | default, placeholder |
email |
string | default, placeholder |
The form is available from the settings control on the plugin’s card in Plugins. Reading or changing it requires plugins:manage.
Settings use the plugin’s namespaced settings store. A field named retentionDays is available to the plugin as retentionDays:
const retentionDays = (await ctx.settings.get<number>("retentionDays")) ?? 30;Schema defaults fill the generated form when no value is stored, but EmDash does not write those defaults to the settings store. Apply the same fallback when the runtime reads the setting. Clearing a non-secret field deletes its stored value and returns the form to its default. Secret values are encrypted before persistence and never sent back to the browser; the form reports only whether a secret is set and lets an administrator replace or clear it.
Settings labels and descriptions render as declared. If those strings must change with the admin locale, build a custom React settings page instead.
React entrypoint
Section titled “React entrypoint”A trusted React extension has three connected declarations:
- The descriptor’s
adminEntrytells Astro which module to bundle into the admin. - The runtime’s
admin.entry,admin.pages, andadmin.widgetsdescribe the visible admin surfaces. - The admin module exports component maps whose keys match the declared page paths and widget IDs. Field widgets are the exception: they are resolved by name from the
fieldsexport and need no declaration.
The descriptor only needs the module specifier. Page and widget metadata belongs in the runtime definition:
export function activityPlugin(): PluginDescriptor { return { id: "plugin-activity", version: "0.1.0", format: "native", entrypoint: "@example/plugin-activity", adminEntry: "@example/plugin-activity/admin", };}
export function createPlugin() { return definePlugin({ id: "plugin-activity", version: "0.1.0", storage: { events: { indexes: ["createdAt"] }, }, admin: { entry: "@example/plugin-activity/admin", pages: [{ path: "/activity", label: "Activity", icon: "clock" }], widgets: [{ id: "recent-activity", title: "Recent activity" }], }, });}Keep adminEntry and admin.entry identical. The first is a build-time import; the second tells the runtime that the plugin uses trusted React admin components.
Admin pages
Section titled “Admin pages”Each page declaration has the following fields:
| Field | Required | Behavior |
|---|---|---|
path |
Yes | Mounts the page at /_emdash/admin/plugins/<plugin-id><path>. Use a leading slash. |
label |
Yes | Supplies the sidebar and command-palette label. |
icon |
No | Names a Phosphor icon in kebab, snake, space-separated, or PascalCase form. Unknown names fall back to the plugin icon. |
group |
No | Places the page in a collapsible sidebar folder. A group that matches the group of a collection shown in the sidebar (case-sensitive, ignoring surrounding whitespace) puts the page in that folder after its collections and taxonomies; otherwise pages sharing the group, from any plugin, form a folder in the Plugins section. |
The admin module maps each declared path to a React component. A trailing slash is treated as equivalent, and the plugin root opens the first exported page when no / page exists.
The following page loads a private plugin route. Use Kumo for controls and apiFetch() for plugin API requests; apiFetch() adds the X-EmDash-Request: 1 header required by cookie-authenticated private routes.
import { Button, Loader } from "@cloudflare/kumo";import { useLingui } from "@lingui/react";import { apiFetch, parseApiResponse } from "emdash/plugin-utils";import * as React from "react";
interface ActivitySummary { count: number;}
export function ActivityPage() { const { i18n } = useLingui(); const [summary, setSummary] = React.useState<ActivitySummary>(); const [error, setError] = React.useState<string>();
const load = React.useCallback(async () => { setError(undefined); try { const response = await apiFetch( "/_emdash/api/plugins/plugin-activity/summary", ); setSummary( await parseApiResponse<ActivitySummary>( response, i18n._({ id: "activity.load-error", message: "Could not load activity" }), ), ); } catch (cause) { setError(cause instanceof Error ? cause.message : String(cause)); } }, [i18n]);
React.useEffect(() => { void load(); }, [load]);
return ( <section className="space-y-4"> <h1 className="text-2xl font-semibold"> {i18n._({ id: "activity.title", message: "Activity" })} </h1> {summary ? ( <p> {i18n._({ id: "activity.count", message: "Event count" })}: {summary.count} </p> ) : error ? ( <p role="alert" className="text-kumo-danger">{error}</p> ) : ( <Loader /> )} <Button type="button" onClick={() => void load()}> {i18n._({ id: "activity.refresh", message: "Refresh" })} </Button> </section> );}Define the corresponding route in the native runtime. Native handlers receive one context argument:
routes: { summary: { permission: "plugins:read", handler: async (ctx) => ({ count: await ctx.storage.events.count(), }), },},Private routes default to the administrator-only plugins:manage permission. Declare the narrowest existing permission that matches the operation. Use public: true only for an endpoint intended for unauthenticated internet traffic.
Export the page from the admin entrypoint:
import type { PluginAdminExports } from "emdash";
import { ActivityPage } from "./ActivityPage.js";
export const pages: PluginAdminExports["pages"] = { "/activity": ActivityPage,};Page labels are translated through the admin’s shared Lingui instance when a loaded catalog has an entry for them. A plugin can load its own message catalog into the shared instance for plugin-specific labels and component messages; otherwise the declared English message is the fallback.
Load the plugin catalog when the admin entrypoint is imported, then load it again after the administrator changes locale. The following small German catalog uses the same IDs as the page and widget examples:
import { i18n } from "@lingui/core";
const catalogs: Record<string, Record<string, string>> = { de: { Activity: "Aktivität", "activity.title": "Aktivität", "activity.count": "Ereignisanzahl", "activity.refresh": "Aktualisieren", "activity.load-error": "Aktivität konnte nicht geladen werden", "activity.unavailable": "Nicht verfügbar", "activity.default-locale": "Standardsprache", },};
function loadPluginCatalog() { const messages = catalogs[i18n.locale]; if (!messages || "activity.title" in i18n.messages) return; i18n.load(i18n.locale, messages);}
loadPluginCatalog();i18n.on("change", loadPluginCatalog);Import the loader for its registration side effect before exporting components:
import "./i18n.js";
// Page, widget, panel, and column exports follow.The admin replaces its active catalog when the locale changes. The change listener restores the plugin messages, and the message-ID check prevents i18n.load() from triggering a loop. For more locales, generate the message objects with the plugin’s Lingui build instead of maintaining them by hand. Keep @lingui/core and @lingui/react as peer dependencies so the plugin uses the host’s shared instance.
Dashboard widgets
Section titled “Dashboard widgets”A widget declaration has a required id and optional title and size:
admin: { entry: "@example/plugin-activity/admin", widgets: [ { id: "recent-activity", title: "Recent activity", size: "half" }, ],},Export a component under the same ID. This widget reads the same summary route as the page and supplies only the card content; EmDash supplies the surrounding dashboard card and heading.
import { useLingui } from "@lingui/react";import { useQuery } from "@tanstack/react-query";import type { PluginAdminExports } from "emdash";import { apiFetch, parseApiResponse } from "emdash/plugin-utils";
interface ActivitySummary { count: number;}
async function loadSummary(fallbackMessage: string) { const response = await apiFetch( "/_emdash/api/plugins/plugin-activity/summary", ); return parseApiResponse<ActivitySummary>( response, fallbackMessage, );}
function RecentActivityWidget() { const { i18n } = useLingui(); const { data, isLoading, isError } = useQuery({ queryKey: ["plugin-activity", "summary"], queryFn: () => loadSummary( i18n._({ id: "activity.load-error", message: "Could not load activity" }), ), });
return ( <p> {i18n._({ id: "activity.count", message: "Event count" })}:{" "} {isLoading ? "…" : isError ? i18n._({ id: "activity.unavailable", message: "Unavailable" }) : (data?.count ?? 0)} </p> );}
export const widgets: PluginAdminExports["widgets"] = { "recent-activity": RecentActivityWidget,};The host places the component inside a dashboard card and renders title as its heading. Keep the component compact and do not add a second card shell. size accepts full, half, or third; it is stored as a layout hint, but the current dashboard renders plugin widgets in its responsive two-column grid without applying that hint.
Custom field widgets
Section titled “Custom field widgets”A field widget replaces the editor for one schema field with a component from your plugin. Export a fields map from the admin module, keyed by widget name:
import { useLingui } from "@lingui/react";
interface FieldWidgetProps { value: unknown; onChange: (value: unknown) => void; label: string; id: string; required?: boolean; options?: Record<string, unknown> | Array<{ value: string; label: string }>; validation?: Record<string, unknown>; minimal?: boolean;}
function RatingField({ value, onChange, label, id, options }: FieldWidgetProps) { const { i18n } = useLingui(); const max = !Array.isArray(options) && typeof options?.max === "number" ? options.max : 5; const rating = typeof value === "number" ? value : 0;
return ( <div role="group" aria-labelledby={`${id}-label`} className="grid gap-2"> <span id={`${id}-label`} className="text-sm font-medium"> {label} </span> <div className="flex gap-1"> {Array.from({ length: max }, (_, index) => index + 1).map((step) => ( <button key={step} type="button" id={step === 1 ? id : undefined} aria-pressed={step <= rating} aria-label={i18n._({ id: "rating.set", message: "Rate {step}", values: { step }, })} onClick={() => onChange(step === rating ? null : step)} > {step <= rating ? "★" : "☆"} </button> ))} </div> </div> );}
export const fields = { rating: RatingField,};The plugin needs the adminEntry and admin.entry pair described in React entrypoint so the module loads. Nothing else in the descriptor or the definePlugin() call refers to a field widget.
A schema field opts in by setting widget to <plugin-id>:<widget-name>. The plugin ID is the id passed to definePlugin(), and the widget name is a key of the fields export. The following seed field uses the widget above for a plugin whose ID is plugin-reviews:
{ "slug": "rating", "label": "Rating", "type": "integer", "widget": "plugin-reviews:rating", "options": { "max": 5 }}The schema API accepts widget as well. Choose a field type that can hold the value the widget produces; the widget changes only the editor, not how the value is stored.
The component receives the following props:
| Prop | Type | Behavior |
|---|---|---|
value |
unknown |
The field’s current value in the editor. Narrow it before use. |
onChange |
(value: unknown) => void |
Call with the new value, not an event. |
label |
string |
The field’s label. The host does not render one around a plugin widget, so render it yourself. |
id |
string |
A DOM ID for the field, in the form field-<slug>. |
required |
boolean (optional) |
The field’s required setting. |
options |
object or Array<{ value, label }> (optional) |
The field’s options from the schema, passed through unchanged. Use it for per-field configuration such as max above. When the field has validation.options (select and multiSelect fields), the host passes those instead, as a list of { value, label } items. |
validation |
object (optional) |
The field’s validation rules from the schema. |
minimal |
boolean (optional) |
true when the host asks for a compact rendering without surrounding label chrome. |
The editor wraps each widget in an error boundary. If the component throws while rendering, the field shows a “Plugin widget error” message with a retry button instead of unmounting the editor. If the fields export has no function under the requested name, the editor uses the default editor for the field type. A widget value without a : logs a console warning and also falls back.
Content editor panels
Section titled “Content editor panels”An editor panel adds a host-framed section to the settings sidebar of a saved entry. It does not mount for a new entry because no saved entry exists yet.
Panels and content-list columns are discovered directly from the trusted admin module. They need adminEntry and admin.entry so the module loads, but they do not need entries in admin.pages or admin.widgets.
import type { ContentEditorPanelContext, ContentEditorPanelExtension,} from "@emdash-cms/admin";import { useLingui } from "@lingui/react";
function ActivityPanel({ entry, collection, locale }: ContentEditorPanelContext) { const { i18n } = useLingui(); const displayLocale = locale ?? i18n._({ id: "activity.default-locale", message: "Default locale" });
return ( <p className="text-sm text-kumo-subtle"> {collection}/{entry.slug} ({displayLocale}) </p> );}
export const contentEditorPanels = [ { id: "activity-summary", title: "Activity summary", component: ActivityPanel, collections: ["posts", "pages"], order: 10, },] satisfies readonly ContentEditorPanelExtension[];Panel fields have the following behavior:
id,title, andcomponentare required. The ID must be unique among this plugin’s panels.collectionsis an array of collection names or a predicate. Omit it to show the panel for every collection.minRoleis a numeric visibility threshold. It does not authorize API calls.isVisibleoptionally receives the same context as the component and returnsbooleanorPromise<boolean>. EmDash checks it after the staticcollectionsandminRolefilters. Onlytrueshows the section, including its heading and reorder control. The section stays hidden while the first check for a collection, entry ID, and locale is pending. A throw or rejection hides the section and logs the plugin and panel IDs in the browser console. Results and errors from superseded checks are ignored.ordersorts lower values first. Ties use plugin ID and panel ID.
The component receives the saved entry, its collection, the resolved locale, and editorDraft. Keep its layout responsive to the narrow sidebar. EmDash isolates component, visibility-check, and collection-predicate failures so one panel cannot unmount the editor.
Use isVisible when panel visibility depends on plugin settings loaded from an API. Returning null from the component hides only its contents, not the host-rendered section. Checks run again when the saved entry, collection, resolved locale, or eligible panel set changes. When the same entry is saved again, including by autosave or publication, the section keeps its last visibility decision while the new check is pending. A visible panel stays mounted and keeps its local state if the recheck returns true. Any other result, throw, or rejection hides it. Changing the collection, entry ID, or resolved locale starts a new first check with the section hidden. Cache settings requests in your plugin if multiple checks can share them; visibility checks do not authorize API calls.
entry holds the entry as last saved. editorDraft works with the values open in the editor, including changes the user has not saved yet. Its get() method reads them, and its patch() method puts new values into the form without saving the entry. Both methods return synchronously.
editorDraft is undefined on EmDash versions without draft access. Hide the panel’s draft actions when it is missing, or declare the minimum emdash version in the plugin’s peerDependencies.
Read unsaved values with get()
Section titled “Read unsaved values with get()”get() returns a snapshot with the following properties:
| Property | Contents |
|---|---|
revision |
An opaque string that identifies the values the snapshot was read from. Pass it to patch() as expectedRevision. |
readOnly |
true when the editor does not accept edits: another user holds the edit lock, the user cannot edit the entry, the collection has a field type the editor does not support, or a version of the entry is open in the revision view. |
fields |
A copy of each draft value, keyed by field slug. A field without a value is null. |
fieldDefinitions |
One EditorDraftFieldDefinition per draft value, with slug, label, schema type, required, translatable, and validation. |
Each value appears as the editor holds it, which is not always its stored type. For example, a boolean loaded from storage is 0 or 1 until the user changes it. Changing a snapshot does not change the form.
The draft includes every collection field except reference fields bound to a relation and fields whose type the editor does not support. It also includes three values that are not collection fields, under keys that no field slug can take:
| Key | Value | Present | Definition |
|---|---|---|---|
slug |
The entry’s slug | Always | slug type |
seo.title |
The SEO title | In collections with SEO | string type, validation.maxLength of 200 |
seo.description |
The meta description | In collections with SEO | text type, validation.maxLength of 500 |
An empty slug or SEO value is null. The definitions of these keys use the labels the editor shows, in the admin’s language. If the panel writes values through the content API instead, send these keys as slug and seo: { title, description }, not in data. The draft does not include bylines, taxonomy terms, the status, or the other SEO settings.
Change the form with patch()
Section titled “Change the form with patch()”patch(operations, { expectedRevision }) takes the revision from a snapshot and an array of operations. Each operation replaces a whole value:
{ op: "set", field, value }sets a value. Anullvalue clears it.{ op: "clear", field }clears a value.
A successful patch writes the values into the form without saving the entry. A patch to collection fields or the slug marks the entry as having unsaved changes. The form autosaves on its usual schedule, and the user can keep, edit, or save the values like typed changes. In a collection with revisions, the first save that includes the patched values keeps the previous draft in the revision history, so the user can restore it. A patched rich text field reloads with the new value and starts a new undo history. Patching slug has the same effect as typing in the slug input, so later edits to the title leave the slug unchanged.
With collaborative editing on, a patch goes into the document everyone in the entry shares, and the room’s regular saves save it like typed edits. Those saves don’t keep the previous draft in the revision history, so the revision history can’t restore the values from before the patch. A patched rich text field keeps its undo history, and one undo step reverts the patch. Draft values another person changes after get() make a patch with that revision stale.
patch() never throws, and a refused patch changes nothing. It returns { ok: true } or { ok: false, code, message }. message is English text for developers, so show the user your own localized text based on code. The editor checks the patch in the following order and returns the first failure:
code |
Returned when |
|---|---|
EDITOR_DRAFT_STALE |
A draft value changed after get() returned expectedRevision, or the editor has switched to another entry or locale, or closed. |
EDITOR_DRAFT_READ_ONLY |
The editor does not accept edits. |
EDITOR_DRAFT_INVALID |
An operation or one of its values is not allowed, as listed below. message names the operation and field. |
The revision follows the draft values. A patch is stale when the draft values differ from the ones get() read, whether the user typed the change, a patch wrote it, or the editor reloaded the entry with different values after a save. A completed autosave does not change the values, so it leaves the revision current. Call get() again before each patch.
When the editor switches to another entry or locale, or closes, the editorDraft object it passed to the panel stops working for good. Its get() returns an empty, read-only snapshot and its patch() returns EDITOR_DRAFT_STALE, even after the user returns to the same entry. While an image or gallery block’s settings are open, the settings sidebar shows them in place of the panels, so the panel unmounts. A task it started earlier can still call patch().
patch() returns EDITOR_DRAFT_INVALID in these cases:
operationsis empty or contains something other thansetandclearoperations.- Two operations name the same field.
- An operation names a field that is not in the draft.
- An operation clears
slugor sets it to anything other than a non-empty string. - An SEO value is longer than the
validation.maxLengthin its definition. - A value cannot be serialized as JSON, or does not have the shape its field type takes.
- A Portable Text value uses marks the rich text editor does not support, or the editor cannot load it.
A set value must have the following shape for its field type:
| Field type | set value |
|---|---|
string, slug, text, url, datetime, select, reference |
string |
number |
finite number |
integer |
integer |
boolean |
true, false, 0, or 1 |
multiSelect |
array of strings |
portableText |
array of objects with a string _type |
repeater, blocks |
array of objects |
image, file |
object that is not an array |
json |
any JSON value |
Other schema rules, such as required fields, length limits, patterns, select choices, reference targets, and slug uniqueness, are checked when the entry is saved and reported as they are for typed values.
Translate a draft from a panel
Section titled “Translate a draft from a panel”The following function reads the translatable text fields, sends them to a private plugin route that calls a translation provider, and patches the results into the form. In a collection with SEO, seo.title and seo.description have the string and text types, so the function translates them too, unless the entry is published. The slug has the slug type and stays unchanged.
import type { ContentEditorDraft, ContentEditorDraftPatchResult,} from "@emdash-cms/admin";import { apiFetch, parseApiResponse } from "emdash/plugin-utils";
const TEXT_TYPES = new Set(["string", "text"]);
async function translate(texts: string[], locale: string): Promise<string[]> { const response = await apiFetch( "/_emdash/api/plugins/plugin-translate/translate", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ texts, locale }), }, ); const result = await parseApiResponse<{ texts: string[] }>( response, "Translation failed", ); return result.texts;}
export async function translateDraft( editorDraft: ContentEditorDraft, locale: string, published: boolean,): Promise<ContentEditorDraftPatchResult | null> { const snapshot = editorDraft.get(); if (snapshot.readOnly) { return { ok: false, code: "EDITOR_DRAFT_READ_ONLY", message: "The editor does not accept edits", }; }
const slugs = snapshot.fieldDefinitions .filter((field) => field.translatable && TEXT_TYPES.has(field.type)) .map((field) => field.slug) .filter((slug) => !(published && slug.startsWith("seo."))) .filter((slug) => typeof snapshot.fields[slug] === "string"); if (slugs.length === 0) return null;
const translated = await translate( slugs.map((slug) => snapshot.fields[slug] as string), locale, );
return editorDraft.patch( slugs.map((slug, index) => ({ op: "set", field: slug, value: translated[index], })), { expectedRevision: snapshot.revision }, );}translateDraft() checks readOnly before it sends anything, so a read-only editor never sends content to the provider. It returns null when no field needs translating. Define the translate route as in Admin pages, with a permission that every user of the panel holds, such as content:edit_own_drafts. A private route without a permission accepts only administrators.
The SEO panel saves a patched seo.title and seo.description within about half a second, so on a published entry they would reach the live page before the user reviews them. translateDraft() therefore leaves the seo. keys out when published is true. To translate a published entry’s SEO text, show those translations in the panel and let the user copy them into the SEO fields.
The following panel calls translateDraft() when the user presses its button, and says where the text goes. If the user edits a draft value while the request runs, patch() returns EDITOR_DRAFT_STALE and the form is unchanged, so the panel asks the user to translate again.
import { Button } from "@cloudflare/kumo";import type { ContentEditorPanelContext } from "@emdash-cms/admin";import { useLingui } from "@lingui/react";import * as React from "react";
import { translateDraft } from "./translate.js";
export function TranslatePanel({ entry, locale, editorDraft }: ContentEditorPanelContext) { const { i18n } = useLingui(); const [working, setWorking] = React.useState(false); const [message, setMessage] = React.useState("");
if (!editorDraft || !locale) { return ( <p className="text-sm text-kumo-subtle"> {i18n._({ id: "translate.unavailable", message: "Translation is not available in this editor.", })} </p> ); }
const handleTranslate = async () => { setWorking(true); setMessage(""); try { const result = await translateDraft(editorDraft, locale, entry.status === "published"); if (result === null) { setMessage( i18n._({ id: "translate.nothing", message: "This entry has no text to translate." }), ); } else if (result.ok) { setMessage( i18n._({ id: "translate.done", message: "The translation is in the form." }), ); } else if (result.code === "EDITOR_DRAFT_STALE") { setMessage( i18n._({ id: "translate.stale", message: "The entry changed during translation. Translate again.", }), ); } else { setMessage( i18n._({ id: "translate.not-applied", message: "The translation could not be added to this entry.", }), ); } } catch { setMessage(i18n._({ id: "translate.error", message: "Translation failed. Try again." })); } finally { setWorking(false); } };
return ( <div className="space-y-3"> <p className="text-sm text-kumo-subtle"> {i18n._({ id: "translate.notice", message: "Translating sends this entry's text, including unsaved changes, to the translation service.", })} </p> <Button type="button" loading={working} onClick={() => void handleTranslate()}> {i18n._({ id: "translate.action", message: "Translate" })} </Button> <p role="status" className="text-sm"> {message} </p> </div> );}Register the component in the contentEditorPanels export of the admin module, as in the first example of this section.
Content-list columns
Section titled “Content-list columns”A content-list column adds read-only cells to active collection lists. The host still owns pagination, row actions, loading and empty states, and the table itself. Columns are not shown in Trash.
The following column uses visibleItems to fetch one page of statuses. Every cell uses the same React Query key, so the requests share one result instead of issuing one request per row.
import { useQuery } from "@tanstack/react-query";import type { ContentListColumnCellContext, ContentListColumnExtension,} from "@emdash-cms/admin";import { apiFetch, parseApiResponse } from "emdash/plugin-utils";
async function loadStatuses( collection: string, locale: string | undefined, ids: readonly string[],) { const response = await apiFetch( "/_emdash/api/plugins/plugin-activity/statuses", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ collection, locale, ids }), }, ); return parseApiResponse<Record<string, string>>( response, "Could not load activity statuses", );}
function ActivityCell({ item, visibleItems, collection, locale,}: ContentListColumnCellContext) { const ids = visibleItems.map((visibleItem) => visibleItem.id); const { data } = useQuery({ queryKey: ["plugin-activity", "statuses", collection, locale ?? null, ids], queryFn: () => loadStatuses(collection, locale, ids), });
return <span>{data?.[item.id] ?? "-"}</span>;}
export const contentListColumns = [ { id: "activity", label: "Activity", cell: ActivityCell, collections: ["posts", "pages"], align: "end", order: 10, },] satisfies readonly ContentListColumnExtension[];Column fields have the following behavior:
id,label, andcellare required. The ID must be unique among this plugin’s columns.headerreplaces the header content with a component;labelremains the host fallback.collections,minRole, andorderbehave like their panel equivalents.alignacceptsstartorendand uses logical alignment for left-to-right and right-to-left locales.
Contributed columns are hidden while the content list’s table is narrower than 42rem (672px), as on phones and portrait tablets, so give anything editors must reach on a phone another home, such as a content editor panel.
Columns cannot add browser-only sorting or filtering. Those controls would affect only the loaded cursor page, not the full server-backed collection.
Disabled plugins
Section titled “Disabled plugins”When an administrator disables the plugin, EmDash removes its pages, widgets, panels, and columns from the admin. Its private routes return not found, and its hooks stop running. Re-enabling the plugin rebuilds the hook pipeline and makes its trusted admin exports available again.
Package the entrypoint
Section titled “Package the entrypoint”Export the admin module separately from the server runtime so Astro can bundle it for the browser with the host’s React, Kumo, and Lingui instances. The plugin must use the exact Kumo version that the installed @emdash-cms/admin uses; Match the admin’s Kumo version explains how to pin it. Distributing native plugins provides the complete package layout, exports, peer dependencies, and build commands.