既存AstroにEmDashを追加する方法｜パスキーと公開確認

こんにちは。Osukeラーニング、運営者の「osuke」です。

既存のAstroサイトにEmDashを足すと、いまのブログは表示され続けるのか。管理画面で公開した内容はAstroにどう届くのか。公開テンプレートStarfolioを使い、本人限定の環境で導入前後を比較しました。既存3ページは引き続き表示され、検証ページは下書き時の0件から公開後の1件に変わりました。

途中でパスキー登録に失敗したため、実際に開いているHTTPSのアドレスをEmDashの設定に指定し直しました。登録直前、下書き保存後、公開後の実画面とともに、直した箇所を説明します。

CMSを選ぶ段階なら、EmDashの仕組みと向いているサイトの全体像も確認できます。

記事のポイント

• 既存Astroのルートとビルドを導入前後で比較する方法
• パスキーのセキュリティエラー後に修正した設定
• 下書きと公開でAstroの表示が変わる様子
• 本番へ持ち込む前に確認する認証・データ・復元

既存AstroにEmDashを追加する前の準備

先に既存の動作を測り、配信方法とデータの保存先を確認しました。

Starfolioで固定した検証条件

既存のAstroサイトにCMSを足すとき、最初に気になるのは、今あるページを保ったまま管理画面を増やせるかどうかです。今回は、トップページとMDXブログがすでにある公開テンプレートStarfolioのコミット 6d49318 を取得し、本人限定のGitHub Codespacesで作業しました。元のリポジトリへ変更を送らず、既存サイトを別の場所で再現してから比較しています。

導入前後で比較した組み合わせは、Astro 6.4.8、Cloudflareアダプター13.7.0、Wrangler 4.160.0です。ここにEmDashとそのCloudflare向けパッケージの1.4.0を加えました。固定したコミットには依存関係のロックファイルが含まれていなかったため、ソースの版と、今回インストール時に解決された依存関係の版は別々に記録しました。手元で再現する場合も、コミット番号だけで同じ実行条件と判断せず、解決されたバージョンを残しておくと比較がしやすくなります。

11月11日に導入前後のビルドと既存ページを比較し、12日に管理者登録とダミー記事1件の公開を確かめました。見たのは検証用の構成で、既存Workerへ配置した結果や、一般の閲覧者からアクセスした結果は測っていません。記事内の「公開」は、本人限定プレビュー内で、EmDashの記事の状態を公開済みにしたことを指します。

Starfolioの検証に使った固定コミット

既存アダプターとReactを残す

Astroの設定を見ると、StarfolioにはすでにCloudflareアダプターとReactが登録され、サーバー出力も指定されていました。この構成で足したのはEmDashのインテグレーションと保存先の指定です。EmDash公式の既存プロジェクト向け手順はNode.jsの構成例から始まるので、手順中に出てくるアダプターをそのまま追加すると、既存の配信方式まで変えることになります。先に今使っているアダプターを把握すると、必要な差分を小さくできます。

Reactは管理画面で使われますが、今回はすでに設定済みだったため登録を重ねませんでした。既存のMDXやサイトマップの設定もそのまま使用し、CMSの記事を読み出す設定を src/live.config.ts に追加しました。ファイルベースのコレクションとCMSのコレクションを分けておくと、既存の記事群を残しながら、新しい経路を少量のデータで確認できます。

確認する順番は、既存の設定を読む、今のままでビルドする、CMSの追加箇所を記録する、変更後に同じ条件でビルドする、です。今回も導入後のビルドが通ることを確認しました。別のAstroプロジェクトで試すときは、その環境で指定済みの出力方式や実行条件を確認してから、該当する配信先の公式手順を選びます。

EmDash公式の既存Astroプロジェクトへの導入手順

既存ルートとCMS用ルートを照合する

今回、トップ、ブログ一覧、既存のMDX記事1本を、導入の前後でそれぞれ確認しました。3ページともHTTP 200を返し、導入後は既存MDX記事の本文もブラウザーで読めました。一方、EmDash管理画面の入口は導入前に404、導入後に初回セットアップへリダイレクトしました。既存ページと新しい入口を別々に記録すると、どの変更でどの経路が増えたかを追えます。

CMSの公開済み記事を表示するページには、既存ブログと重複しない検証用パスを選びました。管理画面の入口が出た時点では、元からある /blog がCMSの記事を読むようにはなっていません。既存ページへCMSをつなぎたい場合は、そのページでどのデータをどの条件で読むのかを別途決める必要があります。確認を始めるときは、専用のパスで一件だけ表示できるところまで進めると、切り分けが楽です。

