<p>テーマ<br>https://expressive-code.com/guides/themes/<br><br>https://expressive-code.com/reference/configuration/#getblocklocale<br>テーマ設定やstyelのオーバーライド</p>

<p>前回<a href="https://841-biboroku.info/entry/astro-v5-content-loader-post/" target="_blank" rel="noopener noreferrer">Astro v5 Content Loader APIで記事詳細を作成</a>したので、今回は詳細ページの本文にシンタックスハイライト適用した手順をまとめました。</p><h2 id="he18d734d0a">現在：Next.js×Prism</h2><p>現在、コードはmicroCMSにコード用のカスタムフィールドを用意し、以下の内容を登録できるようにしています。</p><ul><li>コード</li><li>ファイル名</li><li>言語</li></ul><p>登録したデータはNext.jsにPrismのスタイルとjsを読み込みコンポーネントで表示しています。</p><p>ファイル名の部分は、自作でコードの外に配置しています。</p>

<p><span class="txt-small">▲ 現在のシンタックスハイライトのキャプチャ</span></p><div class="iframely-embed"><div class="iframely-responsive" style="height: 140px; padding-bottom: 0;"><a href="https://841-biboroku.info/entry/syntax-highlighting-prism/" data-iframely-url="https://cdn.iframe.ly/api/iframe?card=small&amp;url=https%3A%2F%2F841-biboroku.info%2Fentry%2Fsyntax-highlighting-prism%2F&amp;key=c271a3ec77ff4aa44d5948170dd74161"></a></div></div><script async src="https://cdn.iframe.ly/embed.js" charset="utf-8"></script><div class="iframely-embed"><div class="iframely-responsive" style="height: 140px; padding-bottom: 0;"><a href="https://841-biboroku.info/entry/react-syntax-highlighter/" data-iframely-url="https://cdn.iframe.ly/api/iframe?card=small&amp;url=https%3A%2F%2F841-biboroku.info%2Fentry%2Freact-syntax-highlighter%2F&amp;key=c271a3ec77ff4aa44d5948170dd74161"></a></div></div><script async src="https://cdn.iframe.ly/embed.js" charset="utf-8"></script>

<h2 id="h30edd085e4">💮採用：Expressive Code</h2><p><a href="https://expressive-code.com/" target="_blank" rel="noopener noreferrer nofollow">https://expressive-code.com/</a></p><p>AstroにはPrismの組み込みサポートもありますが、PrismとExpressive Codeのインテグレーションの両方を試してファイル名の表示やコピー機能も付いているExpressive Codeを採用することにしました。</p><p>ファイル名表示やコピーボタンが標準機能で揃うのが一番の決め手でした。自作していた手間がなくなり簡単に設定できて嬉しいポイントです！</p><h2 id="hfc8380c925">Expressive CodeとPrismの比較</h2><table><tbody><tr><th colspan="1" rowspan="1"><p><strong>比較項目</strong></p></th><th colspan="1" rowspan="1"><p><strong>Expressive Code</strong></p></th><th colspan="1" rowspan="1"><p><strong>@astrojs/prism</strong></p></th></tr><tr><td colspan="1" rowspan="1"><p>主な特徴</p></td><td colspan="1" rowspan="1"><p>「全部入り」の高機能パッケージ</p></td><td colspan="1" rowspan="1"><p>「必要最小限」のシンプル構成</p></td></tr><tr><td colspan="1" rowspan="1"><p>ハイライト方式</p></td><td colspan="1" rowspan="1"><p>Shiki（VS Codeと同じエンジン）</p></td><td colspan="1" rowspan="1"><p>Prism.js（正規表現ベース）</p></td></tr><tr><td colspan="1" rowspan="1"><p>ファイル名表示</p></td><td colspan="1" rowspan="1"><p>標準機能（<code>title</code>属性で表示）</p></td><td colspan="1" rowspan="1"><p>不可<strong>・</strong>自作が必要</p></td></tr><tr><td colspan="1" rowspan="1"><p>コピーボタン</p></td><td colspan="1" rowspan="1"><p>標準機能（自動配置）</p></td><td colspan="1" rowspan="1"><p>不可<strong>・</strong>JSで自作が必要</p></td></tr><tr><td colspan="1" rowspan="1"><p>行ハイライト</p></td><td colspan="1" rowspan="1"><p>標準機能（差分表示も可能）</p></td><td colspan="1" rowspan="1"><p>不可<strong>・</strong>CSSで工夫が必要</p></td></tr><tr><td colspan="1" rowspan="1"><p>ビルド速度</p></td><td colspan="1" rowspan="1"><p>やや遅い</p><p></p></td><td colspan="1" rowspan="1"><p>高速<strong>・</strong>処理が軽量</p></td></tr><tr><td colspan="1" rowspan="1"><p>ランタイム速度</p></td><td colspan="1" rowspan="1"><p>差なし（ビルド時に静的処理）</p></td><td colspan="1" rowspan="1"><p>差なし（ビルド時に静的処理）</p></td></tr><tr><td colspan="1" rowspan="1"><p>カスタマイズ</p></td><td colspan="1" rowspan="1"><p>設定ファイルで一括変更</p><p>複雑な要件はプラグイン作成が必要</p></td><td colspan="1" rowspan="1"><p>CSSを直接書いて調整自由</p><p>シンプル・柔軟</p></td></tr></tbody></table>

<h2 id="h8ba9749960">Expressive Code導入の流れ</h2><p>インテグレーション設定とコンポーネントにフィールドの内容を適用するだけなのでとてもシンプルです。</p><h3 id="h7e002a42c1">1. パッケージのインストールとAstroインテグレーション設定</h3>

import astroExpressiveCode from "astro-expressive-code";

export default defineConfig({
  //...略
  integrations: [
    astroExpressiveCode(),
  ],
});

<h3 id="h636fe4e144">2. コンポーネントに組み込み</h3><p>microCMSのカスタムフィールドのデータをコンポーネントに組み込みます。</p>

---
import { Code } from 'astro-expressive-code/components'
---
<Code code={コードフィールド} lang={言語フィールド} title={ファイル名のフィールド} />

<h3 id="hbdf577ce36">3. テーマカラーの設定</h3><p><a href="https://expressive-code.com/guides/themes/" target="_blank" rel="noopener noreferrer nofollow">約60種くらいのテーマカラー</a>が用意されています。</p><p>dark / light それぞれ指定しておくと、自動でOS/ブラウザのモードに合わせて切り替えてくれます。</p><p>テーマの設定はインテグレーション設定にテーマ名を設定します。</p>

import astroExpressiveCode from "astro-expressive-code";

export default defineConfig({
  //...略
  integrations: [
    astroExpressiveCode({
      themes: ["slack-dark", "solarized-light"],  // テーマ名を指定・複数設定可
    }),
  ],
});

<h4 id="h735f6bf696">Expressive Codeのダークテーマとライトテーマ</h4>

<p>サイトにテーマスイッチャーを採用するときには、モードに合わせて切り替わるように実装しようと考えています。</p><h2 id="h932e30a48a">Astro Prism導入の流れ</h2><p><a href="https://docs.astro.build/ja/guides/syntax-highlighting/" target="_blank" rel="noopener noreferrer nofollow">https://docs.astro.build/ja/guides/syntax-highlighting/</a></p><p>ドキュメントに沿って設定します。</p><h3 id="hd2f296e68c">1. パッケージのインストール</h3>

