Skip to content

Distributing native plugins

Native plugins are npm packages installed in the host project and registered in astro.config.mjs. The package needs a built server entry for its descriptor and createPlugin(). If it also ships React or Astro components, export those as separate source entrypoints so the host can compile them for the correct environment.

The following layout separates the server runtime from browser and Astro source:

plugin-activity/
├── src/
│ ├── index.ts
│ ├── admin/
│ │ ├── index.tsx
│ │ └── ActivityPage.tsx
│ └── astro/
│ ├── index.ts
│ └── ActivityBlock.astro
├── dist/
│ ├── index.mjs
│ └── index.d.mts
├── package.json
├── tsconfig.json
└── README.md

dist/ is generated. Keep src/admin/ and src/astro/ in the published tarball because the host’s Vite and Astro build must process those entrypoints.

The following package.json builds the server entry and publishes all three entrypoints:

package.json
{
"name": "@example/plugin-activity",
"version": "0.1.0",
"type": "module",
"main": "./dist/index.mjs",
"exports": {
".": {
"types": "./dist/index.d.mts",
"import": "./dist/index.mjs"
},
"./admin": "./src/admin/index.tsx",
"./astro": "./src/astro/index.ts"
},
"files": ["dist", "src/admin", "src/astro"],
"scripts": {
"build": "tsdown src/index.ts --format esm --dts --clean",
"dev": "tsdown src/index.ts --format esm --dts --watch",
"typecheck": "tsc --noEmit",
"prepublishOnly": "pnpm typecheck && pnpm build"
},
"peerDependencies": {
"@cloudflare/kumo": "2.19.0",
"@emdash-cms/admin": "*",
"@lingui/core": "*",
"@lingui/react": "*",
"@tanstack/react-query": "*",
"astro": ">=6.0.0-beta.0",
"emdash": "*",
"react": "^18.0.0 || ^19.0.0"
},
"devDependencies": {
"@types/react": "^19.0.0",
"tsdown": "^0.20.0",
"typescript": "^5.9.0"
},
"keywords": ["emdash", "emdash-plugin"],
"license": "MIT"
}

Remove ./admin, src/admin, and the admin-only peer dependencies when the plugin has no trusted React UI. Remove ./astro, src/astro, and the astro peer when it has no Portable Text renderer. Add a peer dependency for every host-owned library imported by an exported source entrypoint; this prevents a second React, Kumo, Lingui, or React Query instance from entering the admin bundle. Declare @cloudflare/kumo with one exact version and no range, as described in Match the admin’s Kumo version.

The entrypoints have different consumers:

Export Required when Consumer
. Always Astro configuration imports the descriptor factory; EmDash imports the named createPlugin() at runtime.
./admin adminEntry is set The host’s browser build imports the React component maps.
./astro componentsEntry is set The host’s Astro build imports blockComponents.

The module specifiers in the descriptor and runtime must match these exports:

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",
componentsEntry: "@example/plugin-activity/astro",
};
}
export function createPlugin() {
return definePlugin({
id: "plugin-activity",
version: "0.1.0",
admin: {
entry: "@example/plugin-activity/admin",
},
});
}

Keep the npm package version, descriptor version, and definePlugin() version synchronized. The version shown to a site administrator comes from the plugin definition, not automatically from package.json.

The admin ships a prebuilt stylesheet generated from the exact Kumo version that @emdash-cms/admin depends on. A plugin whose ./admin entrypoint imports @cloudflare/kumo must use that same version. With a different version, the site installs a second copy of Kumo whose components can use classes missing from the admin’s stylesheet, so the plugin’s controls can render unstyled or invisible.

Set the @cloudflare/kumo peer dependency to the admin’s Kumo version, as the package.json example above does. Each emdash release depends on the @emdash-cms/admin release with the same version number. The following command prints the Kumo version of the latest admin release; replace latest with the emdash version the plugin targets:

Terminal window
npm view @emdash-cms/admin@latest dependencies.@cloudflare/kumo

When an emdash release moves the admin to a different Kumo version, publish a plugin release pinned to the new version, and tell operators in its release notes to update the plugin and emdash together. A site that updates only one of them installs two Kumo versions, and a site that installs @cloudflare/kumo itself must use the same version. Run pnpm why @cloudflare/kumo in the site to list each installed Kumo version and the packages that require it.

Upgrade to Kumo 2.19 lists the component changes that can affect plugin admin code when moving from Kumo 2.15.

definePlugin() accepts either an unscoped ID containing lowercase letters, digits, and hyphens, or a scoped ID in the form @scope/name. Use an unscoped, kebab-case ID for a site plugin because the ID also occupies one path segment in /_emdash/api/plugins/<plugin-id>/<route>.

The following values show the accepted forms and the recommended separation between plugin ID and npm package name:

id: "plugin-activity"; // Recommended: valid in plugin route URLs
id: "@example/plugin-activity"; // Accepted by definePlugin(), but not one URL segment
entrypoint: "@example/plugin-activity"; // The npm package may stay scoped

Versions must begin with a semantic major.minor.patch sequence. Use a complete semantic version for both the descriptor and runtime:

version: "1.0.0"; // Valid
version: "1.2.3-beta.1"; // Valid prerelease
version: "1.0"; // Invalid: missing patch version

The following tsconfig.json covers a native plugin with React and Astro source:

tsconfig.json
{
"compilerOptions": {
"target": "ES2022",
"module": "preserve",
"moduleResolution": "bundler",
"strict": true,
"declaration": true,
"outDir": "./dist",
"rootDir": "./src",
"jsx": "react-jsx",
"types": ["astro/client"]
},
"include": ["src/**/*"],
"exclude": ["node_modules", "dist"]
}

Run pnpm typecheck against the source entrypoints before packaging. The build script compiles only src/index.ts; the host compiles the exported admin and Astro source when it consumes the package.

Test the exact tarball contents before publishing. The commands below assume a disposable site named my-emdash-site sits beside the plugin directory.

  1. Build and type-check the package.

    Terminal window
    pnpm typecheck
    pnpm build
  2. Create the npm tarball and review the file list printed by npm.

    Terminal window
    npm pack

    For the example package, npm creates example-plugin-activity-0.1.0.tgz.

  3. Confirm that the output contains dist/index.mjs, dist/index.d.mts, and every source file reachable from the exported ./admin and ./astro modules.

  4. Install the produced tarball in the disposable EmDash site.

    Terminal window
    cd ../my-emdash-site
    pnpm add ../plugin-activity/example-plugin-activity-0.1.0.tgz
  5. Import and register the descriptor factory in the disposable site’s astro.config.mjs, following Create and register the package. Then build the host site.

    Terminal window
    pnpm build

    Open every plugin admin surface and render every contributed Portable Text block. Registering before the build makes Astro resolve the tarball’s ./admin and ./astro exports; a server-only package test cannot catch a missing browser or .astro source file.

Give an operator enough information to install and evaluate the package without reading its source. Include:

  • a one-sentence description and the supported EmDash version
  • the install command and complete astro.config.mjs registration
  • the native trust boundary and why the plugin needs native execution
  • every declared capability and allowed host, with the feature that uses it
  • settings and their defaults
  • required layout components, such as EmDashBodyEnd for a body-end fragment
  • upgrade steps for changes that require operator action

Do not describe capability declarations as an isolation boundary. They gate ctx APIs, but native code can still use imports, environment variables, and direct network calls available to the host process.

Publish after the tarball test passes:

Terminal window
npm publish --access public

The first public release of a scoped package needs --access public. Use semantic versioning for later releases. Treat changes to constructor options, stored data, required host changes, package exports, or the plugin’s trust requirements as compatibility decisions. If an upgrade requires a new capability or allowed host, call it out in the release notes even though native installs do not have a capability-consent prompt.

An operator installs the published package in the EmDash site:

Terminal window
pnpm add @example/plugin-activity

Then import and register its descriptor factory in astro.config.mjs as shown in Create and register the package. Installing the dependency alone does not activate the plugin; changing the Astro configuration and deploying the site completes the installation.

Build the plugin in watch mode:

Terminal window
pnpm dev

Install the local directory from the host site:

Terminal window
pnpm add ../plugin-activity

Register the plugin’s descriptor factory in astro.config.mjs, then start the host development server. Restart the server after changing descriptor metadata or package exports. If a package-manager file dependency copies files instead of linking them in your setup, reinstall it after rebuilding; a workspace dependency or pnpm link keeps the local package connected during development.

Native packages cannot be published to the EmDash registry. Registry plugins use the sandboxed package format, signed release workflow, and installation consent flow. If the plugin no longer needs React admin code, Astro renderers, trusted fragments, or another in-process dependency, convert it to the sandboxed format before publishing through the registry.

To support an emdash release whose admin uses Kumo 2.19.0, set the plugin’s @cloudflare/kumo peer dependency to 2.19.0 and open every plugin admin surface in a site running that release. The plugin may work without further changes. If a test fails or a control looks different, check the changes below. The Kumo changelog lists every change from 2.16.0 to 2.19.0.

In Kumo 2.15, Radio.Group rendered an unnamed role="radiogroup" element around a <fieldset> named by its legend.

Radio.Group renders one <fieldset role="radiogroup">, named by its legend or Radio.Legend.

Update tests that find a radio group by its legend to query the radiogroup role. The following Testing Library or Playwright query shows the change:

getByRole("group", { name: "Recording mode" });
getByRole("radiogroup", { name: "Recording mode" });

In Kumo 2.15, DatePicker was styled by .rdp-* rules and --rdp-* variables in Kumo’s stylesheet.

Kumo styles each DatePicker part with classes that it passes through classNames, and its stylesheet has no .rdp-* rules or --rdp-* variables apart from the month-change animations. A classNames key you pass, other than root, replaces all of Kumo’s classes for that part. className adds classes to the picker’s root element.

Remove --rdp-* variable overrides and classNames entries that adjusted Kumo’s .rdp-* styles, such as day_button or month_grid, and pass layout classes through className. The following example removes an override that centered the day buttons, which Kumo centers itself:

<DatePicker
mode="single"
selected={date}
onChange={setDate}
classNames={{ day_button: "rdp-day_button !mx-auto" }}
/>

In Kumo 2.15, a max-h-* class on a Dialog set its maximum height at every window width.

Dialog keeps its content within the window’s height and scrolls taller content. On windows at least 640px wide, that limit takes precedence over a max-h-* class on the dialog.

Set the dialog’s own maximum height with the style prop. An inline maxHeight replaces Kumo’s window limit at every width, so include a viewport unit when the value could be taller than the window:

<Dialog className="flex max-h-[min(88dvh,46rem)] flex-col">
<Dialog className="flex flex-col" style={{ maxHeight: "min(88dvh, 46rem)" }}>
⌂ 换网址