ものしり

第4部 まとめ

第13章 ベストプラクティス集

10 の原則と場面別の手引きとして、全体をまとめ直す。

読了の目安 約 11 分 ・ EmDash 1.3.1 / Astro 7 系(確認日 2026-10-29)

この章は、第1〜12章の内容を、実際に判断・作業するときに引ける形に再構成したものです。新しい事実を加えるのではなく、各章で根拠を示した内容を「原則」「場面別の手引き」「避けたいこと」にまとめ直しています。根拠は、括弧内の章・節で確認できます。

注意: この章の記述には、公式ドキュメントに書かれた推奨と、筆者の判断による推奨が混ざっています。区別が必要なものには、[公式]、[筆者の推奨] のラベルを付けました。ラベルのないものは、各章の本文で根拠を確認してください。

この章で学ぶこと

  • EmDash を使うときの 10 の原則
  • 場面別(導入判断、設計、開発、移行、運用、セキュリティ)の手引き
  • 避けたいパターン
  • この本の学び方(読み進め方と練習課題)

13.1 10の原則

図 13-1 に示すように、10 の原則は「設計の姿勢」「守る」「変更する」「確かめる」の四つの群に整理できます。

図 13-1: 10 の原則の四つの群

1. 公式の範囲で組み、範囲の外は「自分の責任」と明示する

EmDash の公式ドキュメントが想定しているのは、サーバー出力(output: "server")のアプリケーションとして、公開ページと管理画面・APIを同じ場所で動かす構成です(第1章、第10章)。公開側を完全な静的配信にする構成や、管理画面を別ホスト名に分ける構成は、公式ドキュメントに記載がありません(第12章)。これらを採用するなら、自分で検証し、設計の責任を負います。[筆者の推奨]

2. 入口を数える

