EmDashプラグインは、サンドボックス型またはネイティブ型の2つの形式のいずれかで提供されます。この選択は、プラグインのインストール方法、実行時の適用内容、利用可能な機能に影響します。
デフォルトではサンドボックス型を使用してください。 サンドボックス型プラグインは、マーケットプレイスで公開でき、管理UIからワンクリックでインストールできます。ネイティブ型プラグインは、コードの変更、npm install、そしてそれを使用したいすべてのサイトでの再デプロイが必要です。サンドボックス型は、エンドユーザーが求めるものです。
サンドボックスが提供できない機能が必要な場合にのみ、ネイティブ型を選択してください。
一覧
| サンドボックス型 | ネイティブ型 | |
|---|---|---|
ディスクリプタのformatフィールド | "standard" | "native" |
| インストール方法 | 管理マーケットプレイスからワンクリック | npm install + astro.configの編集 |
| 実行環境 | サンドボックスランナーによって提供される分離されたランタイム | Astroサイトと同じプロセス |
| 機能 | サンドボックスブリッジによって適用される | 同じブリッジによってインプロセスで適用される |
| リソース制限 | ランナーによって適用される — 通常はCPU、サブリクエスト、実行時間、メモリ | なし |
| ネットワークアクセス | ctx.httpのみ、allowedHostsに制限 | ctx.httpのみ、allowedHostsに制限 |
直接的なfetch() / process.env | ランナーによってブロックされる | 可能（プラグインコードはランタイムを共有） |
| 配布方法 | マーケットプレイス上の.tar.gzバンドル | npmパッケージ |
| 管理UI | Block Kit（JSON記述）のルート | Reactコンポーネント、またはBlock Kit |
| 設定UI | Block Kitページ + KV読み取り | admin.settingsSchema（自動フォーム）またはBlock Kit |
| Portable Textレンダリングコンポーネント | 利用不可 | componentsEntryがAstroコンポーネントを提供 |
| ページメタデータの寄与 | page:metadataフック — meta/propertyタグ、許可リストの<link> rels、JSON-LD | page:metadataフック（同じサーフェス） |
| ページフラグメントの注入 | 利用不可 — page:metadata経由のmeta/JSON-LDのみ | page:fragmentsフック — インラインスクリプト、外部スクリプト、生のHTML |
| コンストラクタオプション | なし — 実行時にKVから設定を読み取る | ディスクリプタ上のoptions |
ネイティブ型を選択することで失うもの
ネイティブ型プラグインは、より強力なバージョンのように見え、実際にそうですが、代償は大きいです：
- マーケットプレイスなし。 すべてのサイトがnpmパッケージをインストールし、
astro.config.mjsを編集し、再デプロイする必要があります。 - 分離なし。 プラグインのバグは、ホストプロセスをクラッシュさせたり、CPU予算を使い果たしたりする可能性があります。フック内の未処理の拒否は、周囲のリクエストを道連れにする可能性があります。
- ユーザーへの信頼負担。 ネイティブ型プラグインは、ホストサイトと同じアクセス権を持ちます。エンドユーザーは、機能宣言だけではそれらを監査できません。
プラグインがサンドボックス内でその仕事を実行できる場合、そうすべきです。
ネイティブ型を選択する場合
ネイティブ型を選択する理由は3つあり、すべてホストサイトとのビルド時統合が必要な機能に関するものです：
-
カスタムReact管理ページまたはウィジェット。 サンドボックス型プラグインは、Block Kitで管理UIを記述します — これは、管理者がプラグインの代わりにレンダリングするJSONスキーマです。完全なReact（カスタムフック、サードパーティコンポーネント、複雑な状態）が必要な場合は、ネイティブ型が必要です。
-
公開サイトでPortable TextブロックをレンダリングするためのAstroコンポーネント。 プラグインは
format: "standard"でカスタムブロックタイプを宣言できますが、公開サイトでそれをレンダリングするAstroコンポーネントは、ビルド時にnpmから読み込まれる必要があります。componentsEntryを提供できるのは、ネイティブ型プラグインだけです。 -
公開ページへの生のHTML、スクリプト、またはスタイルシートの注入。
page:fragmentsフックは、訪問者のブラウザにファーストパーティコードを配信します — サンドボックス境界の外側です。これはネイティブ型プラグインに制限されています。サンドボックス型プラグインは、page:metadataフックを通じて公開ページに寄与することができ、これは多くの実際のユースケースをカバーします：metaタグ（name+content） — SEO記述、ロボット指令、Twitterカードpropertyタグ — OpenGraphおよびその他のプロパティベースのメタ- セキュリティロックされたrel許可リストを持つ
linkタグ（canonical、alternate、author、license、nlweb、site.standard.document） —stylesheet、prefetch、および類似のリソース読み込みrelsは意図的に許可されていません - JSON-LDグラフ
「ページ注入」のニーズが構造化データまたはSEOメタデータの場合は、サンドボックス型にとどまり、
page:metadataを使用してください。実際に訪問者のブラウザにJavaScriptまたはHTMLを配信する必要がある場合は、それがネイティブ型を選択するケースです。
不確かな場合は、サンドボックス型を選択してください。後でネイティブ型に移行することは常に可能ですが、逆は困難です。なぜなら、ネイティブ型専用の機能にはサンドボックス型の同等物がないからです。
サンドボックスランナーとプラットフォームサポート
サンドボックス自体はプラガブルです。EmDashはsandboxRunner設定オプションを公開し、ランナーがプラグインコードの分離方法を決定します — プラグイン形式自体にはCloudflare固有のものはありません。
現在ほとんどのサイトが使用しているランナーは、@emdash-cms/cloudflareのsandbox()で、Cloudflare WorkersのDynamic Worker Loaderを使用します。Worker Loaderは、プラグインIDごとにV8分離をキャッシュするため、分離のコールドスタートコストは一度だけ支払われます。ランナーは各呼び出しで新しいワーカースタブとブリッジバインディングを構築します。これは、スタブとバインディングが呼び出しリクエストのI/Oコンテキストに紐付けられているためです。他のプラットフォーム（workerd経由のNode.jsおよび潜在的にDeno）用のランナーは開発中です。
ランナーが設定されていない場合、または設定されたランナーが現在のプラットフォームで利用できないと報告した場合、sandboxed: []の下にリストされているプラグインは、デバッグレベルのログで起動時にスキップされます。
サンドボックスランナーなしのプラットフォームで標準形式プラグインを実行したい場合は、sandboxed: []からplugins: []配列に移動してください — インプロセスで実行されます。機能宣言は依然として尊重されます（同じPluginContextファクトリがctx.content、ctx.httpなどを制限します）が、分離境界はなく、リソース制限もなく、バグのあるまたは悪意のあるプラグインはfetch()を直接呼び出したり、環境変数を読み取ったり、イベントループをブロックしたりできます。サンドボックスランナーがアクティブでない場合は、信頼の目的で各プラグインをネイティブ型プラグインとして扱ってください。