<h3 id="h5c90a87f01">2. スタイルシートの読み込み</h3><p><a href="https://github.com/PrismJS/prism-themes">Prism Themes</a>から好きなスタイルシートをダウンロードしてpublicディレクトリに配置して<code>&lt;link&gt;</code>で読み込みます。</p>

<h3 id="h0c99cd0c38">3. コンポーネントに組み込み</h3><p>Prismにはコードの表示のみのため、ファイル名やコピー機能は自作する必要があります。</p><p>凝ったデザインにしたい・CSSをカスタマイズしたい場合には向いていますが、シンプルに機能を実装したい場合はExpressive Codeの方が圧倒的に手軽です。</p>

---
import { Prism } from '@astrojs/prism'
---
<Prism lang={言語フィールド} code={コードフィールド} />

<h3 id="h72429e59d8">PrismのVSCodeテーマカラー</h3>

<h2 id="ha214098e44">まとめ</h2><p>とにかく簡単！ファイル名・コピーボタン・テーマ切り替えがこれ一つで適用されるのが良い👍</p><p>Expressive Codeは設定がシンプルな割に機能が充実していて、導入してよかったです。</p><p></p><p>📝参考</p><ul><li>Expressive Code公式<ul><li><a href="https://expressive-code.com/guides/themes/" target="_blank" rel="noopener noreferrer nofollow">Themes | Expressive Code</a></li><li><a href="https://expressive-code.com/reference/configuration/#getblocklocale" target="_blank" rel="noopener noreferrer nofollow">Configuring Expressive Code | Expressive Code</a></li></ul></li><li>Astro公式<ul><li><a href="https://docs.astro.build/ja/guides/syntax-highlighting/" target="_blank" rel="noopener noreferrer nofollow">シンタックスハイライト | Docs</a></li></ul></li></ul>

Expressive Code導入・Astroでシンタックスハイライトを強化する

<p>microCMS公式のMCP（Model Context Protocol）サーバーを活用し、既存記事の再編集にトライしました。</p><p>以前は新規記事の入稿を試しましたが今回は、メタディスクリプションをAIに生成させ、直接microCMSへ書き込む仕組みを構築した記録です。</p><div class="iframely-embed"><div class="iframely-responsive" style="height: 140px; padding-bottom: 0;"><a href="https://841-biboroku.info/entry/microcms-mcp-server-hands-on/" data-iframely-url="https://cdn.iframe.ly/api/iframe?card=small&amp;url=https%3A%2F%2F841-biboroku.info%2Fentry%2Fmicrocms-mcp-server-hands-on%2F&amp;key=c271a3ec77ff4aa44d5948170dd74161"></a></div></div><script async src="https://cdn.iframe.ly/embed.js" charset="utf-8"></script><h2 id="ha9ea0715ee">試した環境</h2><ul><li>Claude Desktop Claude Sonnet 4.6</li><li>microCMS（Hobbyプラン）</li></ul><h2 id="ha8bc14ce49">なぜディスクリプションを再編集しようと思ったか</h2><p>このブログではNext.js側でデフォルト設定として「タイトル＋固定文」を結合してディスクリプションを動的生成し、microCMSのフィールドでユニーク設定できるようにしています。</p><p>せっかく作ったフィールドも使っていない...</p><h3 id="h0f1dca437b">ふと気になった</h3><p><strong>📝ブログカードの見た目</strong></p><p>記事内でリッチエディタの埋め込み（ブログカード）を使ったとき、タイトルと説明文に同じテキストが並んでしまう。</p><p><strong>🚀MCPの練習</strong></p><p>既存記事の再編集（PATCH）を試すのに、ディスクリプションはちょうどよかった。</p>

<p><span class="txt-small">▲ ブログカード表示のイメージ</span></p><h2 id="h6a394f774f">1. microCMS側の設定</h2><h3 id="had3fd3fc62">1-1. API権限の設定</h3><p>API設定からPATCH権限を有効にします。</p><p>設定しないと読み取りはできても書き込みでエラーになります。</p><h3 id="hb78c7c7f54">1-2. フィールドの確認</h3><p>過去に作成していたメタディスクリプションのフィールドをそのまま利用します。</p><h2 id="he9d930a6a9">2. Claudeでの実行プロセス</h2><p>※事前にmicroCMS公式の「<a href="https://blog.microcms.io/microcms-mcp-server/" target="_blank" rel="noopener noreferrer nofollow">microCMSのMCPサーバーをリリースしました</a>」記事を参考にmicroCMS MCP Serverの設定をしておきます。</p>

<h3 id="h2738dab2dc">2-1. AIへの指示</h3>

microCMSの以下条件の記事の内容を確認し記事ページに設定するメタディスクリプションを考え、要約した内容を該当記事の指定フィールドに入稿・登録してください。

## 対象コンテンツAPI
{対象コンテンツAPIを記載}

## 条件
- ステータスが公開中のみを対象
- 要約する文章は80～100文字

## 要約するためのAPIスキーマ
- フィールドIDが{FIELD_ID}に登録されている本文情報

## 要約したディスクリプションの登録先
- フィールドIDが{FIELD_ID}に登録してください。

## 流れ
- まずは、試しに１つ対応してください。
- 確認したあとに問題なければ残りの要約を依頼します。

<h3 id="h1f8ce835a8">2-2. Claudeの自動稼働と提案</h3><p>指示を受けると、ClaudeはMCP経由でスキーマと公開記事を確認。内容を読み取って以下のような案を出してくれました。</p>

メタディスクリプション案（80〜100文字）：
「Astro v5のContent Layer APIを使った記事詳細ページの実装手順を解説。getStaticPathsやgetCollectionでデータを取得し、Zodの型定義を再利用してシンプルに実装する方法をまとめます。」

<h3 id="h1b5ced284a">2-3. microCMSへの書き込み</h3><p>内容を確認して問題なければ実行！</p><p><code>microcms_patch_content</code>が実行され、管理画面側で正しくテキストが登録されていることが確認できました。</p>