200はURLに応答があることを示します。たとえば独自のエラーページが200を返す場合もあるので、確認票には、ステータスと一緒に見出しや本文の目印を書きます。今回は既存記事と検証用記事の本文まで目視し、二つの出力を取り違えないようにしました。

模擬D1・R2で保存先を確かめる

Cloudflare向けの構成では、今回のEmDashにデータベース用のD1とメディア用のR2を渡しました。実際の検証ではCodespace内の模擬環境へ接続し、D1に問い合わせを行い、R2ではテストデータを一度書き込み、同じ内容を読み戻してから削除しました。検証ページで両方がPASSと表示され、Astroアプリから二つの保存先に到達できることを確かめました。

この結果を本番に持ち込むときは、アプリが参照するバインディング名と、配信先で割り当てる実リソースを照合します。たとえば、アプリで DB を参照しているなら、検証と本番でどのデータベースに結び付くかを別々に確認します。メディアも同様で、書き込み先のバケットが想定した環境のものかどうかは、構成を分けて点検する項目です。

今回の模擬R2の成功が示すのは、アプリからテストデータを往復できたことです。管理画面から画像を投稿して配信する操作や、本番環境での課金、バックアップからの復元は今回の実測に含めていません。公開記事の表示を確かめるために、既存のWorkerやクラウド上の実データに触れる必要はありませんでした。

EmDash公式のCloudflare構成とバインディング

パスキーのセキュリティエラーとsiteUrl

管理者登録では、非公開プレビューのHTTPSページをChromeで開いていましたが、利用者の操作時に「セキュリティ上の問題が発生しました。セキュアな接続でアクセスしていることを確認してください。」と表示されました。掲載した画像はボタンを押す直前の画面です。エラー文は登録を行った本人から受け取った報告に基づいています。

試した修正は、astro.config.mjs の emdash({…}) 内に siteUrl を加え、ブラウザーが実際に開いている本人限定HTTPSのオリジンを指定することです。オリジンは https とホスト名、必要な場合はポートまでです。管理画面のパスやクエリは含めません。変更を反映してセットアップを開き直し、同じ検証用のダミー情報で本人がパスキーを作成すると、管理画面まで進めました。

公式資料では、中継サーバーの背後でアプリが内部アドレスを参照すると、パスキーに必要な登録先の判定へ影響しうると説明しています。今回の成功は siteUrl の明示後に確認したものです。エラー発生時にブラウザーへ渡された内部の登録先IDまでは記録していません。同じ文言でも、まずブラウザーで開いたオリジンとアプリ設定を照合し、原因は環境ごとに確認してください。

emdash({
  siteUrl: "https://preview.example.com",
  // 既存の database、storage などの設定を残す
})

preview.example.com は説明用です。実際には、本人がブラウザーで開くHTTPSのオリジンに置き換えます。

EmDash公式のsiteUrlとリバースプロキシの説明

EmDashの公開記事をAstroに表示する

同じページを公開前後で比較し、件数と原稿の中身を確認しました。

下書き保存でAstroに0件と表示された理由

管理画面のPostsから新しい記事を作り、ダミーのタイトルと本文を入力して保存しました。エディターには入力した原稿が残り、「今すぐ公開」を選べる状態になりました。この段階で別タブのAstro検証ページを開くと、公開済み件数は0件で、先ほど保存したタイトルと本文は表示されませんでした。

保存が通ったのにページが空だと、DB接続が壊れているようにも見えます。今回は同じ検証ページで、公開済みの投稿だけを読む設定にしていました。そのため、最初の下書きが表示されないこと自体が確認したかった結果です。画面を見比べるときは、管理画面に原稿があるか、公開日時や公開ボタンはどう表示されるか、閲覧用ページが同じ環境を向いているかを順に確認できます。

掲載する画面は、公開前後で同じ検証ページです。閲覧ページの件数と本文を見比べられるように、記事の中には、架空の原稿だけを載せています。普段の運用で保存の確認をするときも、管理画面で編集できる状態と、公開済みの一覧に出る状態をそれぞれ一度見ておくと、誤公開や確認漏れを見つけやすくなります。

保存した内容を再確認する際は、管理画面のプレビューと通常の閲覧ページを別のタブにしておくと、どちらの状態を見たかが分かります。

今すぐ公開するとタイトルと本文が表示された

保存後に「今すぐ公開」を選び、確認画面でもう一度公開を確定しました。管理画面には非公開へ戻す操作が現れ、同じAstroページを再読み込みすると件数が0から1に変わりました。入力したタイトルと英語のダミー本文も画面に出たため、管理画面での公開状態と、Astroが実際に読み取った内容の両方を確認できました。

