H 原水工房
Docs / tech

Contentful に移行したコンテンツを Astro で表示する

2026-06-26 |
#Contentful #Astro

WordPress から Contentful に移行したコンテンツを Astro で表示するブログのプロジェクトを追加で作成をしました。基本的には WordPress のブログだけであれば、移行をしてしまえばこのプロジェクトで繋がるようになります。

Contentful & Astro Blog

WordPress からのコンテンツ移行に対応した、Astro と Contentful を組み合わせたブログのプロジェクトを作成しました。コードは以下の GitHub のリポジトリで公開をしています。

https://github.com/haramizu/contentful-astro-sample

利用方法

ローカル開発、またはデプロイする際には、プロジェクトのルートディレクトリに .env ファイルを作成し、以下の値を設定してください。この環境変数に関しては、Vercel などでも同じ値を利用することになります。これのテンプレートとして、.env.example のファイルを準備しています。

CONTENTFUL_SPACE_ID=your_space_id
CONTENTFUL_ACCESS_TOKEN=your_delivery_token
CONTENTFUL_PREVIEW_ACCESS_TOKEN=your_preview_token  # 任意 (プレビュー用)
CONTENTFUL_ENVIRONMENT=master                        # デフォルトは master
NEXT_PUBLIC_SITE_URL=http://localhost:4321           # サイトマップ・RSS・メタデータ用

上記の値を Vercel で展開する場合、production には CONTENTFUL_ACCESS_TOKEN を指定して、プレビューでは CONTENTFUL_PREVIEW_ACCESS_TOKEN が見えるように設定すれば、下書きのコンテンツもプレビューをすることが可能となります。

起動とビルドコマンド

プロジェクトを利用するにあたって、以下の手順を実行してください。

npm install

ローカルでの起動方法はいかのコマンドを実行すれば参照が可能となります。

npm run dev

起動したらカルーセルが表示されて、下のようにブログの記事一覧が表示されています。

Astro と Contentful を接続

実際にビルドをして、その環境で起動する手順は以下のようになります。

# プロダクション用ビルド
npm run build

# ビルドした成果物で本番環境サーバーを起動
npm run preview

プロジェクトの構成

主な機能と特徴

このプロジェクトでは、以下のフレームワークを前提として構築しています。Astro と組み合わせて使いやすいフレームワークを選択している形です。

  • Astro (v6) によるアイランドアーキテクチャに基づいた高速な静的生成。
  • React (v19) によるインタラクティブコンポーネントの連携（カルーセル等）。
  • TypeScript による型安全なコンポーネント開発とデータ接続。
  • Tailwind CSS v4.3 をベースとした美しいダークモードデザインとガラスモルフィズム、スムーズなホバーアニメーション。
  • Embla Carousel & Lucide Icons を活用したレスポンシブなスライド式新着フィーチャーエリア。

ディレクトリ構造

プロジェクトのディレクトリ構造は以下のようになっています。

  • src
    • components再利用可能なUIコンポーネント
      • Header.astro共通ヘッダー
      • Footer.astro共通フッター
      • TSFeaturedCarousel.tsxカルーセル (React)
      • Pagination.astroページネーション
      • PostCard.astro記事カード
    • layouts
      • Layout.astroヘッダー・フッター等共通レイアウト
    • lib
      • TScontentful.tsContentful SDK 設定 & API クエリ関数
    • pages
      • [year]
        • [month]
          • [day]
            • [slug].astro記事詳細 (WordPress互換URL)
      • categoriesカテゴリー一覧・カテゴリ別記事
      • tagsタグ一覧・タグ別記事
      • TSrss.xml.tsRSSフィード配信
      • index.astroブログトップページ
    • styles
      • CSSglobals.cssグローバルCSS (Tailwind v4定義)
  • JSONtsconfig.jsonエイリアス（@/*）および型スコープ設定

ブログの構造

WordPress のブログと同じように URL が動くように、以下のような URL のルールとして実装をしています。

  • 元の WordPress 記事のURL構造をそのまま引き継ぐため、/[year]/[month]/[day]/[slug]/ という日付階層つきの動的ルーティングに対応。
  • getStaticPaths によるビルド時事前ビルドによる高速な静的生成。
  • すべての出力 URL の末尾スラッシュを常に強制する設定 (trailingSlash: 'always') をサポート。

またサイトの中で利用しているカテゴリとタグに関しての実装は以下のようになっています。

  • カテゴリー一覧とカテゴリー別記事一覧 (/categories/, /categories/[slug]/)。
  • タグ一覧とタグ別記事一覧 (/tags/, /tags/[slug]/)。
  • クエリとルーティングを組み合わせたページネーションコントロール。

SEO & RSS フィードの自動配信

ブログを立ち上げるとなるとやはり気をつけたいのは SEO と RSS です。これに関してはコンテンツの更新に合わせて、きちんと SEO に必要なフィールドが埋まるように、また RSS に関しても自動的に更新をするように実装してあります。

  • 動的メタタグ（OpenGraph / Twitter Card）の自動設定（Layout.astro）。
  • サイトマップの自動生成 (/sitemap.xml): src/pages/sitemap.xml.ts にて、ホームページ、全投稿、全カテゴリー、全タグの各ページを網羅したXMLサイトマップを出力（lastmod, changefreq, priority の設定付き）。
  • ロボット指示ファイル自動生成 (/robots.txt): src/pages/robots.txt.ts により、ビルド時に動的にロボット制御テキストを生成し、サイトマップとの紐付けも自動化。
  • RSS 2.0 フィード自動生成 (/rss.xml): 最新100件の記事データを配信。

Contentful との連携

このブログを利用するにあたって、Contentful のキーを .env の中に設定をすれば動作するようにしてあります。特に、Delivery API および Preview API の両方に対応させることで、本番環境と下書きプレビュー環境を環境変数で切り替えができるようになっています。

  • Delivery API および Preview API の両方に対応。本番環境と下書きプレビュー環境を環境変数で切り替え可能。
  • Contentful SDK v10+ の EntrySkeletonType に完全適合した型安全なデータ接続。
  • Contentful RichText データの構造を解析し、画像の最適化および絶対リンクを相対リンクへ置換するカスタムレンダリングを実装。
← Contentful 一覧に戻る 技術メモ全体を見る →