Skip to content

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.

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:

src/index.ts
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:

src/index.ts
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.

A trusted React extension has three connected declarations:

  1. The descriptor’s adminEntry tells Astro which module to bundle into the admin.
  2. The runtime’s admin.entry, admin.pages, and admin.widgets describe the visible admin surfaces.
  3. 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 fields export and need no declaration.

The descriptor only needs the module specifier. Page and widget metadata belongs in the runtime definition:

src/index.ts
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.

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.

src/admin/ActivityPage.tsx
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:

src/index.ts
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:

src/admin/index.tsx
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:

src/admin/i18n.ts
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:

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

A widget declaration has a required id and optional title and size:

src/index.ts
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.

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

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:

src/admin/index.tsx
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:

seed/seed.json
{
"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.

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.

src/admin/index.tsx
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, and component are required. The ID must be unique among this plugin’s panels.
  • collections is an array of collection names or a predicate. Omit it to show the panel for every collection.
  • minRole is a numeric visibility threshold. It does not authorize API calls.
  • isVisible optionally receives the same context as the component and returns boolean or Promise<boolean>. EmDash checks it after the static collections and minRole filters. Only true shows 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.
  • order sorts 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.

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.

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. A null value 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:

  • operations is empty or contains something other than set and clear operations.
  • Two operations name the same field.
  • An operation names a field that is not in the draft.
  • An operation clears slug or sets it to anything other than a non-empty string.
  • An SEO value is longer than the validation.maxLength in 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.

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.

src/admin/translate.ts
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.

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

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.

src/admin/index.tsx
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, and cell are required. The ID must be unique among this plugin’s columns.
  • header replaces the header content with a component; label remains the host fallback.
  • collections, minRole, and order behave like their panel equivalents.
  • align accepts start or end and 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.

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.

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.

⌂ 换网址