WordPress CMS統合ガイド¶

このドキュメントは、Next.js Storefront、Vendure、およびWordPress CMSの統合方法、アーキテクチャ、実装パターンを説明します。

概要¶

このプロジェクトでは、WordPressをHeadless CMSとして使用し、以下のコンテンツを管理します：

ナビゲーションメニュー: ヘッダー・フッターの動的なリンク構造
お知らせ（Announcements）: サイト全体のお知らせ、重要なお知らせの固定表示
キャンペーン（Campaigns）: プロモーションキャンペーン情報
Heroスライド（Hero Slides）: ホームページのヒーローセクション用スライド
店舗設定: ロゴ、コピーライト、コンタクト情報など

アーキテクチャ¶

StorefrontはWordPressへ直接アクセスするのではなく、Vendureの CmsIntegrationPlugin をプロキシとして経由します。これにより、認証情報の秘匿、APIの一元化、およびデータの正規化が可能になります。

┌─────────────────┐
│ WordPress CMS   │
│ (Headless)      │
│                 │
│ - Menu Items    │
│ - Custom Posts  │
│ - ACF Settings  │
└────────┬────────┘
         │ WPGraphQL (Internal)
         │
         ▼
┌─────────────────┐
│ Vendure Server  │
│ (CMS Plugin)    │
│                 │
│ - Data Proxy    │
│ - Normalization │
│ - Resolvers     │
└────────┬────────┘
         │ Shop API (Public)
         │
         ▼
┌─────────────────┐
│ Next.js         │
│ Storefront      │
│                 │
│ - SSR Fetch     │
│ - Components    │
│ - Display       │
└─────────────────┘

1. サイト外枠（枠組み）¶

担当: Storefront (Next.js)
対象: ヘッダー、フッター、グローバルナビゲーション
管理: WordPressの「メニュー」機能（位置: PRIMARY, FOOTER）で管理。Vendureがこれを headerMenu, footerMenu として公開し、StorefrontがReactコンポーネントとして描画します。

2. メインコンテンツ（中身）¶

担当: WordPress (Elementor / Gutenberg)
対象: 固定ページ、お知らせ詳細、キャンペーン詳細
実装: WordPressが生成するHTMLをVendure経由で取得し、Storefrontの ContentProcessor で加工して描画します。

装パターン¶

正規化処理の共通化¶

Wo Press特有のデータ構造をRitsubiドメインのクリーンなデータに変換するため、正規化処理を重層的に行います。

Shared Utilities (@ritsubi/utils): slugify や normalizeCmsUrl といった純粋な変換関数を提供します。バックエンドとフロントエンドの両方で使用されます。
Vendure Plugin (Backend): WPGraphQLの冗長なネスト（nodes { ... } 等）を排除し、フロントエンドが扱いやすいフラットな型へ正規化します。
Storefront (Frontend): Vendureから受け取ったデータを、UIコンポーネントのProps（NavigationItem 等）に最終マッピングします。

GraphQLクライアント¶

Storefrontからのリクエストは apps/storefront/src/lib/cms/wordpress/client.ts の fetchWordPressGraphQL を使用します。この関数は デフォルトで非モック（実データ取得） であり、VendureのShop APIを叩きます。

メニュー同期 (Menus)¶

WordPress側: 「外観」→「メニュー」で作成。位置を「Header」または「Footer」に設定。
Vendure側: CmsIntegrationPlugin が headerMenu, footerMenu クエリを提供。
Storefront側: fetchMenus() で両方のメニューを一括取得し、Header / Footer コンポーネントに反映。

設定¶

環境変数 (Vendure Server)¶

バックエンドがWordPressへアクセスするための設定です。

WORDPRESS_ENDPOINT: WordPressのベースURL（例: http://localhost:8181）
WORDPRESS_GRAPHQL_TOKEN: WPGraphQLの認証が必要な場合のBearerトークン

環境変数 (Storefront)¶

VENDURE_API_URL: Vendure Shop APIのエンドポイント
NEXT_PUBLIC_STOREFRONT_API_MOCKING: enabled に設定するとMSW経由でのモックが有効になりますが、コードレベルでは常にネットワークリクエストが発生します。

開発とテスト¶

テスト戦略¶

バックエンドテスト*: ackages/plugins/src/cms-integration/wordpress/.spec.ts` で、WordPressからの生データが正しく正規化され、GraphQLリゾルバーが機能することを検証します。
フロントエンドテスト: apps/storefront/src/lib/cms/wordpress/*.test.ts で、VendureからのデータがUIコンポーネント向けに正しくマッピングされることを検証します。

モックデータの扱い¶

ソースコード内にハードコードされた大規模なモックデータは廃止されました。開発時にモックが必要な場合は、apps/storefront/src/mocks/cms-handlers.ts (MSW) にデータを定義してください。

トラブルシューティング¶

メニューが反映されない¶

WordPress側でメニューが作成され、正しい「位置」（PRIMARY/FOOTER）に割り当てられているか確認してください。
Vendureサーバーのログを確認し、WordPress APIへのリクエストが成功しているか（200 OK）を確認してください。
GraphQL Playground (/admin-api 等) で query { headerMenu { items { label } } } がデータを返すか直接確認してください。

URLがWordPressのドメインのままになっている¶

@ritsubi/utils の normalizeCmsUrl が適用されているか確認してください。この関数は絶対URLを相対パスに変換します。