<h2 id="h72b0258126">3. 残り記事の更新</h2><h3 id="hec5c0e2756">あえて「1件ずつ」選んだ理由</h3><p>最初のテストが成功したあと、残りの全記事（約50件）も実行するように指示しました。</p><p>ここでうまくいかず...</p><p><strong>最初は一括処理で失敗</strong></p><p>まとめて処理させようとすると、複雑なスクリプトを組もうとして途中で止まったり、APIの制限でエラーが出たりと、かえって時間がかかってしまいました。</p><p><strong>1件ずつの繰り返しへ変更</strong></p><p>指示を「1件ずつ内容を確認し、生成・書き込みを繰り返して」と変更。</p><p><strong>結果</strong></p><p>Claudeが <code>microcms_patch_content</code> を淡々と繰り返し、途中で止まることもなく約50件の記事が10〜15分ほどで完走。 </p><h2 id="h47069e2352">4. 文章校正</h2><p>確認する前にAIによるセルフ校正チェックを挟みます。</p><h3 id="h38e9ee296d">4-1. 校正ルールの提示</h3><p>いきなり校正チェック～修正を実行せず、どのような基準でチェックすべきかをClaudeに提示させました。</p><h4 id="h56d3a5223d">👉提案された内容</h4><ul><li>ネガティブワード — 「つらい」「失敗」「苦労」「問題」「エラー」「悩み」など、読者に不安や苦労を想起させる表現</li><li>自信のなさを示す表現 — 「〜してみた」「〜試した」など、権威性・信頼性を下げる可能性のある表現（ただしブログの性質上許容範囲もある）</li><li>曖昧・冗長な表現 — 「〜をまとめた備忘録です」の繰り返しによる単調さ</li><li>読者メリットが不明瞭 — 何が得られるか伝わらない説明文</li><li>日本語の不自然さ — 助詞の誤り、文末の不統一、句読点の問題など</li></ul><h3 id="h8656e9c4d2">4-2. 校正後の修正PATCH</h3><p>どこをどのように修正するかを提示してくれます。</p><p>内容を確認し、提示された箇所を再度PATCHで上書き修正してもらいます。</p><p>完成です。</p><h2 id="h2e7eae0659">つまづきポイント</h2><h3 id="h3844e7f9e0">👿PUTとPATCHの使い分け</h3><p>前回、新規記事の入稿を試した際はPUTを使っていました。</p><p>今回もPUT権限でいいだろうと実行したところ、Claude（MCP）側は「部分更新」と判断してPATCHでリクエストを送信していたので権限不足ではじかれてしまいました🫠</p><p>自動でPUTで実行して書き込みはできたのですが、全フィールドのデータを上書きするので本文が空になってしまう危険も。</p><h4 id="h634b0ed1cb">編集ならPATCH一択</h4><p>今回のような部分更新なら安全で低負荷のPATCHが最適です。</p><h3 id="hdc770c9f35">👿一括もいいけど1件ずつの繰り返し</h3><p>最初は全件まとめてやってと指示しましたが、何度か途中で中断するはめに。</p><p>複雑なスクリプトを組もうとして環境依存（pip等）の問題にぶつかっていたとのこと。</p><p>一向に進まないので、1件ずつPATCHを叩くように変更したところ最後まで止まらず実行されました😀</p>

<h4 id="h79ee8e3598">Claudeに何があったのか質問してみた💭</h4><ul><li><strong>環境依存の壁</strong><ul><li>Pythonスクリプトの実行に pip install が必要で、ネットワーク制限などの環境トラブルに弱かった。</li></ul></li><li><strong>不透明な中間工程</strong><ul><li>「テキスト抽出 → 生成 → ファイル保存 → 読み込み → 登録」と工程が多く、どこで失敗したかの切り分けが困難だった。</li></ul></li><li><strong>リトライの負荷</strong><ul><li>処理が途中で止まると、どこまで進んだかの管理ができず、最初からやり直す必要があった。</li></ul></li><li><strong>ツールへの依存</strong><ul><li>「自動化ツールを作る」こと自体が目的化し、本来の「APIを叩いて更新する」というシンプルなゴールを複雑にしていた。</li></ul></li></ul><h3 id="h77c28c7f18">👿あくまでも自動生成</h3><p>生成されたテキストを確認していたところ「設定手順と呪った点をまとめます」と。呪った...！👀</p><p>自分で確認する前にまずはAIで校正チェックと修正をしてから確認するフローに変えました。</p>

<h2 id="hba9913274f">microCMSの履歴はどうなる？</h2><p>MCP経由で編集した場合、管理画面の履歴はどうなるのか確認してみました。</p><h3 id="hdf97d4592e">最終更新</h3><p>通常はアカウント名が出ますが、MCP経由（API）の場合は「API」と記録されます。</p><h3 id="h1345e787e1">過去の編集履歴</h3><p>編集履歴にも更新者が「API」として残っていることを確認できました。</p><p></p>

<p><span class="txt-small">※次に保存されたタイミングで現在のデータが履歴に残るので、MCPで書き換えた直後のログは、次に更新（保存）を行った際に一つ前の履歴として確認できるようになります。</span></p><h3 id="h22583e3de8">ブログカードの見え方</h3><p>これまではタイトルと説明文に同じテキストが並んでいましたが、要約が入ることでブログカードの情報の密度が上がり、パッと見の印象がぐっと良くなりました👍</p>

<h2 id="ha214098e44">まとめ</h2><p>今回はディスクリプションということで、文脈の作り込みよりも要約の自動化に重きを置きましたが、タイトルや本文から要点をまとめてくれて、運用の負担が軽減されました。</p><p>長らく空欄のままだったディスクリプションのフィールドも、ようやく日の目を見ることができてうれしい限りです✨</p><p>今回のように既存記事に対するアクションを実践してみて、記事内容を理解させた上でのタグ付けや、アイキャッチ画像の自動生成なども現実的だと感じました。</p>

microCMS MCP×Claudeで実現。AIによるメタディスクリプション自動生成とPATCH更新の実践ログ

<p>この備忘録ブログを最初に作ったときは<strong>Next.js（Pages Router）</strong>を採用していましたが、このたび心機一転、<strong>Astro v5</strong> へリニューアル中です🎈</p><p>前回の「<a href="https://841-biboroku.info/entry/astro-v5-content-loader-zod/">ブログをAstro v5 Content Loader API・microCMSにリニューアル - Zodの型定義編 -</a>」に続き、今回は記事詳細ページの実装をまとめます。</p><p>Content Layer APIを使うことで、型安全かつ高速なページ生成が実現。</p><div class="iframely-embed"><div class="iframely-responsive" style="height: 140px; padding-bottom: 0;"><a href="https://841-biboroku.info/entry/astro-v5-content-loader-zod/" data-iframely-url="https://cdn.iframe.ly/api/iframe?card=small&amp;url=https%3A%2F%2F841-biboroku.info%2Fentry%2Fastro-v5-content-loader-zod%2F&amp;key=c271a3ec77ff4aa44d5948170dd74161"></a></div></div><script async src="https://cdn.iframe.ly/embed.js" charset="utf-8"></script>

<h2 id="h31f45652bc">動的に記事詳細ページを生成</h2><p>動的パラメータを定義するためファイル名を<code>[path].astro</code>で作成（ファイル名は任意。slugなどでもOK）。</p><h2 id="h423ed66dc2">型定義の準備</h2><p>前回作成した<code>content.config.ts</code>で作成したスキーマを詳細ページでも使い回せるように <code>export</code> しておきます。</p>

export const ArticleSchema = z
  .object({
      // 各フィールドの型
  })
  .merge(microCMSContentIdScheme)
  .merge(microCMSDateScheme);

<h2 id="h96a1a225f0">getCollectionで全記事の展開</h2><h3 id="h68c1283c92">1. 全データの取得</h3><p><code>content.config.ts</code>で設定したローカルキャッシュ（Content Layer）から、<code>getCollection</code>で全記事のデータを配列で取得します。</p><p>すでに取得済みのデータを使うため、再fetchする必要がありません。</p>

export async function getStaticPaths() {
  const articles = await getCollection("articles");
  return articles.map((article) => ({
    params: { path: article.data.フィールド },
    props: { article },
  }));
}

<h3 id="he3feee3415">2. URL（パス）の指定</h3><p><code>params</code>にmicroCMS側で設定した一意の値を登録しているフィールドを使ってURLに使うパラメータを指定します。</p><h3 id="h27caedb639">3. データの受け渡し</h3><p><code>props</code>にgetCollectionで取得した記事データをそのまま渡します。</p><h2 id="hf1631bb17f">Zodの型をそのまま使う</h2><p><code>CollectionEntry</code>を使うことでZodで定義したバリデーション済みの型がそのまま反映されるので、安全で便利です✨</p><p>👉 <a href="https://docs.astro.build/en/reference/modules/astro-content/#collectionentry" target="_blank" rel="noopener noreferrer nofollow">Astro公式のCollectionEntry</a></p>

