升級網站外掛

This guide is for site operators: people who install plugins into a site. If you write plugins, see Migrating to the plugin CLI instead.

Upgrade your dependencies

Update emdash and your plugin packages to their latest versions, then reinstall and rebuild:

pnpm up --latest emdash @emdash-cms/plugin-audit-log @emdash-cms/plugin-webhook-notifier @emdash-cms/plugin-atproto
pnpm build

After upgrading, your site may build and run without further changes. If the build fails or a plugin stops loading, work through the breaking changes below. Each one tells you exactly what to change.

For the full list of changes in each package, see its entry on the releases page.

Breaking changes

Changed: registry releases can use PDS blobs

Earlier EmDash versions install package artifacts only from an external URL.

Registry releases can now store the package bundle as a blob in the publisher’s Personal Data Server (PDS). EmDash resolves blob-only releases through a record-scoped cache or the publisher’s PDS and verifies the fetched bytes before installation.

What should I do?

Upgrade EmDash before installing a release whose package artifact does not provide an external URL. Publishers that must support older sites can continue to publish the package bundle with emdash-plugin publish --url <https-url>.

Renamed: @emdash-cms/registry-cli is now @emdash-cms/plugin-cli

Earlier releases shipped the plugin registry CLI as @emdash-cms/registry-cli, with an emdash-registry binary.

The package is now @emdash-cms/plugin-cli and the binary is emdash-plugin. The old package is no longer published.

You only have this dependency if you publish plugins or run registry commands from your site repository. Most sites that only install plugins never had it.

What should I do?

Replace the package:

pnpm remove @emdash-cms/registry-cli
pnpm add -D @emdash-cms/plugin-cli

Update any package.json scripts that call the old binary, replacing emdash-registry with emdash-plugin:

emdash-registry publish --url https://example.com/my-plugin-1.0.0.tar.gz
emdash-plugin publish --url https://example.com/my-plugin-1.0.0.tar.gz

Removed: --artifact-base-url

Earlier releases required --artifact-base-url when a manifest declared icons, banners, or screenshots. The CLI uploaded those files with HTTP PUT.

The CLI now uploads listing images to your Atmosphere account as atproto blobs. emdash-plugin publish also builds and uploads the package bundle there by default. The --url option remains available for externally hosted package bundles.

What should I do?

Remove --artifact-base-url and the image-host write credentials from publish scripts. Run emdash-plugin publish from the plugin directory:

emdash-plugin publish

The updated CLI rejects --artifact-base-url instead of ignoring it, so stale scripts fail with migration guidance.

If the command reports MISSING_BLOB_SCOPE, run emdash-plugin logout, then log in again to grant blob upload access.

Changed: published plugins use a default export

Earlier releases exposed first-party plugins as a named export and a factory call, for example import { auditLogPlugin } from "@emdash-cms/plugin-audit-log" used as auditLogPlugin().

These plugins now provide a default export that you pass directly into plugins: or sandboxed:. There is no factory call. This affects @emdash-cms/plugin-audit-log, @emdash-cms/plugin-webhook-notifier, and @emdash-cms/plugin-atproto.

What should I do?

In astro.config.mjs, drop the braces around the import and the () after the plugin name.

The following example shows the change for @emdash-cms/plugin-audit-log, which runs in-process and goes in plugins::

import { auditLogPlugin } from "@emdash-cms/plugin-audit-log";
import auditLog from "@emdash-cms/plugin-audit-log";

export default defineConfig({
	integrations: [
		emdash({
			plugins: [auditLogPlugin()],
			plugins: [auditLog],
		}),
	],
});

Apply the same two edits to the other packages. @emdash-cms/plugin-atproto and @emdash-cms/plugin-webhook-notifier are sandboxed plugins, so they go in sandboxed: instead of plugins:; the import change is identical.

After upgrading

If a third-party plugin still ships a named export and factory call, it has not been updated for this release. Check its changelog. All first-party plugins listed above use the default-export shape.