作りたい機能に合うプラグイン方式を選ぶ
プラグインの2つの方式を比較し、追加したい機能と設置先に合う方を選びます。管理画面で入れるものとnpmで入れるものの違いも説明します。
目次
まず、追加したいことを一文にする
プラグインは、EmDashへ機能を追加するプログラムです。「記事を保存したら記録を残す」「外部サービスと連携する」「編集画面に独自の入力部品を追加する」などを担当します。
この章は、自分で追加機能を開発したくなった人向けです。先にファイル編集と記事を読み出すページを試し、コードを保存して結果を確認する流れに慣れておくと進めやすくなります。
方式は、原則としてサンドボックス方式から検討します。独自のReact画面など、その方式では扱えない機能が必要ならネイティブ方式を選びます。まず追加したい処理を一文にし、以下の違いと照らし合わせましょう。
2つの方式の違い
サンドボックスは、サイト本体から分離した環境でプログラムを動かす仕組みです。許可された窓口を通して記事や設定を扱います。ネイティブは、サイト本体と同じ実行環境で動く方式です。
| 比べること | サンドボックス | ネイティブ |
|---|---|---|
| 主な定義 | manifestとsrc/plugin.ts | descriptorとdefinePlugin() |
| 導入 | レジストリから管理画面で導入可能 | npmパッケージを設置し設定を変更 |
| 本番への反映 | 対応する実行環境が必要 | 通常はサイトの再ビルド・再配置が必要 |
| 管理画面の拡張 | Block Kitなどホスト提供の仕組み | Reactの独自画面も作れる |
| Astroの描画部品を同梱 | できない | できる |
| サイトからの分離 | runnerによる分離あり | 分離なし |
manifestは「このプラグインは何者で、何にアクセスするか」の定義です。descriptorは、サイトがプラグインを読み込むための情報です。どちらも、実際の処理を書くコードとは役割を分けます。
原則はサンドボックスから考える
公式の選択ガイド(別タブで開く)は、ネイティブ固有の機能が必要でなければサンドボックスを選ぶ方針です。
保存時の処理、専用データの保存、APIの追加、Block Kitによる管理画面などは、サンドボックスで扱えます。Block Kitは「見出し」「入力欄」「ボタン」などの構成をデータとして返し、EmDashが画面にする仕組みです。
検索向けのメタ情報や構造化データを追加したい場合も、page:metadataで対応できる範囲があります。「ページへ何か足すから、必ずネイティブ」とは限りません。
ネイティブが必要になる例
独自のReact画面を管理画面に組み込む、Portable Textの独自部品とAstroの表示部品を同梱する、読者向けページへ独自のHTMLやスクリプトを挿入する、といった場合に検討します。
ネイティブの権限宣言は、EmDashがプラグインに渡すctxという操作窓口で、使える機能を制限します。ただし、プラグインはサイト本体と同じ環境で動きます。同じ実行環境にある設定や処理へ影響できるため、導入前に提供元とコードを確認する必要があります。
サンドボックスには実行係が必要
分離した環境を起動する部品をrunnerと呼びます。プラグインを登録するだけでは、このrunnerは用意されません。
Node.js用サイトでは@emdash-cms/sandbox-workerdとworkerd、Cloudflareでは対応するWorker Loaderの設定などが必要です。Cloudflareのサンドボックス利用にはWorkers Paidプランが必要という条件もあるため、公開構成と合わせて選びます。料金そのものは、契約時点のCloudflare公式案内を確認してください。
runnerがない場合、sandboxedに登録したプラグインは読み込まれません。分離を無効化すると、プラグインがサイト本体へ影響できる範囲も変わります。動かない場合は、まずrunnerの準備を確認してください。
次に進むガイドを選ぶ
サンドボックスの基本はサンドボックスプラグインを作るで扱います。ネイティブが必要ならネイティブプラグインを作るへ進んでください。
どちらも、最初は記事保存のログという小さな機能から始めます。その後でフック、設定と保存、確認と配布を追加します。拡張機能が不要なサイトでは、プラグイン開発をせずに記事やテーマの制作を進めて構いません。
将来、外すときも考えて選ぶ
その部品を使った記事が、プラグインを外した後も読める必要があるかを決めます。表示を担うネイティブプラグインなら、代わりの表示コードや内容の変換が必要になる場合があります。
保存データの残し方、他の部品への依存、停止中に失われる操作を、導入・停止・削除の確認で整理してから選びます。