タグ: WPGraphQL

ポートフォリオサイトを、素のHTMLで書かれた静的サイトから「ヘッドレスWordPress + Next.js」という構成に作り直しました。前回までの記事では、実際にやった作業と、そこでつまずいた内容を書いてきました。

今回は少し引いた視点で、そもそもなぜこの構成にしたのかを書きます。技術選定の話です。

結論から言うと、この構成は万人向けではありません。個人のポートフォリオという規模に対しては、明らかに過剰な部分があります。それでも選んだ理由と、その代わりに何を失ったのかまで含めて残しておきます。選定の記事は、良い点だけ並べても参考にならないと思うからです。

まず全体像

完成した構成はこうなっています。

記事を書くのはWordPressの管理画面。表示するのはNext.js。両者はGraphQLというやり取りの決まりでつながっています。

なぜヘッドレスにしたのか

元のサイトは素のHTML・CSS・JavaScriptで書かれた静的サイトでした。表示は速く、構成もシンプル。悪くありません。

ただ、実績を1件追加するのにHTMLを直接編集する必要がありました。文章の言い回しを直したいだけなのに、エディタでタグを探して、間違えないように書き換えて、アップロードし直す。これを何度か繰り返すうちに、更新のしやすさが欲しくなりました。

ここで普通に考えると、選択肢は2つあります。

案Aで十分だったと思います。実際、更新のしやすさだけが目的ならそれが正解です。

それでも案Bを選んだ理由は2つあります。

ひとつは表示側を自由に作りたかったこと。WordPressのテーマを作る場合、PHPのテンプレート階層という作法に沿うことになります。慣れれば速いのですが、今回は「もとのサイトの見た目を保ちつつ、新しい書き方で作り直す」のが目的だったので、表示側は白紙から書きたかった。

もうひとつが正直なところ大きいのですが、学習目的です。普段の実務ではヘッドレスCMSやGraphQL、Next.jsのApp Routerに触れる機会がありません。自分のポートフォリオという、壊れても誰も困らない題材で試してみたかった、というのが本音です。

なぜWordPressを残したのか

ヘッドレス構成にするなら、データを持つ側はWordPressである必要はありません。microCMSやContentfulのような最初からヘッドレス前提で作られたCMSもあります。

それでもWordPressを選んだ理由は3つです。

1. 管理画面の完成度

記事を書く画面、画像をアップロードする画面、カテゴリを整理する画面——WordPressのそれらは20年かけて磨かれています。自分で書くつもりなら、この使い勝手は無視できません。

2. ACFによる構造化

今回のサイトには「実績」と「スキル」という、普通の記事とは形の違うデータがあります。

実績: タイトル / 説明 / 役割 / 期間 / 使用技術 / カテゴリ / 画像
スキル: 名前 / 習熟度（10段階） / 説明 / カテゴリ

これを本文にベタ書きすると、あとで「使用技術だけ一覧したい」といった扱いができません。ACF（Advanced Custom Fields）というプラグインを使うと、こうした項目を管理画面に専用の入力欄として追加できます。

入力する側から見ると「役割」「期間」という欄が並ぶだけですが、データとしてはきちんと項目に分かれているので、表示側で自由に組み替えられます。

3. 自分が慣れている

実務でWordPressのテーマ制作をしてきたので、管理画面の構造もカスタム投稿タイプの考え方も分かっています。新しいことを1つ試すときは、他をなるべく既知のもので固める——今回はフロントエンド側で新しいことをたくさんやるので、CMS側は慣れたもので押さえておきたかった、という判断です。

なぜNext.jsなのか

表示側にはNext.jsを選びました。ReactというUIライブラリをベースにしたフレームワークです。

選定理由は、サーバー側でデータを取ってHTMLを組み立てられる点にあります。

Reactだけで作ると、ブラウザ側でJavaScriptが動いてからデータを取りに行く形が基本になります。この場合こういう流れです。

【ブラウザ側で取得する場合】
1. ブラウザが空っぽのHTMLを受け取る
2. JavaScriptを読み込んで実行する
3. そこからAPIにデータを取りに行く
4. 返ってきたデータで画面を描く
   → 4に到達するまで、画面には何も出ない
   → 検索エンジンにも中身が伝わりにくい