import { getCollection, type CollectionEntry } from "astro:content";

interface Props {
  article: CollectionEntry<"articles">;
}

<h2 id="h78d3b33432">コンテンツの展開</h2><p>あとは<code>Astro.props</code>で受け取って、各フィールドを展開するだけです。</p><p>定義したフィールドが補完されるので実装がスムーズです。</p>

const { article } = Astro.props;
const { publishedAt, title, 他のフィールド} = article.data;

<h2 id="ha214098e44">まとめ</h2><p>今回は記事詳細ページを中心にまとめました。</p><p>型定義やコンテンツキャッシュを活用してデータを再利用することで、とてもシンプルに出力できました😇</p><p>次回は、記事一覧ページについて書きたいと思います。</p><p></p>

ブログをAstro v5 Content Loader API・microCMSにリニューアル - 記事詳細ページ編 -

<p>今までこの備忘録ブログのOGP画像は、microCMSで使えるimgixのURLパラメータを使って画像に記事タイトルのレイヤーを重ねて色を設定した画像を連携していました。</p><p>OGP画像を確認したところ記事タイトルが長くパラメータが肥大化してしまい、うまく表示されないケースがあったことに最近気づきました😭</p><p>そこでこれを機に前から実装してみたかったCloudflare Workers + R2で画像を生成・保存する仕組みを作ることにしました。画像の生成はCloudinaryを使います。</p><p>imgixを使った画像加工についてまとめた記事は「📝<a href="https://841-biboroku.info/entry/imgix-create-ogp/">microCMS×imgixでOGPを自動生成する</a>」をご覧ください。</p><h2 id="h06e76817df">💡この記事で実現できること</h2><ul><li><strong>OGP自動生成</strong><ul><li>記事URLにアクセスがあった際、microCMSからタイトルやカテゴリ色を動的に取得し、Cloudinaryで画像を合成。</li></ul></li><li><strong>Cloudinaryでの画像加工</strong><ul><li>日本語<code>Noto Sans JP</code>フォントを利用。パラメータの組み合わせで複数レイヤーと効果を使用した加工。</li></ul></li><li><strong>コストパフォーマンスと高速配信</strong><ul><li>一度生成した画像は<strong>Cloudflare R2</strong>にキャッシュ。<br>2回目以降は画像生成をスキップし、R2から即座にレスポンスを返すことでCloudinaryの無料枠を節約。</li></ul></li><li><strong>microCMS連動のキャッシュ自動削除</strong><ul><li>microCMSで記事を更新・削除した際、Webhook（カスタム通知）を飛ばして<strong>R2上の古いキャッシュ画像を自動で削除</strong>。<br>常に最新の情報を反映。</li></ul></li></ul><h3 id="hac02c8f33c">OGP生成・配信のフロー</h3><ol><li>OGP画像URLへアクセス（SNSでのシェアや直接アクセス）</li><li>Cloudflare Workersが起動</li><li>R2キャッシュの確認 <ul><li>キャッシュあり： R2から画像を返して終了（爆速＆低コスト）</li><li>キャッシュなし： 次のステップへ</li></ul></li><li>microCMSから記事情報を取得（タイトル、カテゴリ色、IDなど）</li><li>Cloudinaryで画像を動的生成<ul><li>R2にある素材画像（ベース画像・1px画像）とフォントを組み合わせて合成</li></ul></li><li>生成画像をR2に保存（次回のアクセスのためにキャッシュ）</li><li>画像をレスポンスとして返却</li></ol><h3 id="h1c45e48120">キャッシュ削除のフロー（Webhook）</h3><ul><li>microCMSでの記事更新・削除を検知</li><li>Workersの削除専用エンドポイントを実行</li><li>HMAC署名検証でリクエストの正当性を確認</li><li>R2上の該当キャッシュ画像を削除（これで次回のアクセス時に新デザインで再生成される）</li></ul><h2 id="h40cdd7aa75">まずはCloudinary+Cloudflare R2とCloudflare Imagesの比較</h2>

<p>はじめはCloudflareでまとめようと画像の加工にCloudflare Imagesを使おうと思いました。</p><p>しかしCloudflare Imagesはリサイズや圧縮には優れていますがレイヤーの重ね合わせや、動的なテキスト合成の自由度が低かったため運用の柔軟性とコストを考え、今回はCloudinary＋R2を採用することにしました。</p><table><tbody><tr><th colspan="1" rowspan="1"><p><strong>比較項目</strong></p></th><th colspan="1" rowspan="1"><p><strong>Cloudinary+Cloudflare R2</strong></p></th><th colspan="1" rowspan="1"><p><strong>Cloudflare Images</strong></p></th></tr><tr><td colspan="1" rowspan="1"><p><strong>無料枠</strong></p></td><td colspan="1" rowspan="1"><p><strong>最強。</strong><br>Cloudinary(25クレジット)<br>+R2(10GB)+Workers(10万件リクエスト/日)</p></td><td colspan="1" rowspan="1"><p>月5,000回まで。<br>超えると有料。</p></td></tr><tr><td colspan="1" rowspan="1"><p><strong>加工自由度</strong></p></td><td colspan="1" rowspan="1"><p><strong>非常に高い。</strong><br>文字入れやレイヤー加工が自由自在。</p></td><td colspan="1" rowspan="1"><p>基本的なリサイズ・圧縮がメイン。</p></td></tr><tr><td colspan="1" rowspan="1"><p><strong>構成</strong></p></td><td colspan="1" rowspan="1"><p>複雑（Workersのコード管理が必要）</p></td><td colspan="1" rowspan="1"><p>シンプル（スイッチ一つで完結）</p></td></tr></tbody></table>

<h2 id="h8ab2fbd718">1. Cloudflare R2の準備</h2><p>生成した画像のアップロード先のバケットを作成します。</p><ol><li>Cloudflareダッシュボードの「ストレージとデータベース＞R2オブジェクトストレージ＞概要」を開き「バケットを作成」をクリック。</li><li>名前を入力（例:<code>blog-ogp-images</code>）して作成。</li></ol>

<h2 id="h4cbf3d38e4">2. WorkersとR2の紐付け（バインディング）</h2><h3 id="h308f35ce97">2-1. Workersの作成</h3><ol><li>コンピューティングとAI</li><li>Workers &amp; Pages</li><li>アプリケーションを作成する</li><li>Ｈello Ｗorldを開始する</li><li>Worker nameを入力（例：<code>ogp-generator</code>）</li><li>（一旦）デプロイ</li></ol><p>※後ほどコードを書き換えます。</p><h3 id="h5d4f5a773f">2-2. バインディングの設定</h3><ol><li>作成したWorkersを開く</li><li>バインディングを開く</li><li>バインディングを追加</li><li>R2 バケットを選択しバインディングを追加</li><li>Workersで使うR2バケット名の変数名（例：<code>OGP_R2_BUCKET</code>）を入力し、「1. Cloudflare R2の準備」で作成したバケットを選択。</li><li>デプロイ</li></ol><h3 id="he5eb6531bc">2-3. ランタイムの設定</h3><ol><li>設定＞ランタイム＞互換性フラグ</li><li>nodejs_compatを追加</li></ol>

