第4部 まとめ
第13章 ベストプラクティス集
10 の原則と場面別の手引きとして、全体をまとめ直す。
読了の目安 約 11 分 ・ EmDash 1.3.1 / Astro 7 系(確認日 2026-10-29)
この章は、第1〜12章の内容を、実際に判断・作業するときに引ける形に再構成したものです。新しい事実を加えるのではなく、各章で根拠を示した内容を「原則」「場面別の手引き」「避けたいこと」にまとめ直しています。根拠は、括弧内の章・節で確認できます。
注意: この章の記述には、公式ドキュメントに書かれた推奨と、筆者の判断による推奨が混ざっています。区別が必要なものには、[公式]、[筆者の推奨] のラベルを付けました。ラベルのないものは、各章の本文で根拠を確認してください。
この章で学ぶこと
- EmDash を使うときの 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 のレイアウトとコンポーネントは、ページ単位で分離します。ページ単位で分離すると、影響範囲を追いやすくなります。[筆者の推奨]
移行するとき
- 棚卸しを先に行う(第11章 §2)。
- インポート機能の対応範囲と制限を確認し、何がそのまま移り、何が手作業かを表にする(第11章 §3)。
- メディアは別の手順で移行し、保存先(R2 など)を決める(第11章 §4)。
- URL を決め、リダイレクトを管理する(第11章 §5)。
- プラグインの機能は、移植せずに済むか先に考える(第11章 §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章 |
練習課題
- ローカルに新しい EmDash サイトを作り、管理画面にログインして記事を1件公開する(第1章)。
- シードファイルを書き、
emdash seed --validateで検証して、コレクションを1つ作る(第6章)。 - 記事を予約公開に設定し、状態がどう変わるかを確認する(第5章)。
emdash contentコマンドで、記事の作成と削除(ゴミ箱)を試す(第9章)。- 簡単なプラグインを1つ作り、フックで動作を確認する(第8章)。
- チェックリスト(第10章、第12章)を使って、自分の構成を点検する。
ヒント: 練習は、本番環境ではなくローカルまたは検証用の環境で行ってください。削除系のコマンドや、
--urlが本番を向く操作には、特に注意が必要です(第9章)。
まとめ
- 公式の範囲で組み、範囲の外は自分の責任と明示します。
- 入口を数え、管理面は Access への一本化(または Access なしのパスキー構成)で全体を覆い、最小権限で動かします。
- 変更の前に復旧点を取り、依存を固定し、更新を計画します。
- 公式に書かれていないことは「確認できなかった」と読み、試して確かめます。
- EmDash は 1.x の若い製品です。重要な用途では、追加の検証を計画します。
理解度チェック
- 管理画面を Cloudflare Access で守るとき、どのパスに適用しますか。その理由も説明してください。
- 「公式に書かれていない」ことを、どのように読むべきですか。
- DB の変更を伴う作業の前に、何をしますか。SQLite の場合の注意点も挙げてください。
- 移行の検証で、自動化しておきたい作業を二つ挙げてください。
- 自分のサイトで、「入口を数える」とは具体的に何をすることですか。
答え
/_emdash/*全体に適用します。/_emdash/admin/*だけを守ると、REST API に JWT が要求されなくなります(第7章、第12章)。- 「存在しない」ではなく「確認できなかった」と読みます。自分の環境で実際に試して確かめます(第12章)。
- 復旧点を記録します(D1 のブックマークなど)。SQLite は、WAL を考慮して
.backupを使うか、サーバーを止めてから WAL も含めてコピーします(第10章)。 - リンク切れの巡回と、旧サイトとの差分比較です(第11章 §8)。
- 外から見える動的なエンドポイント(
/_emdash/*、自作の API、自作の配信パス)を一覧にすることです(第12章 §5)。
出典
この章は、第1〜12章の内容を再構成したもので、新しい事実を追加していません。根拠となる公式ドキュメントは、各章の「出典」を参照してください。