EmDash プラグインは sandboxed または native のどちらかの形式を使います。オーサリング形状、インストール経路、信頼境界が異なるため、プラグインを書く前に形式を選んでください。
プラグインが native 専用の統合を必要としない限り、sandboxed プラグインを選んでください。sandboxed プラグインはレジストリに公開し、管理 UI からインストールできます。native プラグインは、サイト運用者がプロジェクトにインストールし、再デプロイ前に astro.config.mjs に追加する npm パッケージです。
一目で
| Sandboxed | Native | |
|---|---|---|
| Authoring shape | emdash-plugin.jsonc + src/plugin.ts | definePlugin() descriptor |
| Install method | One-click from the admin registry | npm install + edit astro.config |
| Runs in | An isolated runtime provided by a sandbox runner | Same process as your Astro site |
Capability-gated ctx APIs | Enforced by the sandbox bridge | Gated by PluginContext, but not a security boundary |
| Resource limits | Runner limits for CPU, subrequests, and wall time; platform memory ceiling | No per-plugin limits |
| Network access | ctx.http, restricted to declared access | ctx.http follows declarations; native code can also call fetch() |
Direct fetch() / process.env | Blocked by the runner | Possible (plugin code shares the runtime) |
| Distribution | Signed release in the plugin registry | npm package |
| Admin UI | Block Kit (JSON-described) routes | React components, or Block Kit |
| Settings UI | Block Kit page + ctx.settings | admin.settingsSchema (auto-form) or Block Kit |
| Portable Text rendering components | Not available | componentsEntry provides Astro components |
| Page metadata contributions | page:metadata hook — meta/property tags, allowlisted <link> rels, JSON-LD | page:metadata hook (same surface) |
| Page fragment injection | Not available — meta/JSON-LD only via page:metadata | page:fragments hook — inline scripts, external scripts, raw HTML |
| Constructor options | None — read settings from KV at runtime | options on the descriptor |
native プラグインのコスト
native プラグインには異なるインストールと信頼モデルがあります。
- プロジェクト単位のインストール。 すべてのサイトが npm パッケージをインストールし、
astro.config.mjsを編集して再デプロイする必要があります。 - 分離なし。 プラグインのバグがホストプロセスをクラッシュさせたり、CPU 予算を消費したりします。フック内の未処理の rejection が周囲のリクエストも巻き添えにすることがあります。
- ユーザー側の信頼負担。 native プラグインはホストサイトと同じアクセスを持ちます。ケイパビリティ宣言だけでは、コードができることのすべてを示せません。
プラグインがサンドボックスで仕事をできるなら、そうすべきです。
native にするとき
ホストサイトとのビルド時統合が必要な機能には native を選んでください。
-
カスタム React 管理ページまたはウィジェット。 sandboxed プラグインは管理 UI を Block Kit — 管理画面がプラグインの代わりにレンダリングする JSON スキーマ — で記述します。フル React（カスタムフック、サードパーティコンポーネント、複雑な状態）が必要なら native が必要です。
-
カスタム Portable Text ブロック型。 編集設定と Astro レンダリングコンポーネントはインストール済み npm パッケージから読み込まれます。そのビルド時サーフェスを提供できるのは native プラグインだけです。
-
公開ページへの生 HTML、スクリプト、スタイルシートの注入。
page:fragmentsフックは訪問者のブラウザにファーストパーティコードを送ります — どのサンドボックス境界の外でも。native プラグインに限定されています。sandboxed プラグインは、多くの実用例をカバーするpage:metadataフック経由で公開ページに引き続き貢献できます。metaタグ（name+content）— SEO 説明、robots ディレクティブ、Twitter カードpropertyタグ — OpenGraph やその他の property ベースのメタ- セキュリティで固定された rel 許可リスト付きの
linkタグ（canonical、alternate、author、license、nlweb、site.standard.document）—stylesheet、prefetch、および同様のリソース読み込み rel は意図的に許可されていません - JSON-LD グラフ
「ページ注入」の必要が構造化データや SEO メタデータなら、sandboxed のまま
page:metadataを使ってください。訪問者のブラウザに実際に JavaScript や HTML を送る必要があるなら、それが native にするケースです。
これらの機能のいずれも当てはまらない場合は、sandboxed 形式を使ってください。
サンドボックスランナーとプラットフォームサポート
サンドボックス自体は差し替え可能です。EmDash は sandboxRunner 設定オプションを公開し、ランナーがプラグインコードの分離方法を決めます — プラグイン形式自体に Cloudflare 固有のものはありません。
EmDash には 2 つのランナーが同梱されています。@emdash-cms/cloudflare の sandbox() は Cloudflare の Worker Loader 経由で各プラグインを Dynamic Worker として実行し、@emdash-cms/sandbox-workerd/sandbox は Node.js 上の workerd 子プロセスでプラグインを実行します。Plugin Sandbox では各ランナーのセットアップ、適用するリソース制限、両者の違いを扱います。
ランナーが構成されていない場合、sandboxed: [] に列挙されたプラグインは読み込まれません。構成済みランナーが現在のプラットフォームで利用できない場合も読み込まれず、EmDash は起動時に警告を記録します。
サンドボックスランナーのないプラットフォームで sandboxed プラグインを動かしたい場合は、sandboxed: [] から plugins: [] 配列へ移してください — プロセス内で実行されます。ケイパビリティ宣言は引き続き守られます（同じ PluginContext ファクトリが ctx.content、ctx.http などをゲートします）が、分離境界もリソース制限もなく、バグのあるまたは悪意のあるプラグインが fetch() を直接呼び、環境変数を読み、イベントループをブロックできます。サンドボックスランナーが有効でないときは、信頼の観点ですべてのプラグインを native プラグインとして扱ってください。