このとき、公開ボタンを押したあとにAstroのビルドやWorkerへの再配置は行っていません。今回の確認ページはサーバーでその都度CMSの公開済みデータを読み、表示を組み立てます。静的生成やキャッシュが入る別構成では、いつ新しい内容を読み直すかを個別に確認してください。運用の合格条件は、管理画面の操作が成功したことに加え、閲覧者が見る経路で新しい情報を取得できることです。

テストでは一件だけ作り、タイトルと本文に他の投稿と見分けやすい文字列を使いました。複数の記事があるサイトでも、独自の見出しや短い合言葉を決めておけば、一覧に出ている記事が本当に今回のものかを判定できます。今回は本人限定の検証内に公開状態のダミーを残し、Codespaceを停止しました。

Astroに公開済み記事を表示する最小コード

検証ページでは getEmDashCollection('posts') で投稿を取得し、タイトルをAstroのテンプレートで表示しました。本文はリッチテキストのデータなので、公式の PortableText コンポーネントに渡して表示しました。記事の取得に失敗した場合はエラーを表に出すようにしておくと、記事がまだない状態と、読み込みに失敗した状態を区別できます。

下の例を既存サイトへ試す場合は、EmDashとライブコレクションの設定を済ませ、既存ルートと衝突しない .astro ファイルを置きます。posts は今回の初期セットアップで作られたコレクション名です。独自のコンテンツタイプを使うプロジェクトでは、コレクション名とタイトル・本文のフィールドを実際の定義に合わせます。

この例にはページネーション、公開日時での並べ替え、一覧から詳細へのリンクは入れていません。まず一件の下書きと公開で表示が切り替わるところを見て、用途が決まってから一覧や詳細を設計します。既存のMDX一覧へ組み込みたい場合も、既存の一覧に手を入れる前に、専用ページでCMSの読み取りと本文の描画を確認すると変更範囲を絞れます。

---
import { getEmDashCollection } from 'emdash';
import { PortableText } from 'emdash/ui';

const { entries, error } = await getEmDashCollection('posts');
if (error) throw error;
---
<h1>公開済み記事</h1>
<p>公開済み件数: {entries.length}</p>
{entries.map((post) => (
  <article>
    <h2>{post.data.title}</h2>
    {post.data.content && <PortableText value={post.data.content} />}
  </article>
))}

EmDash公式のコンテンツ取得と本文の描画

表示されないときの切り分け

公開後もページが空のときは、まずEmDashで該当記事が公開済みか、タイトルの違う別記事を開いていないかを確認します。次にAstro側のURLを開き直し、検証したい環境と同じデータを参照しているかを照合します。たとえば管理画面を検証用で操作していても、閲覧用タブが別の環境に向いていれば、公開後も結果は変わりません。

公開済みを読んでいるのに件数が合わない場合は、コレクション名、接続先、絞り込み条件を確認します。件数は合っていて本文だけ空の場合は、本文のフィールド名、データの形式、レンダラーの呼び出しを調べると範囲を狭められます。既存の /blog に記事が出ない場合は、その一覧が今もMDXだけを参照する設計かを確認するのが先です。

パスキーのエラーが出てまだ管理画面へ入れない場合は、公開操作を確認する前に、開いているHTTPSのオリジンと siteUrl の一致を確かめます。既存ページが壊れたときは、CMSの公開状態を触る前に、導入前のビルドとルート一覧を照合します。症状が似ていても、どの段階まで成功したかを記録すれば、次に調べる対象を決められます。

本番へ持ち込む前の確認票

本番へ持ち込む前に、既存ページ、管理者登録、公開記事、データの保存先を一枚の確認票に分けます。今回は既存ルート3件、模擬D1・R2、管理者登録1件、ダミー公開1件を確認しました。公開した原稿のタイトルと本文は本人限定のAstroプレビューに表示されました。ビルドから既存ページまでの結果と、CMSから閲覧ページまでの結果を別の欄に残すと、次の判断がしやすくなります。

既存Astroへ足す案は、今のレイアウトやMDXを維持しながら、編集者が更新する部分を少しずつ増やしたい場合に検討できます。新規サイトなら、CMS向けに整ったスターターを選ぶ方法もあります。どちらの経路を選ぶ場合でも、既存アダプターの有無、最初に検証するルート、認証の登録先、試験データの範囲を先に決めておくと、失敗時に元へ戻す判断ができます。

次に行うなら、既存ページ3つと公開確認用の1ページを自分の構成に合わせて選び、対象・期待する表示・結果を記録してみてください。本番の匿名アクセス、データのバックアップと復元、利用量と課金は今回の公開検証とは別の確認項目です。編集や予約公開の運用が気になる場合は、管理画面での保存・公開・予約を別途観察した記事も参照できます。

EmDashの日本語編集と予約公開を確認した記事