本記事は、WordPressをバックエンド、Next.jsをフロントエンドに据えた「ヘッドレス構成」への移行記録です。
従来のプラグイン依存の構成から脱却し、最新のApp Router環境でパフォーマンスと保守性を再構築しました。技術選定の理由から具体的な実装のポイントまで、簡潔にまとめています。
開発環境 / 技術スタック
- インフラ / デプロイ: Vercel
- フロントエンド: Next.js 16.2.2 (App Router) / React 19.2.4 / TypeScript 5
- スタイリング: Tailwind CSS 4 / CSS Modules
- データ通信: GraphQL 16.13.2
- フォーム / 状態管理: React Hook Form 7.72.1 / Zod 4.3.6
- バックエンド (Headless): WordPress 6.x / WPGraphQL
Next.jsによるHeadless化を採用するメリット
Next.jsとヘッドレスアーキテクチャの組み合わせによる、本プロジェクトでの技術的な意図を解説します。
TailwindとCSS Modulesによるスタイル管理
Tailwind CSSとCSS Modules（module.css）を併用し、コンポーネント単位でスタイルをスコープ化しています。これにより意図しないスタイルの競合を防ぎ、修正や削除時の影響範囲を限定しています。
通信の無駄を省くGraphQLの採用
クライアントが必要なデータのみを要求する仕様により、オーバーフェッチを防いでいます。データ転送量を削減し、ページ読み込み速度の改善を図りました。
エッジ配信とキャッシュの活用
Vercelのエッジネットワークを利用し、コンテンツを配信しています。Next.jsのキャッシュ制御と組み合わせることで、サーバー負荷の軽減とレスポンスの向上を目的としています。
Vercelによる自動デプロイ
GitHubへのプッシュをトリガーとしたビルド・デプロイ環境を構築しました。プレビュー環境の自動生成により、変更内容の確認プロセスを省力化しています。
フォーム実装と状態管理
React Hook Formを利用してクライアントサイドの入力チェックを実装しています。非同期処理を用いることで、画面遷移を伴わないフォーム送信を可能にしました。
ヘッドレス構成による攻撃リスクの軽減
CMSの管理画面とフロントエンドを物理的に分離し、外部から管理画面へのアクセス経路を制限することで、従来のWordPress構成が持つ脆弱性リスクを低下させています。
TypeScriptによる型安全性
静的型チェックを導入し、開発時の型不整合を検知しています。エディタの入力補完を活用し、コードの安定性を図っています。
画像の自動最適化
Next.jsの機能を利用し、デバイスに応じたサイズやフォーマットへ画像を自動変換しています。これにより、Core Web Vitals等のパフォーマンス指標の改善を図りました。
コンポーネント設計による保守性
UIをコンポーネントとして分割・管理し、コードの再利用性を高めました。共通パーツの仕様変更を一箇所で管理できる構成にしています。
なぜGraphQLを選んだのか
これまではREST APIを使用していましたが、データ取得の効率化を目的にGraphQLを採用しました。 RESTでは複数回のエンドポイントへのリクエストが必要なケースでも、GraphQLでは単一のクエリで必要なデータを取得できます。実装にはWordPressプラグイン「WPGraphQL」を使用しました。スキーマ定義やリゾルバーの構築を省略できる利点がある一方、内部のSQL処理が隠蔽されるため、パフォーマンスチューニングの際には内部構造の理解が別途必要になるという課題も確認できました。
SCSSからTailwind CSS / CSS Modulesへ移行
以前制作したテーマのSCSS資産を移行しました。 元のSCSSの設計規則が明確だったため、AIツールを用いたコード変換が比較的スムーズに行えました。基本のスタイリングにはTailwind CSSを使用し、複雑な指定が必要な箇所にはCSS Modules（module.css）を適用してコンポーネントごとにカプセル化する運用としています。
HTMLからReactコンポーネントへの動的変換
WordPressから取得したHTML文字列を、html-react-parserを用いてReactコンポーネントへ変換してレンダリングしています。 特定のHTMLタグ（imgやaなど）をNext.jsの<Image>や<Link>コンポーネントに置換し、フレームワークの最適化機能を適用させています。また、サーバーサイドでnode-html-parserを用いてHTMLを解析し、目次（ToC）の生成等も行っています。
フォームバリデーションと通知基盤
問い合わせフォームにはReact Hook FormとZodを導入し、型安全なバリデーションを実装しました。 ボット対策としてCloudflare Turnstileを組み込み、目視の画像認証なしでバックグラウンド検証を行っています。フォーム送信後のメール通知基盤にはResendのAPIを利用し、配信処理を実装しました。
キャッシュ戦略とWebhookによる即時更新
WordPress側の更新をサイトへ反映させるため、Next.jsのData Cacheとタグベースの再検証（On-demand Revalidation）を実装しました。 fetch時にデータ種別ごとのタグ（articles, works, pages等）を付与し、WordPressで記事が保存された際にWebhook経由でNext.jsのAPIルート（/api/revalidate）へ通知を送ります。これにより、更新された対象データのキャッシュのみを破棄（revalidateTag）する仕組みです。
検索・フィルタリング機能の実装
カテゴリー、タグ、カスタムタクソノミー、フリーワード等による絞り込みを実装しました。 カテゴリーやタグなどの階層構造を持つものは動的ルーティング（サブディレクトリ形式）を使用し、複数条件の絞り込みや検索ワードの保持にはクエリパラメータを使用するなど、要件に応じてルーティング処理を分けています。
既存資産の整理とプラグインの削減
フロントエンドへの移行に伴い、WordPress側の構成を整理しました。 これまでプラグインで処理していた目次生成やテーブル装飾、フォーム機能をフロントエンド側（Reactコンポーネント）へ移管しました。これにより、WordPress本体の稼働プラグイン数を削減し、バックエンドの構成をシンプルにしています。
Infisicalによるシークレット管理（.envの廃止）
ローカルの.envファイルによる環境変数管理を廃止し、シークレット管理ツール「Infisical」を導入しました。 機密情報をリポジトリへプッシュするリスクを防ぐとともに、AIエディタ（Cursor等）がAWS認証情報などを意図せず読み取って学習データに利用してしまう可能性を排除し、環境変数をプロセス実行時に動的に注入する構成としています。
Sentryによるエラー監視とオブザーバビリティ
フロントエンドのエラー検知のため「Sentry」を導入しました。 当サイトの主な動的機能であるフォームの送信エラーなど、表面化しにくい内部エラーが発生した際に即座に通知を受け取れるようにし、監視体制を構築しています。
Sentryを活用したWeb Vitals計測とCLS対応
パフォーマンス計測（Web Vitals）にもSentryを利用し、エラーログとパフォーマンスデータを同一基盤で確認できるようにしました。 RUM（Real User Monitoring）であるためユーザー環境により数値は変動しますが、指標の中でも特にレイアウトシフト（CLS）を抑えることを意識して画像等のコンポーネント設計を行いました。
Claude Designを活用した対話型UI実装
UIの構築において、デザインコンセプトをClaude Designに渡し、対話形式でUI要件を定義しました。 そこからNext.js、TypeScript、Tailwind CSSに準拠した実稼働コードを直接生成させるアプローチを検証しました。デザインから実装までの工程をAIに集約することで、UIコンポーネントを実用レベルで組み込むフローを構築しています。
おわりに
今回のヘッドレス化プロジェクトは、単なるレガシーなWordPressからの脱却にとどまらず、現在のフロントエンドのエコシステムを実践的に導入する検証の場となりました。 Next.jsとGraphQLによる通信の実装から始まり、Infisicalによるシークレット管理、Sentryを用いた監視、Claude Designを通じたAI駆動のUI実装など、各ツールを連携させて本番環境で稼働させたことは、一つの技術的な知見となりました。今後も構築したアーキテクチャをベースに、保守運用を続けていきます。