<h2 id="h07965a6c6a">3. Workersのコードを編集（Cloudinaryとの連携）</h2><p>今回はCloudinaryを画像加工エンジンとして使い、その結果をR2にキャッシュさせる仕組みにしました。</p>

export default {
  async fetch(request, env) {
    // 1. 環境変数のバリデーション
    const validationError = validateEnvironment(env);
    if (validationError) return validationError;

    const SITE_URL = env.SITE_URL;
    const url = new URL(request.url);

    // ---------------------------------------------------------
    // A. Webhookによるキャッシュ削除ロジック
    // ---------------------------------------------------------
    // microCMSなどのWebhook通知を受け取ってR2上の画像を削除します
    if (url.pathname.endsWith("/★delete-cache-endpoint")) {
      let targetId = url.searchParams.get('id'); 

      if (request.method === "POST") {
        const bodyText = await request.text();

        // Webhook署名検証 (Secretが設定されている場合)
        if (env.MICROCMS_WEBHOOK_SECRET) {
          const signature = request.headers.get('X-Microcms-Signature');
          const expected = await createSignature(bodyText, env.MICROCMS_WEBHOOK_SECRET);
          if (signature !== expected) {
            return new Response("Unauthorized", { status: 401 });
          }
        }

        try {
          const body = JSON.parse(bodyText);
          // microCMSのJSON構造からID（slugなど）を抽出
          targetId = body.contents?.new?.publishValue?.★field_name
            || body.contents?.old?.publishValue?.★field_name
            || targetId;
        } catch (e) {
          console.log("JSON parse failed. Using query parameter.");
        }
      }

      if (!targetId) return new Response("ID missing", { status: 400 });

      try {
        const R2_KEY = `${targetId}.png`;
        await env.OGP_R2_BUCKET.delete(R2_KEY);
        return new Response(`Deleted: ${R2_KEY}`, { status: 200 });
      } catch (e) {
        return new Response(`Delete failed: ${e.message}`, { status: 500 });
      }
    }

    // ---------------------------------------------------------
    // B. 画像取得・生成ロジック
    // ---------------------------------------------------------
    const filename = url.pathname.split('/').pop()?.replace('.png', '');

    // 不正なアクセスやルートへのアクセスはブログトップへリダイレクト
    if (!filename || filename === "" || filename === "favicon.ico") {
      return Response.redirect(SITE_URL, 301);
    }

    const R2_KEY = `${filename}.png`;

    // 素材画像（背景や1px画像）はそのままR2から返却する
    if (filename === "★base_image_name" || filename === "★dot_image_name") {
      const material = await env.OGP_R2_BUCKET.get(R2_KEY);
      if (material) {
        return new Response(material.body, { headers: { 'Content-Type': 'image/png' } });
      }
      return new Response('Material Not Found', { status: 404 });
    }

    try {
      // 2. R2キャッシュチェック
      const cached = await env.OGP_R2_BUCKET.get(R2_KEY);
      if (cached) {
        return new Response(cached.body, { headers: { 'Content-Type': 'image/png' } });
      }

      // 3. データソース（microCMS等）から記事情報を取得
      const apiRes = await fetch(
        `https://${env.MICROCMS_SERVICE_ID}.microcms.io/api/v1/★endpoint?filters=★field_name[equals]${filename}`,
        { headers: { 'X-MICROCMS-API-KEY': env.MICROCMS_API_KEY} }
      );
      const data = await apiRes.json();

      if (!data.contents || data.contents.length === 0) {
        return Response.redirect(SITE_URL, 302);
      }

      const { title, category } = data.contents[0];
      const themeColor = (category?.[0]?.imgColor || '3d50f5').replace('#', '');

      // 4. Cloudinary URL構築
      const cloudinaryUrl = buildCloudinaryUrl({
        cloudName: env.CLOUDINARY_NAME,
        title,
        themeColor,
        workerDomain: url.host
      });

      // 5. Cloudinaryから画像を取得
      const imageRes = await fetch(cloudinaryUrl);
      if (!imageRes.ok) throw new Error('Cloudinary Error');

      const imageBuffer = await imageRes.arrayBuffer();

      // 6. 次回のためにR2にキャッシュ保存
      await env.OGP_R2_BUCKET.put(R2_KEY, imageBuffer, {
        httpMetadata: { contentType: 'image/png' },
      });

      return new Response(imageBuffer, { headers: { 'Content-Type': 'image/png' } });

    } catch (e) {
      console.error(e.message);
      return Response.redirect(SITE_URL, 302);
    }
  }
};

/**
 * 署名作成 (HMAC-SHA256)
 */
async function createSignature(body, secret) {
  const encoder = new TextEncoder();
  const key = await crypto.subtle.importKey(
    "raw", encoder.encode(secret),
    { name: "HMAC", hash: "SHA-256" },
    false, ["sign"]
  );
  const signed = await crypto.subtle.sign("HMAC", key, encoder.encode(body));
  return Array.from(new Uint8Array(signed))
    .map(b => b.toString(16).padStart(2, "0"))
    .join("");
}

/**
 * 環境変数のチェック
 */
function validateEnvironment(env) {
  const vars = ['OGP_R2_BUCKET', 'API_SERVICE_ID', 'API_KEY', 'CLOUDINARY_NAME', 'SITE_URL'];
  for (const v of vars) {
    if (!env[v]) return new Response(`Missing env var: ${v}`, { status: 500 });
  }
  return null;
}

/**
 * Cloudinaryの変換URLを生成
 */
function buildCloudinaryUrl({ cloudName, title, themeColor, workerDomain }) {
  const baseImageUrl = `https://${workerDomain}/★base_image_name.png`;
  const BASE_IMAGE_B64 = safeBase64(baseImageUrl);
  const encodedTitle = encodeURIComponent(title).replace(/,/g, '%252C');
  const ONE_PIXEL_URL = `https://${workerDomain}/★dot_image_name.png`;
  
  return [
    // Cloudinaryの画像生成URL
  ].join('/');
}

/*
 * Cloudinary用のURLセーフなBase64エンコード
 */