公開されている動的な入口(/_emdash/*、自作の API、自作の配信パス)を一覧にします。入口を数えられないものは守れません(第12章 §5 の項目 1)。[筆者の推奨]

3. 管理面は、認証方式を一つに決めて入口を全部覆う

Cloudflare にデプロイするときに Cloudflare Access を使うなら、/_emdash/* 全体に適用します。/_emdash/admin/* だけを守ると、REST API が認証なしになります(第7章、第12章)。[公式] 本番では Access が排他的な認証方式になり、パスキーやマジックリンクは併用できません。つまり「二重」ではなく、Access への一本化です(第7章 §7、第12章)。[公式] Access を使わない構成では、パスキーを本番ドメインで登録します(第7章)。[公式]

4. 最小権限で動かす

プラグインは、必要な capability だけを許可し、ネイティブ型のプラグインは一つずつ理由を確認します(第8章、第12章)。API トークンもスコープを最小にし、MCP は不要なら無効にします(第9章、第12章)。[公式/筆者の推奨]

5. シークレットは設定ファイルに置かない

秘密値は、wrangler secret put や環境変数で渡し、設定ファイルや import.meta.env に入れません。EMDASH_ENCRYPTION_KEY は、別の保管先に控えます(第7章、第10章、第12章)。[公式]

6. 変更は、復旧点を取ってから

DB の変更を伴う作業(アップデート、マイグレーション、スキーマ変更)の前に、復旧点を記録します(D1 のブックマークなど)。SQLite のコピーは、WAL を考慮して .backup かサーバー停止後に行います(第10章)。[公式]

7. 依存は固定し、更新は計画する

ロックファイルをコミットし、CI で npm ci を使います。emdash と @emdash-cms/cloudflare は同時に更新し、更新前に upgrade-emdash --dry-run で計画と changelog を確認します(第10章)。[公式/筆者の推奨]

8. 「試して確かめる」を手順に入れる

公式に書かれていないこと(付与されるセキュリティヘッダーの内容、Access 配下で公開機能がどうなるかなど)は、「存在しない」のではなく「確認できなかった」と読みます。自分の環境で実際に試します(第12章)。[筆者の推奨]

9. 検証は、型にして自動化する

移行や更新の後は、同じ検証項目を毎回確認します。リンク切れの巡回と、旧サイトとの差分比較は、手作業に頼らず自動化します(第11章 §8)。[筆者の推奨/一般論]

10. 1.x の若い製品であることを前提にする

EmDash は 1.x で、実績とエコシステムが小さいプロダクトです。重要な用途では、追加の検証を計画し、アップデートの追跡を担当者の仕事にします(第12章)。[筆者の推奨]

13.2 場面別の手引き

導入を判断するとき

問い 判断の材料 参照
EmDash に向いているか 公式の整理した採用判断の目安を読む。WordPress を使い続けるべきケースも書かれている 第2章 §2.9
何が必要か Astro と Cloudflare の基礎知識が必要。運用はアプリケーションの運用に近い 第3章、第4章
移行すべきか 棚卸し(投稿タイプ、プラグイン依存、ショートコード、メディア、URL、フォーム、多言語、SEO、ユーザー)の結果で決める 第11章 §1〜2

設計するとき

  • コレクションとフィールドは、WordPress の投稿タイプとメタから、先にスキーマを設計してから作ります(第2章、第5章)。
  • テーマは、シードファイルで再現できるようにします。emdash seed --validate で検証してから投入します(第6章)。
  • 多言語は、ロケールと翻訳の関連づけ(locale と translationOf)を最初に決めます。Astro 側の i18n の設定(fallback、routing)との対応を確認します(第3章、第5章)。
  • キャッシュは、公開ルートごとに routeRules を書き、/_emdash/ を巻き込まないようにします(第10章)。[公式]

開発するとき

  • プラグインは、まず「サンドボックス型」を検討し、必要なときだけネイティブ型にします(第8章)。
  • フックは、副作用(外部への通知など)を最小にし、失敗しても編集をブロックしない設計にするかを決めます。errorPolicy は、プロセス内実行でのみ有効です(第8章)。
  • Astro のレイアウトとコンポーネントは、ページ単位で分離します。ページ単位で分離すると、影響範囲を追いやすくなります。[筆者の推奨]

移行するとき

  1. 棚卸しを先に行う(第11章 §2)。
  2. インポート機能の対応範囲と制限を確認し、何がそのまま移り、何が手作業かを表にする(第11章 §3)。
  3. メディアは別の手順で移行し、保存先(R2 など)を決める(第11章 §4)。
  4. URL を決め、リダイレクトを管理する(第11章 §5)。
  5. プラグインの機能は、移植せずに済むか先に考える(第11章 §6)。
  6. 検証項目を決め、切り替えとロールバックの手順を用意する(第11章 §8〜9)。

運用するとき

  • 本番デプロイ前、アップデート時のチェックリスト(第10章)を、実際に表として使う。
  • 予約公開を使うなら、Cron Trigger と scheduled ハンドラーがあることを確認します。Node.js では常駐プロセスが必要です(第5章、第10章)。
  • 退職者・外部ユーザーの無効化手順を決めておきます(第7章、第12章)。[公式]

セキュリティを確認するとき

第12章 §5 の 30 項目のチェックリストを、公開前に一通り確認します。特に次の項目は、後回しにしやすいので注意します。

項目 理由
未ログインのブラウザで /_emdash/admin と /_emdash/api/* が認証を要求する 設定の抜けは、実際に試さないと分からない
公開バケットが backups/ を露出していない バックアップは、公開バケットから到達できると漏えいする
sandbox: false を使っていない サンドボックスは、プラグインの影響範囲を限定する仕組み
パスキーを複数端末に登録し、復旧手順を決めた 全部を失っても、別の Admin かメール設定があればマジックリンクで復旧できる。Admin が 1 人でメール未設定のときだけ、DB 操作しか手がない

13.3 避けたいこと

避けたいこと 理由 参照
/_emdash/admin/* だけを Access で守る REST API に JWT が要求されなくなる 第7章、第12章
(Access を使わない構成で)パスキーを、本番と違うホスト名で登録する パスキーは、登録したホスト名でしか使えない 第7章
SQLite の DB ファイルを、WAL を考慮せずにコピーする WAL にしかない変更が失われる 第10章
秘密値を設定ファイルや import.meta.env に書く 漏えいの経路になる 第10章、第12章
routeRules を、サイト全体のキャッチオールにする /_emdash/ まで巻き込む 第10章
公式に無い構成を、公式の推奨のように扱う 想定外の挙動に責任を負えなくなる 第12章
プラグインを、権限を確認せずに入れる 最小権限の原則に反する 第8章
更新を、changelog を読まずに適用する 破壊的変更を見落とす 第10章
移行後の検証をしない リンク切れや見た目の差に気づけない 第11章

13.4 この本の学び方

読み進め方

目的 読む順序
まず全体像を知りたい 第1章 → 第2章 → 第13章
WordPress から移行したい 第1章 → 第2章 → 第11章 → 第12章 → 第10章
安全な構成を知りたい 第7章 → 第12章 → 第4章
サイトを作りたい 第1章 → 第3章 → 第5章 → 第6章
プラグインを作りたい 第8章 → 第9章

練習課題

  1. ローカルに新しい EmDash サイトを作り、管理画面にログインして記事を1件公開する(第1章)。
  2. シードファイルを書き、emdash seed --validate で検証して、コレクションを1つ作る(第6章)。
  3. 記事を予約公開に設定し、状態がどう変わるかを確認する(第5章)。
  4. emdash content コマンドで、記事の作成と削除(ゴミ箱)を試す(第9章)。
  5. 簡単なプラグインを1つ作り、フックで動作を確認する(第8章)。
  6. チェックリスト(第10章、第12章)を使って、自分の構成を点検する。

ヒント: 練習は、本番環境ではなくローカルまたは検証用の環境で行ってください。削除系のコマンドや、--url が本番を向く操作には、特に注意が必要です(第9章)。

まとめ

  • 公式の範囲で組み、範囲の外は自分の責任と明示します。
  • 入口を数え、管理面は Access への一本化(または Access なしのパスキー構成)で全体を覆い、最小権限で動かします。
  • 変更の前に復旧点を取り、依存を固定し、更新を計画します。
  • 公式に書かれていないことは「確認できなかった」と読み、試して確かめます。
  • EmDash は 1.x の若い製品です。重要な用途では、追加の検証を計画します。

理解度チェック

  1. 管理画面を Cloudflare Access で守るとき、どのパスに適用しますか。その理由も説明してください。
  2. 「公式に書かれていない」ことを、どのように読むべきですか。
  3. DB の変更を伴う作業の前に、何をしますか。SQLite の場合の注意点も挙げてください。
  4. 移行の検証で、自動化しておきたい作業を二つ挙げてください。
  5. 自分のサイトで、「入口を数える」とは具体的に何をすることですか。

答え

  1. /_emdash/* 全体に適用します。/_emdash/admin/* だけを守ると、REST API に JWT が要求されなくなります(第7章、第12章)。
  2. 「存在しない」ではなく「確認できなかった」と読みます。自分の環境で実際に試して確かめます(第12章)。
  3. 復旧点を記録します(D1 のブックマークなど)。SQLite は、WAL を考慮して .backup を使うか、サーバーを止めてから WAL も含めてコピーします(第10章)。
  4. リンク切れの巡回と、旧サイトとの差分比較です(第11章 §8)。
  5. 外から見える動的なエンドポイント(/_emdash/*、自作の API、自作の配信パス)を一覧にすることです(第12章 §5)。

出典

この章は、第1〜12章の内容を再構成したもので、新しい事実を追加していません。根拠となる公式ドキュメントは、各章の「出典」を参照してください。