Next.jsのサーバーコンポーネントを使うと、この流れが変わります。

【サーバー側で取得する場合】
1. サーバーがWordPressからデータを取る
2. サーバーが中身の入ったHTMLを組み立てる
3. ブラウザは完成したHTMLを受け取る
   → 最初から中身が見える
   → 検索エンジンにも内容が伝わる

ポートフォリオは検索から見つけてもらうことに意味があるサイトなので、この違いは重要でした。

ちなみにこの選択が、後の大トラブルの前提にもなっています。サーバーがサーバーを呼ぶという通信経路ができるため、ブラウザから確認しても分からない問題が起きうるのです。実際、SSL証明書の不一致でデータが一切取れないという事態に陥りました。詳細は前回の記事に書いています。

なぜGraphQLなのか（RESTではなく）

WordPressには標準でREST APIという仕組みが備わっています。追加のプラグインなしで使えます。それでもGraphQLを選びました。

RESTの場合に起きること

REST APIは「URLごとに決まった内容が返ってくる」方式です。実績一覧が欲しければ、こう叩きます。

GET /wp-json/wp/v2/project

返ってくるのは、その投稿タイプが持つほぼ全部の項目です。使うのがタイトルと画像とカテゴリだけでも、更新日時も編集履歴のIDもコメント設定も付いてきます。

さらに困るのが、関連するデータが別のリクエストになることです。

1. 実績一覧を取る          → GET /wp/v2/project
2. 各実績のカテゴリ名を取る  → GET /wp/v2/project_category?include=...
3. 各実績の画像URLを取る     → GET /wp/v2/media?include=...
   → 画面ひとつ描くのに3往復

GraphQLの場合

GraphQLは「欲しい項目を書いて送ると、その形で返ってくる」方式です。

query GetProjects {
  projects(first: 100) {
    nodes {
      title
      uri
      featuredImage { node { sourceUrl altText } }
      projectCategories { nodes { name slug } }
      projectDetail { role period toolsused }
    }
  }
}

これで1回のリクエストです。画像もカテゴリもACFの項目も、まとめて必要なぶんだけ返ってきます。

決め手は型の自動生成だった

ただ、往復回数の削減だけならRESTでも工夫でどうにかなります。決め手になったのは別の点でした。

GraphQLにはスキーマという「どんなデータがどんな形で存在するか」の定義があり、これを機械が読み取れます。この性質を利用したのが GraphQL Codegen というツールです。

npm run codegen

これを実行すると、書いたクエリを読み取ってTypeScriptの型定義を自動生成してくれます。結果として、エディタ上でこうなります。

project.  ← ここまで打つと、使える項目が候補に出る
project.titel  ← 打ち間違えると即座に警告が出る

ACFで項目を追加してWordPress側の構造が変わっても、コマンド1つで型が追従します。手で型を書き直す必要がありません。

なぜVercelなのか

Next.jsを公開する場所として、Vercelを選びました。Next.jsを作っている会社が運営しているサービスです。

理由は3つあります。

1. GitHubに置くだけで公開される

GitHubにコードをpushすると、Vercelが自動で検知してビルドし、公開まで済ませます。手作業のアップロードが要りません。今回の作業でも、修正をpushするたびに自動で本番へ反映されました。

2. 設定がほぼ不要

Next.jsのプロジェクトだと自動で判別され、必要な設定はほぼありません。実際に指定したのは2つだけでした。

Root Directory : frontend
環境変数        : NEXT_PUBLIC_WORDPRESS_API_URL

3. 個人利用なら無料

ポートフォリオ程度のアクセス数なら無料枠に収まります。独自ドメインの接続もSSL証明書の発行・更新も無料で自動です。

SSL証明書は通常90日で期限が切れ、更新が必要です。これを忘れるとサイト全体が「安全でない接続」と表示されて事実上使えなくなります。Vercelはこれを自動でやってくれるので、運用の手間がひとつ消えます。