function safeBase64(str) {
  return Buffer.from(str)      // 文字列をBufferに変換
    .toString('base64')        // Base64文字列へ
    .replace(/\+/g, '-')       // URLセーフ化（+ を -）
    .replace(/\//g, '_')       // URLセーフ化（/ を _）
    .replace(/=+$/, '');       // パディング削除
}

<h2 id="h98b1dc753e">4. microCMSのWebhookでキャッシュを自動削除</h2><p>記事を更新したのにOGPが古いままという事を防ぐため、microCMSのWebhook機能を使って、記事公開・更新時にR2のキャッシュを自動で削除する設定を行います。</p><h3 id="hf5e9d18e75">4-1. microCMS側の設定</h3><ol><li>microCMSの管理画面で「API設定」&gt;「Webhook」&gt; 「追加」をクリック</li><li>「カスタム通知」を選択</li><li>以下の項目を入力<ul><li>Webhookの名前</li><li>URLの入力（Workersの実行エンドポイント）</li><li>通知タイミング（実行したいタイミングにチェック、今回はコンテンツの公開と削除にチェック）</li><li>シークレット（認証用）</li></ul></li></ol>

<h3 id="ha79af6bbb4">4-2. Workersの環境変数を設定</h3><p>Workers側で、先ほど決めた「シークレット」を環境変数<code>MICROCMS_WEBHOOK_SIGNATURE</code>で登録します。</p>

<h2 id="hcd6ce4ca04">😞試行錯誤したポイント</h2><h3 id="h3c1a82dbd7">👿R2バケットが「ない」と怒られる</h3><p>Workersにいくつか環境変数を読み込んでいる箇所があり、R2のバケット名も環境変数<code>env.OGP_R2_BUCKET</code>で設定していたところ、バケット名がない・空だ！とエラーがでて進まない...</p><p>WorkersでR2を扱う際、バケット名は「環境変数」として登録するのではなく、「バインディング」という設定が必要でした。これをしないと<code>env.OGP_R2_BUCKET</code>が空（undefined）になり、エラーで進めなくなります。</p><h3 id="h7743d32f3c">👿Cloudinaryでカスタムフォントが適用されない</h3><p>Cloudinaryで「Noto Sans JP」などのデフォルトで指定ができない日本語フォントを使うには、単にMedia Libraryにアップロードするだけでは不十分でした。</p><p>使用できるようにするには、管理画面の<code>Settings &gt; Upload &gt; Upload presets</code>で設定が必要です。</p>

<p>Delivery Typeを「Authenticated」、Access Controlを「Public」設定したプリセットでアップロードしたアセットを使わないと、Workers内のCloudinary画像生成URLで呼び出すことができません。</p><p>CloudinaryのURL構築で<code> l_text:★YourFontName</code>を使う際、フォント名にはAuthenticatedでアップロードした際の<strong>Public ID</strong>を指定する必要があります。</p>

<p>📝参考</p><ul><li><a href="https://blog.kentarom.com/posts/98c62e79-836b-447b-910f-181615d70758" target="_blank" rel="noopener noreferrer nofollow">Cloudinaryを利用して、OGP画像を動的生成する</a></li><li><a href="https://memory-lovers.blog/entry/2021/09/09/070000" target="_blank" rel="noopener noreferrer nofollow">CloudinaryでOGP画像を設定する</a></li></ul><h3 id="hd2d542302f">👿imgixの多重ブレンドをCloudinaryで再現する</h3><p>imgix（microCMS標準）で作り込んでいたレイヤー加工にも苦戦しました。</p><p>もともと使っていたimgixのクエリは、単に文字を載せるだけでなく、背景色と素材画像を高度に合成していました。</p><h4 id="h7ca08f0168">🖼️imgixの生成URL</h4>

`https://images.microcms-assets.io/assets/.../ファイル名.png?
  w=1200&h=630
  &bg=${color}                // 1. 背景色の指定
  &blend-mode=multiply        // 2. 乗算で背景と合成
  &monochrome=95${color}      // 3. ベース画像を単色化
  &blend64=${base64url(text)} // 4. 文字を乗せる
  &fm=png`

<h4 id="h6794eeeb07">🖼️Cloudinaryの生成URL</h4>

return [
  `https://res.cloudinary.com/${cloudName}/image/fetch`,
  `w_1200,h_630,c_fill,b_rgb:${themeColor},e_colorize:100,q_auto`, // 塗り
  `l_fetch:${BASE_IMAGE_B64},w_1200,h_630,c_fill,e_replace_color:${themeColor}:1:979C9F,fl_layer_apply`,  // ベース画像＋色置き換え
  `co_rgb:${themeColor},l_text:★YourFontName_50_bold:${encodedTitle},w_1000,c_fit,fl_layer_apply,g_west,x_100`,  // タイトル
  `f_png`,
  ONE_PIXEL_URL  // 1px画像
].join('/');

<p>ロゴ色を一番下の塗りとタイトルの色に合わせるため、ベース画像の中のロゴ色を置き換える必要がありました。</p><p>はじめはimgixのときと同じようにグレースケール・乗算プロパティで再現しようと思いましたが、imgixとCloudinaryでは処理が違うようで再現できませんでした。</p><pre><code>e_replace_color:${themeColor}:1:979C9F</code></pre><p>そこで使用している色が<code>#979C9F</code>の単色ということもあり、しきい値を1に設定して<code>${themeColor}</code>に置き換えることに成功しました🌟</p><h4 id="h80e76f8c9e">画像の圧縮</h4><p>はじめは圧縮設定をしていませんでしたが<code>q_auto</code>を設定することで、画像サイズが22KB→9.59KBまで圧縮されました。</p>

<h3 id="h8ed8fbce7d">👿キャッシュ削除が動かない？</h3><p>カスタムドメイン経由のWebhookだと削除が動かない現象がありました。</p><p>おそらくCloudflareのWAFなどがmicroCMSからのリクエストをブロックしていた可能性があります。Workersの初期ドメイン（*.workers.dev）を通知先にすることで解決しました。</p><h2 id="h49debcb9ef">最後にデバッガーでOGPチェック</h2><p>WorkersのプレビューやOGP画像のURLにアクセスすると問題なく生成されることを確認できました。</p><p>普段使うチェッカーやデバッガーでも確認すると、生成されるものとされないものが...チェッカーツールでは初回生成時の処理時間によるタイムアウトや、Workers内でのリダイレクト処理が影響しているのかもしれません。</p><h3 id="h6bce815a3e">👏自動生成される</h3><ul><li>X（旧Twitter）のポスト</li><li>Facebookシェアデバッガー</li><li>microCMSのリッチエディタ内の埋め込み</li></ul><div class="iframely-embed"><div class="iframely-responsive" style="height: 140px; padding-bottom: 0;"><a href="https://841-biboroku.info/entry/workers-r2-cloudinary-ogp-automation/" data-iframely-url="https://cdn.iframe.ly/api/iframe?card=small&amp;url=https%3A%2F%2F841-biboroku.info%2Fentry%2Fworkers-r2-cloudinary-ogp-automation%2F&amp;key=c271a3ec77ff4aa44d5948170dd74161"></a></div></div><script async src="https://cdn.iframe.ly/embed.js" charset="utf-8"></script><p><strong>自動生成されない</strong></p><ul><li>OGP画像確認｜ラッコツールズ</li><li>Chrome拡張ツール：Alt &amp; Meta Viewer</li></ul><h2 id="ha214098e44">まとめ</h2><p>設定の罠にハマり、何度もURLを書き換えた苦労はありましたが、その分、既存のツールでは届かない「かゆいところに手が届く」自分専用の機能を作ることができました。</p><p>OGPのURLを短縮しつつ、Cloudflare R2やCloudinaryといった初めて使用するサービスを組み合わせることができ良い経験となりました🙌</p>

microCMSのimgixで自動生成していたOGP画像をCloudflare WorkersとR2×Cloudinaryに変えてみた

<p>microCMSの公式ブログの「AstroとmicroCMSでブログサイトを作ってみよう（Astro 5以降のコンテンツローダー対応版）」を参考にAstro v5でこの備忘録ブログをりにゅアール中。<br><a href="https://blog.microcms.io/astro5-microcms-introduction" target="_blank" rel="noopener noreferrer">https://blog.microcms.io/astro5-microcms-introduction</a><br>ほぼ記事のまま自身のmicroCMSのAPI設定に置き換えるだけ。<br>今回の記事では型定義とcollectionで記事取得まで　何回かにわけて記事を書こうと思います。</p><h2 id="hc9a34d5296">型定義</h2><h3 id="h90b609610a">microCMSの日付・画像の型定義</h3><p>まだ試せてないですが下書き記事を取得するときのために.nullableI()をつけています。（検証したら内容を更新します）</p><pre><code>// 共通のフィールド
const microCMSDateFields = {
  createdAt: z.string().datetime(),
  updatedAt: z.string().datetime(),
  publishedAt: z.string().datetime().nullable(),
  revisedAt: z.string().datetime().nullable(),
};</code></pre><p>microCMSの画像データの形をZodで定義して、satisfies で条件を満たしているかチェック</p><pre><code>
// microCMS画像フィールドのスキーマ
const MicroCMSImageSchema = z.object({
  url: z.string().url(),
  width: z.number(),
  height: z.number(),
  alt: z.string().optional().default(""),
}) satisfies z.ZodType&lt;Partial&lt;MicroCMSImage&gt; &amp; { alt?: string }&gt;;</code></pre><h2 id="h3f6cd11dc1">よく使うzodの型指定</h2><p>途中ですがここでよく使うzodをおさらい<br><strong>データの内容</strong><br><strong>Zodの書き方 (z.)</strong><br><strong>TypeScriptでの型</strong><br><strong>数値</strong><br><code>z.number()</code><br><code>number</code><br><strong>整数（小数不可）</strong><br><code>z.number().int()</code><br><code>number</code><br><strong>文字列</strong><br><code>z.string()</code><br><code>string</code><br><strong>真偽値</strong><br><code>z.boolean()</code><br><code>boolean</code><br><strong>日付</strong><br><code>z.date()</code><br><code>Date</code><br><strong>配列</strong><br><code>z.array(z.string())</code><br><code>string[]</code><br><strong>どれか一つ（列挙型）</strong><br><code>z.enum(["red", "blue"])</code><br><code>"red" | "blue"</code><br><strong>未定義を許容</strong><br><code>.optional()</code><br><code>?</code> (optional)<br><strong>nullを許容</strong><br><code>.nullable()</code><br><code>| null</code><br></p><h2 id="hcb70fed5cb">カスタムフィールドの型を定義</h2><p>microCMSのフィールドの種類・戻り値に合わせて定義する</p><h3 id="h20d64b30e9">カスタムフィールドID（fieldId）</h3><p>stirng()でもエラーは出ませんが、literalで指定しました。</p><pre><code>const MetadataSchema = z.object({
  fieldId: z.literal("metadata"),
  title: z.string().optional(),
  description: z.string().optional(),
});</code></pre><h2 id="hbef1934a4f">種類：セレクトフィールド</h2><p>複数選択がONでもOFFでも戻り値が配列のためarray()とします。<br>enumで選択肢を指定します。</p><pre><code>const HighlightSchema = z.object({
  lang: z
    .array(
      z.enum([
        "javascript",
        "tsx",
        "typescript",
        "jsx",
      ]),
    )
    .optional(),
})</code></pre><h2 id="h3eae2c2e54">種類：複数画像</h2><p>miroCMS画像用の型定義をそのままarray()に入れます</p><pre><code>const GallerySchema = z.object({
&nbsp; images: z.array(MicroCMSImageSchema).optional(),
})</code></pre><h2 id="h27ff54e42f">コンテンツAPIのAPIスキーマの型定義</h2><p>すでに作成したカスタムフィールドの型と組みあわせてAPIスキーマの型定義をします。</p><h3 id="h91b5cd60c9">カテゴリー用</h3><p>共通の日付はmicroCMSDateFieldsをスプレっと構文で展開</p><pre><code>// 各コレクションのスキーマ定義
const CategorySchema = z.object({
  title: z.string(),
  slug: z.string(),
  ...microCMSDateFields,
});</code></pre><h3 id="hc678767a27">記事用</h3><p>種類：複数コンテンツ参照<br>先に定義したカテゴリー用のCategorySchemaを使います。<br>複数参照するのでarray()</p><h4 id="h461bf6ac09">種類：繰り返し</h4><p>どれか1つの形＝カスタムフィールドに当てはまればOKなのでunion()に使えるカスタムフィールドを配列で代入。<br>繰り返しなのでarray()でwrap.<br>必須にしているのでnonempty()を指定しています<br>種類：カスタム<br>単一のカスタムフィールドです。<br>任意のフィールドだけで構成されてますが、未登録の場合でもfieldIdのみ帰ってくるので.optional()をつけずMetadataSchemaのみを指定してます。</p><pre><code>const ArticlesSchema = z.object({
//略
  category: z.array(CategorySchema),
  section: z
    .array(
      z.union([
        HighlightSchema,
        GallerySchema,
       //他の選択肢（カスタムフィールド）
      ]),
    )
    .nonempty(),
  metadata: MetadataSchema,
  ...microCMSDateFields,
});</code></pre><h2 id="h6ab966b81a">AstroのContent Collectionを定義する</h2><p>microCMSLoaderの中でmicrocms-sdkのgetAllContents()を使って全件取得しているので１回で全部取得できる</p><pre><code>export const collections = {
  articles: defineCollection({
    loader: microCMSLoader("記事用のエンドポイント"),
    schema: articleSchema,
  }),
  categories: defineCollection({
    loader: microCMSLoader("カテゴリ用のエンドポイント"),
    schema: categorySchema,
  }),
};</code></pre><p>次回は記事の出力について書く予定です。</p>

<p>この備忘録ブログを最初に作ったときは<strong>Next.js（Pages Router）</strong>を採用していましたが、このたび心機一転、<strong>Astro v5</strong> へリニューアル中です🎈</p><p>今回は、microCMS公式ブログの「<a href="https://blog.microcms.io/astro5-microcms-introduction" target="_blank" rel="noopener noreferrer nofollow">AstroとmicroCMSでブログサイトを作ってみよう（Astro 5以降のコンテンツローダー対応版）</a>」を参考に進めています。</p><p>基本的には公式記事に沿って進めればOKですが、自身のmicroCMSのAPI設定に合わせてカスタマイズした部分（特にZodでの型定義）を中心に、備忘録としてまとめておきます。</p><p>今回は「型定義」と「Content Layerでの取得設定」までを進めました。</p><h2 id="h6bf967ea81">共通フィールドの型定義</h2><p>microCMSの全コンテンツに共通する日付フィールドやコンテンツIDなどの型を定義します。</p>


// microCMSIDフィールドのスキーマ
export const microCMSContentIdScheme = z.object({
  id: z.string(),
}) satisfies z.ZodType<MicroCMSContentId>;

// microCMS日付フィールドのスキーマ
const microCMSDateScheme = z.object({
  createdAt: z.string().datetime(),
  updatedAt: z.string().datetime(),
  publishedAt: z.string().datetime().optional(),
  revisedAt: z.string().datetime().optional(),
}) satisfies z.ZodType<MicroCMSDate>;

<h3 id="h370ce1d1b3">画像データの型定義</h3>

// microCMS画像フィールドのスキーマ
const MicroCMSImageSchema = z.object({
  url: z.string().url(),
  width: z.number(),
  height: z.number(),
  alt: z.string().optional().default(""),
}) satisfies z.ZodType<Partial<MicroCMSImage> & { alt?: string }>;

<h2 id="h2443cdda5b">【おさらい】よく使うZodの型指定</h2><p>設定中に「これなんだっけ🤔？」となりがちな、Zodの書き方とTypeScript型の対応表です。</p><table><tbody><tr><th colspan="1" rowspan="1"><p><strong>データの内容</strong></p></th><th colspan="1" rowspan="1"><p><strong>Zodの書き方(z.)</strong></p></th><th colspan="1" rowspan="1"><p><strong>TypeScriptでの型</strong></p></th></tr><tr><td colspan="1" rowspan="1"><p>数値</p></td><td colspan="1" rowspan="1"><p><code>number()</code></p></td><td colspan="1" rowspan="1"><p><code>number</code></p></td></tr><tr><td colspan="1" rowspan="1"><p>整数（小数不可）</p></td><td colspan="1" rowspan="1"><p><code>number().int()</code></p></td><td colspan="1" rowspan="1"><p><code>number</code></p></td></tr><tr><td colspan="1" rowspan="1"><p>文字列</p></td><td colspan="1" rowspan="1"><p><code>string()</code></p></td><td colspan="1" rowspan="1"><p><code>string</code></p></td></tr><tr><td colspan="1" rowspan="1"><p>真偽値</p></td><td colspan="1" rowspan="1"><p><code>boolean()</code></p></td><td colspan="1" rowspan="1"><p><code>boolean</code></p></td></tr><tr><td colspan="1" rowspan="1"><p>日付</p></td><td colspan="1" rowspan="1"><p><code>date()</code></p></td><td colspan="1" rowspan="1"><p><code>Date</code></p></td></tr><tr><td colspan="1" rowspan="1"><p>配列</p></td><td colspan="1" rowspan="1"><p><code>array(z.string())</code></p></td><td colspan="1" rowspan="1"><p><code>string[]</code></p></td></tr><tr><td colspan="1" rowspan="1"><p>列挙型</p></td><td colspan="1" rowspan="1"><p><code>enum([&quot;a&quot;, &quot;b&quot;])</code></p></td><td colspan="1" rowspan="1"><p><code>&quot;a&quot; | &quot;b&quot;</code></p></td></tr><tr><td colspan="1" rowspan="1"><p>未定義を許容</p></td><td colspan="1" rowspan="1"><p><code>.optional()</code></p></td><td colspan="1" rowspan="1"><p><code>?</code> (optional)</p></td></tr><tr><td colspan="1" rowspan="1"><p>nullを許容</p></td><td colspan="1" rowspan="1"><p><code>.nullable()</code></p></td><td colspan="1" rowspan="1"><p><code>| null</code></p></td></tr></tbody></table>

<h2 id="hc2318b1834">カスタムフィールドの型を定義する</h2><p>microCMSで作成したカスタムフィールドに合わせて、個別にスキーマを作成します。</p><h3 id="h118510576e">1. カスタムフィールドID（fieldId）</h3><p><code>string()</code> でも動作しますが、より厳密にするために<code>.literal</code>でフィールドIDを指定しています。</p>

const MetadataSchema = z.object({
  fieldId: z.literal("metadata"),
  title: z.string().optional(),
  description: z.string().optional(),
});

<h3 id="hbffea6cdd7">2. セレクトフィールド（複数選択）</h3><p>複数選択がONでもOFFでも、APIからの戻り値は配列（array）になります。</p>

const HighlightSchema = z.object({
  // 略
  lang: z.array(
    z.enum(["javascript", "tsx", "typescript", "jsx"])
  ).optional(),
});

<h3 id="he0a34218a9">3. 繰り返しフィールド</h3><p>「繰り返し」は、定義したカスタムフィールドのいずれかに当てはまれば良いため、<code>z.union</code>を使って定義し、全体を<code>z.array</code>で囲みます。</p>

const sectionSchema = z.array(
  z.union([
    HighlightSchema,
    GallerySchema,
    // 他のカスタムフィールドもここに追加
  ])
).nonempty(); // 必須項目の場合はnonempty()

<h2 id="h1dc61d89ea">コンテンツAPIのスキーマを定義</h2><p>これまでに作った部品を組み合わせて、最終的なコレクションのスキーマを完成させます。</p><h3 id="h91b5cd60c9">カテゴリー用</h3><p>作成したフィールドにmicroCMSの日付・コンテンツIDの型をマージします。</p>

const CategorySchema = z.object({
  title: z.string(),
  slug: z.string(),
})
.merge(microCMSContentIdScheme)
.merge(microCMSDateScheme);

<h3 id="h5655b62634">記事（Articles）用</h3><p>「複数コンテンツ参照」のカテゴリーや、先ほどの「繰り返しフィールド」を組み込みます。</p>

const ArticlesSchema = z.object({
  // 略
  title: z.string(),
  category: z.array(CategorySchema), // 複数参照なのでarray
  section: sectionSchema,
  metadata: MetadataSchema, // 未入力でもfieldIdは返るのでoptionalなし(※1)
})
.merge(microCMSContentIdScheme)
.merge(microCMSDateScheme);

<p>※1…エラーが出る場合は<code>.optional()</code>か<code>.nullable()</code>を追加<br>一部記事で戻り値がnullになっているデータがありました。途中でカスタムフィールドを追加したからなのか、戻り値の仕様が途中で変わったのか定かではありません。<br>一度該当フィールドにデータを入れて公開⇒削除して公開するとnullからオブジェクトに変わりました。</p>

<h2 id="h4c10cd8a06">AstroのContent Collectionを設定する</h2><p>最後に<code>src/content/config.ts</code>で、Astro v5の<code>loader</code>を使って定義します。</p>

export const collections = {
  articles: defineCollection({
    loader: microCMSLoader({
      endpoint: "articles", // 記事用のエンドポイント
    }),
    schema: ArticlesSchema,
  }),
  categories: defineCollection({
    loader: microCMSLoader({
      endpoint: "categories", // カテゴリ用のエンドポイント
    }),
    schema: CategorySchema,
  }),
};

<p>このローダー関数の中で <code>getAllContents()</code> を使って全件取得してくれているので、個別に取得ロジックを書く必要がなく、とても簡単です🎉</p><p><span class="txt-small">※この関数は、冒頭でも紹介した </span><a href="https://blog.microcms.io/astro5-microcms-introduction" target="_blank" rel="noopener noreferrer nofollow"><span class="txt-small">microCMSの参考ブログ記事</span></a><span class="txt-small"> から引用させていただきました。</span></p><h2 id="ha214098e44">まとめ</h2><p>今回は型定義を中心にまとめました。</p><p>Zodでしっかり型を固めておくと、コンポーネント側でデータを使う時に補完が効いて開発がとても楽になりそうです😇</p><p>次回は、これらのデータを使って実際に記事画面を出力する部分について書きたいと思います。</p><p></p><p><strong>📝参考サイト</strong></p><ul><li><a href="https://docs.astro.build/ja/reference/content-loader-reference/" target="_blank" rel="noopener noreferrer nofollow">Astro Content Loader API</a></li><li><a href="https://blog.microcms.io/astro5-microcms-introduction" target="_blank" rel="noopener noreferrer nofollow">AstroとmicroCMSでブログサイトを作ってみよう（Astro 5以降のコンテンツローダー対応版）</a></li><li><a href="https://evoworx.dev/blog/microcms_astro-content-layer/" target="_blank" rel="noopener noreferrer nofollow">Content Layer APIで進化したAstro×microCMSのブログ構築</a></li></ul>