このガイドは、以前のdefinePlugin()形式に対して書かれたサンドボックスプラグインの作成者向けです。破壊的変更を順番に処理してください。これらはいずれも、実行時のフックやルートの動作を変更するものではありません。プラグインの宣言、ビルド、公開方法を変更します。
各パッケージの変更の完全なリストについては、EmDash changelogを参照してください。
破壊的変更
名称変更：@emdash-cms/registry-cliは現在@emdash-cms/plugin-cliです
以前のリリースでは、CLIを@emdash-cms/registry-cliとして、emdash-registryバイナリで提供していました。
パッケージは現在@emdash-cms/plugin-cliで、バイナリはemdash-pluginです。古いパッケージは公開されなくなりました。
何をすべきですか？
依存関係を置き換えます：
pnpm remove @emdash-cms/registry-cli
pnpm add -D @emdash-cms/plugin-cli呼び出すすべての場所でemdash-registryをemdash-pluginに置き換えます。すべてのサブコマンドは名前を維持し（bundle、publish、login、whoami、switch、validate）、init、build、devが追加されます。プラグインCLIを参照してください。
変更：サンドボックスプラグインはsatisfies SandboxedPluginで定義されます
以前のリリースでは、emdashからインポートされたdefinePlugin()でプラグインのフックとルートをラップし、各ハンドラーのパラメータを手動で注釈していました。
サンドボックスプラグインは現在、satisfies SandboxedPluginで注釈された単純なデフォルトエクスポートです。型はemdash/pluginから提供されます。これは、バンドラーが消去する型のみのエントリポイントです。TypeScriptは、フックまたはルート名から各ハンドラーのeventとctxを推論するため、ハンドラーのパラメータには注釈が不要です。
何をすべきですか？
プラグインのソースファイルに4つの変更を加えます。インポートを置き換えます：
import { definePlugin, type ContentHookEvent, type PluginContext } from "emdash";
import type { SandboxedPlugin } from "emdash/plugin";definePlugin()ラッパーを単純なオブジェクトとsatisfies注釈に置き換えます：
export default definePlugin({ /* hooks, routes */ });
export default { /* hooks, routes */ } satisfies SandboxedPlugin;すべてのハンドラーからパラメータ注釈を削除します：
handler: async (event: ContentHookEvent, ctx: PluginContext) => {
handler: async (event, ctx) => {結果は、単一のデフォルトエクスポートされたオブジェクトです：
import type { SandboxedPlugin } from "emdash/plugin";
export default {
hooks: {
"content:beforeSave": {
handler: async (event, ctx) => {
return event.content;
},
},
},
} satisfies SandboxedPlugin;ヘルパー関数でイベント型を命名するには、emdash/pluginからインポートします：
import type { ContentHookEvent, PluginContext } from "emdash/plugin";ハンドラーのeventは、常にそのフックの正規の型です。より狭いインターフェースでハンドラーに注釈を付けることは、型チェックに合格しなくなりました。依存するフィールドは、typeofチェックまたはガードを使用して実行時に検証してください。これは、型システムの外部から来るデータの正しいアプローチです。
変更：プラグインはsrc/plugin.tsとemdash-plugin.jsoncです
以前のリリースでは、プラグインを2つのファイルに分割していました：src/index.tsはPluginDescriptor（id、version、capabilities、storage、entrypoint）を返し、src/sandbox-entry.tsはフックとルートを保持していました。
プラグインは現在、1つのランタイムファイルsrc/plugin.ts（フックとルート）と、手動編集されたマニフェストemdash-plugin.jsonc（アイデンティティと信頼契約）です。entrypointとformatフィールドはなくなりました。ビルドがそれらを接続します。
何をすべきですか？
上記の形式を使用して、フックとルートをsrc/plugin.tsに移動します。記述子のメタデータをpackage.jsonの横にあるemdash-plugin.jsoncに移動します。記述子のidはマニフェストのslugになります。capabilities、allowedHosts、storageは形式を保持します。versionはpackage.jsonから読み取られるため、省略してください。
次の例は、ストレージコレクションを宣言した記述子のマニフェスト相当を示しています：
{
"$schema": "./node_modules/@emdash-cms/plugin-cli/schemas/emdash-plugin.schema.json",
"slug": "plugin-hello",
"publisher": "did:plc:abc123def456",
"license": "MIT",
"author": { "name": "Jane Doe", "url": "https://example.com" },
"security": { "email": "[email protected]" },
"capabilities": [],
"allowedHosts": [],
"storage": { "events": { "indexes": ["timestamp"] } }
}すべてのフィールドについてはプラグインマニフェストを、publisherフィールドについてはパブリッシャーピン留めを参照してください。
package.jsonで、"./sandbox"エクスポートをビルドされたランタイムファイルに向けます：
"./sandbox": "./dist/sandbox-entry.mjs"
"./sandbox": "./dist/plugin.mjs"マニフェストをfilesに追加して、パッケージと一緒に出荷されるようにします：
"files": ["dist"]
"files": ["dist", "emdash-plugin.jsonc"]変更：emdash-plugin buildでビルド
以前のリリースでは、手書きのtsdownスクリプトで2つのソースファイルをビルドしていました。
emdash-plugin buildはemdash-plugin.jsoncとsrc/plugin.tsを読み取り、dist/アーティファクトを出力します。emdash-plugin devは監視して再ビルドします。
何をすべきですか？
ビルドスクリプトを置き換え、監視スクリプトを追加します：
"scripts": {
"build": "tsdown src/index.ts src/sandbox-entry.ts --format esm --dts --clean"
"build": "emdash-plugin build",
"dev": "emdash-plugin dev"
}次に検証してビルドします：
emdash-plugin validate
emdash-plugin build削除：emdashからの標準形式の型と関数エクスポート
以前のリリースでは、StandardPluginDefinition、StandardHookHandler、StandardHookEntry、StandardRouteHandler、StandardRouteEntry、および関数isStandardPluginDefinitionをemdashからエクスポートしていました。
これらは削除されました。以前のdefinePlugin形式のヘルパーエイリアスでした。
何をすべきですか？
同じ目的でemdash/pluginのSandboxedPluginを使用してください。サンドボックスプラグインのデフォルトエクスポートは、すでにsatisfies SandboxedPlugin注釈によって型付けされているため、isStandardPluginDefinitionの代替はありません。必要に応じて、構造（{ hooks?, routes? }）でプラグインを識別してください。
名称変更：ランタイム型SandboxedPluginは現在SandboxedPluginInstanceです
これは、@emdash-cms/cloudflareなどのカスタムSandboxRunnerの作成者にのみ影響します。ほとんどのプラグイン作成者はスキップできます。
emdashのSandboxedPluginは、現在、作成者向けのソース形式を指します。SandboxRunner.loadによって返されるランタイムハンドルはSandboxedPluginInstanceです。
何をすべきですか？
サンドボックスランナーを型付けするため、またはランタイムプラグインハンドルを保持するためにemdashからSandboxedPluginをインポートする場合は、インポートをSandboxedPluginInstanceに変更します：
import type { SandboxedPlugin } from "emdash";
import type { SandboxedPluginInstance } from "emdash";ユーザーに伝える
プラグインをインストールするサイトもインポートを変更する必要があります。新しい形式を指示してください：中括弧と()を削除します。
import { helloPlugin } from "@my-org/plugin-hello";
import hello from "@my-org/plugin-hello";
export default defineConfig({
integrations: [
emdash({
sandboxed: [helloPlugin()],
sandboxed: [hello],
}),
],
});プラグインがファクトリを通じて構成を受け入れていた場合、その構成は管理UIのプラグイン設定に移動します。実行時にctx.kvまたは設定を介して読み取ります。設定を参照してください。