なぜCMSは共用サーバーのままなのか

ここは技術選定というより、現実的な事情です。

WordPressをVercelに置くことはできません。PHPとデータベースが必要だからです。置き場所は別に必要になります。

選択肢はいくつかありましたが、もともとお名前.comの共用サーバーを契約していて、旧サイトがそこで動いていました。新しく契約すれば月額が増えます。既存の契約で足りるなら、それでいい。

ただし、この判断には代償がありました。

とはいえ、これらは調べれば分かる範囲の問題でした。学習目的という文脈では、むしろ良い題材だったとも思っています。

この構成で払った代償

ここが、この記事でいちばん書きたかった部分です。

1. 管理する場所が2つになった

静的サイトなら、置き場所は1つでした。いまは2つです。それぞれにドメイン、SSL証明書、更新、バックアップの管理が発生します。

【静的サイト】 1箇所
【今の構成】   Vercel + 共用サーバー = 2箇所
               ＋ GitHub（コードの置き場所）= 実質3箇所

2. CMSが落ちるとサイトが空になる

これがいちばん大きい代償です。表示側と、データを持つ側が分かれているということは、データ側が落ちると表示側は空を返すということです。

実際、SSL証明書の問題でWordPressに接続できなかったとき、サイトは正常に表示されるのに実績もスキルも記事も1件も出ない状態になりました。しかもHTTPステータスは200なので、普通の死活監視では検知できません。

静的サイトなら、こんなことは起きません。HTMLに中身が書いてあるからです。

3. 分業ゆえの複雑さ

ヘッドレス構成では「サーバーがサーバーを呼ぶ」経路ができます。この経路はブラウザからは見えません。

今回、ブラウザからは正常にアクセスできるのにサーバーからは失敗する、という状況で数時間はまりました。確認方法そのものを間違えていたわけです。この落とし穴は、構成を分けたことの直接の帰結です。

4. ビルドという工程が増えた

静的サイトはファイルを置けば公開できました。いまはビルドが必要で、そこが失敗すると公開できません。実際、最初のデプロイは自動生成ファイルの不足で失敗しています。

選ばなかった選択肢

静的サイトジェネレータ + Markdown

AstroやHugoなどで、記事をMarkdownファイルとして書く方式です。CMSが不要になるので、構成は圧倒的にシンプルになります。管理場所も減り、CMSが落ちる心配もありません。

選ばなかったのは、記事を書く体験を落としたくなかったからです。画像の挿入、下書きの管理、公開日の設定——このあたりはWordPressの管理画面のほうが圧倒的に楽です。文章を書くこと自体のハードルは下げておきたい、と考えました。

ヘッドセスCMS（microCMS / Contentful など）

最初からヘッドレス前提のCMSです。サーバーの管理が不要になるのが大きな利点で、今回はまったSSL証明書やPHP設定の問題は最初から発生しません。

選ばなかった理由は、既にWordPressの資産（記事・画像・構造）があったこと、そして自分が慣れていることです。ゼロから始めるなら、こちらのほうが素直だと思います。

WordPressのテーマとして普通に作る

冒頭に書いた案Aです。この規模では、いちばん妥当な選択だったと思います。管理場所は1つ、ビルド不要、CMSが落ちればサイトも落ちるという単純明快な構造。

選ばなかったのは学習目的が大きいのですが、正直に言えば「新しい構成を試したかった」という動機が最初にあり、理屈は後から整理した部分もあります。

この構成が向いている人

一通りやってみて、こう思っています。

最後の点が重要だと思っています。今回の構成は部品が増えたぶん、壊れる箇所も増えました。実際、公開までにSSL証明書、DNS、環境変数、ビルド設定と、それぞれ別の理由で止まっています。

そのすべてが学びになったのは、これが止まっても誰も困らない自分のサイトだったからです。同じ構成を仕事で採用するなら、この「壊れる箇所の多さ」を運用体制で引き受けられるかどうかが判断の分かれ目になります。

技術選定に唯一の正解はありませんが、何を得て、代わりに何を失ったのかを説明できる状態にはしておきたい——今回それを整理してみて、そう感じました。