本記事は、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のエッジネットワークを活用し、世界中のユーザーへ物理的に近い距離からコンテンツを配信します。高度なキャッシュ制御により、サーバー負荷を抑えつつ、数百ミリ秒単位の応答速度を実現します。
開発サイクルを加速させるVercelの自動デプロイ
GitHubへプッシュするだけでビルドから公開までが完結し、手動作業によるミスや時間ロスを実質ゼロにします。プレビュー環境の自動生成により、変更内容を素早く確認でき、アウトプットの質が高まります。
快適な操作性を提供するモダンなフォーム実装
React Hook Form等を用いた高速な入力チェックにより、ユーザーにストレスを与えないスムーズな操作感を提供します。画面遷移を伴わない非同期処理を組み合わせることで、フォーム離脱率を改善します。
攻撃リスクを最小化するヘッドレス構成
CMSの管理画面とフロントエンドを物理的に分離することで、従来の構成に比べて攻撃の糸口を大幅に減らします。システムの脆弱性を突かれるリスクを構造的に抑え込み、高い安全性を維持した運用が可能です。
実行時エラーを防ぐTypeScriptの型安全性
強力な静的型チェックにより、開発中の些細なミスや実行時エラーをコンパイル段階で未然に防ぎます。エディタの優れた入力補完機能も最大限に活用できるため、開発のスピードを落とさず、堅牢で安定した品質のアプリケーションを構築できます。
表示遅延を防ぐ画像の自動最適化
デバイスに応じた適切なサイズ・形式への変換を自動で行い、画像による速度遅延を根本から解決します。客観的なパフォーマンス指標が改善されることで、検索エンジンの評価とユーザー体験を同時に向上させます。
長期的な保守性を高めるコンポーネント設計
UIを独立した部品として管理することで、コードの重複を排除し、プロジェクト全体での一貫性と保守性を高めます。仕様変更時も一箇所の修正で全体に反映されるため、運用コストを最小化することが可能です。
なぜGraphQLを選んだのか
これまではREST APIを用いた開発がメインでしたが、本プロジェクトではモダンな技術への挑戦としてGraphQLを採用しました。
最大の理由は、データ取得の効率化です。RESTでは必要な情報の数だけクエリを投げる場面でも、GraphQLならたった1本のリクエストで必要なデータを過不足なく取得できます。この「リクエストの集約」がもたらすパフォーマンス上のメリットは、特にモバイル環境でのユーザー体験において大きな武器になると判断しました。
実装にあたっては、WordPressのプラグイン「WPGraphQL」を活用しています。自前でスキーマ定義やリゾルバーを書く手間を大幅に削減でき、瞬時に強力なAPI基盤を用意できる点は非常に合理的でした。一方で、プラグインに頼ることで内部のSQL処理が見えにくくなる「ブラックボックス感」を感じたのも事実です。利便性と引き換えに、内部構造への深い理解が求められる点は、今後の学びにおける大きな収穫となりました。
SCSSからTailwind CSS / CSS Modulesへ移行する
本プロジェクトでは、以前制作したオリジナルテーマのSCSS資産をベースに、モダンなスタイリング環境への刷新を行いました。
特筆すべきは、移行の効率性です。過去に自分自身で構築したSCSSの設計が丁寧になされていたため、AIを活用したスムーズな変換が可能でした。一つひとつの定義が明確だったことで、AIによる解析精度が高まり、大規模な書き換えをすることなく、最小限の工数で最新の定義へと落とし込むことができました。
スタイリングの基本には開発効率に優れたTailwind CSSを採用していますが、複雑な表現や微細な制御が必要な箇所については**CSS Modules（module.css）**へと個別に変換し、コンポーネント単位でカプセル化しています。この適材適所の使い分けにより、コードの可読性を維持しつつ、保守性の高いスタイリング基盤を再構築することができました。
HTMLからReactコンポーネントへの動的変換
WordPressから配信される記事本文は生のHTML形式ですが、本プロジェクトではこれを単に流し込むのではなく、html-react-parserを用いてReactコンポーネントへと動的に変換しています。
この手法を採用した最大の理由は、フロントエンド側での自由なコンポーネント制御です。特定のHTMLタグ（例えば画像タグやリンクなど）を検知し、Next.jsの<Image>コンポーネントや<Link>コンポーネントへ置換することで、ヘッドレス構成でありながらNext.jsの最適化機能を最大限に享受できるよう設計しました。
実装においては、node-html-parserを組み合わせてサーバーサイドで事前にHTML構造を解析し、目次（TOC）の自動生成なども同時に行っています。パース処理を一段挟むことで、セキュリティ（サニタイズ）の担保と、モダンなユーザー体験を支える柔軟なマークアップ制御を両立させることができました。
堅牢なフォームバリデーションと快適なユーザー体験
お問合せフォームには、React Hook Form と Zod を組み合わせた型安全なバリデーション基盤を採用しました。入力の不備をリアルタイムで検知し、ユーザーに即座にフィードバックを返すことで、送信時のストレスを最小限に抑えています。また、バックエンドでの検証ロジックを共有することで、フロント・バック両面での整合性を担保しています。
セキュリティと利便性の両立も本実装のポイントです。ボット対策には Cloudflare Turnstile を導入しました。従来の画像認証（CAPTCHA）のような、ユーザーの手を止める複雑なパズルを強いることなく、バックグラウンドで安全性を確認できるため、コンバージョンを妨げないスムーズな送信体験を提供しています。
さらに、フォーム送信後の通知基盤には Resend を採用しました。モダンなメール配信プラットフォームを活用することで、確実かつ迅速なメール到達を実現しています。これらの技術選定により、単なる機能としてのフォームを超えた、信頼感のあるモダンなユーザーインターフェースを構築することができました。
緻密なキャッシュ戦略とWebhookによる即時更新
Next.jsでの開発において、パフォーマンスとデータの鮮度の両立は非常に重要なテーマです。本プロジェクトでは、WordPress側での更新を即座にサイトへ反映させるため、Next.jsのData Cacheと**タグベースの再検証（Revalidation）**を組み合わせたキャッシュ戦略を構築しました。
具体的には、fetchリクエスト時にデータ種別ごとのタグ（articles, works, pagesなど）を付与してキャッシュを保持させています。このキャッシュの廃棄にはWebhookを活用しており、WordPress側で記事や固定ページが更新された瞬間にNext.js側のAPIルート（/api/revalidate）へ通知を飛ばし、該当するタグのキャッシュのみをピンポイントで削除（revalidateTag）する仕組みを整えました。
Next.jsのキャッシュ仕様は複雑で扱いが難しい側面もありますが、このように「必要なときだけ捨てる」という明示的な制御を行うことで、サーバー負荷を最小限に抑えつつ、常に最新のコンテンツをユーザーに届ける安定した配信基盤を実現できました
多彩な要件に応える検索・フィルタリング機能
WordPressの柔軟なデータ構造を活かし、カテゴリーやタグ、カスタムタクソノミー、さらには日付やフリーワードによる詳細な検索・絞り込み機能を実装しました。
設計上の工夫として、情報の階層構造を重視すべきカテゴリーやタグの遷移には、SEOに有利なサブディレクトリ形式（動的セグメント）を採用しています。一方で、複数の条件が重なる動的な絞り込みや、検索ワードの保持が必要なケースにはクエリパラメータを用いるなど、用途に応じてルーティングを最適化しました。膨大なコンテンツの中からユーザーが目的の情報へ迷わず辿り着けるよう、静的な構造美と動的な柔軟性を両立させたナビゲーションを実現しています。
既存資産の整理とプラグインの削減
モダンなフロントエンドへの移行は、単なる見た目の刷新ではなく、長年蓄積された「レガシーな仕組み」を整理する貴重な機会となりました。
特に注力したのは、WordPress側の徹底的な軽量化です。これまでプラグインに依存していた目次生成（ToC）やテーブルの装飾、お問い合わせフォームといった機能をフロントエンド側のReactコンポーネントとして再定義しました。これにより、バックエンド側の不要なプラグインを大幅に削減でき、システムの脆弱性リスクを抑えるとともに、依存関係に振り回されないシンプルな構成を実現しました。
新旧の仕様が混在する中で、捨てるべきものは潔く捨て、必要な機能はモダンな形で再構築する。この「レガシーとの折り合い」を丁寧につけたことが、本プロジェクトにおける保守性の根幹を支えています。
次にやりたいこと：UIの刷新とデザインへの挑戦
今回のリニューアルでは、内部のデータ処理やパフォーマンスといった「基盤の再構築」に主眼を置いたため、視覚的なデザインはあえて従来のものを継承しました。データの流れを完全に制御下に置いた今、次のステップとして見据えているのは、ユーザー体験を直接左右するUIの全面的なブラッシュアップです。
特に、AIによるデザイン支援（Claude Design等）の進化には目を見張るものがあり、こうした最新技術を積極的に取り入れることで、より直感的で洗練されたビジュアル表現へのアップデートにチャレンジしたいと考えています。堅牢なバックエンドと、AIによって磨かれたフロントエンドを融合させ、より高い次元でのポートフォリオ完成を目指します。
おわりに：技術の刷新を終えて
今回のヘッドレス化を通じて、データ取得や表示のロジックを以前より明示的に扱える基盤が整いました。
Next.jsのキャッシュ制御やGraphQLの導入、AIを活用したスタイルの移行など、一つひとつの仕組みを整理したことで、型安全性の向上や表示の高速化といった具体的なメリットを享受できています。
もちろん、これが完成形ではなく、ブラックボックスとして残っている部分や調整が必要な箇所も依然として存在します。まずはこの新しい構成をベースに、次はUIの改善やAIを活用したデザインのブラッシュアップなど、よりユーザー体験に直結する部分のアップデートを進めていく予定です。
