GraphQL Codegen は『型を1箇所で管理』する仕組み
GraphQL Codegen はスキーマからクライアント側の型・hooks を自動生成し、フロント-バックエンドの整合性を保ちます。本記事では編集部の視点で、運用を公開情報をもとに整理します。GraphQL 実践 もご参考に。
セットアップ
(1) @graphql-codegen/cli：本体。(2) codegen.ts：設定ファイル。(3) schema 指定：URL/ファイル/ファイル群。(4) documents 指定：クエリ収集対象。(5) plugins 指定：出力形式制御。
主要なプリセット
(1) client preset：URQL/Apollo Client 共通の現代的選択。(2) near-operation-file-preset：ファイル単位生成。(3) typescript-react-apollo：旧来の React Apollo。(4) typed-document-node：型情報付きノード。(5) schema-ast：スキーマファイル生成。新規は client preset が推奨です。
クエリの書き方
(1) gql タグでクエリ記述。(2) fragmentを活用。(3) colocation：コンポーネント横にクエリ。(4) watch mode：開発中自動再生成。(5) 命名規約：UpperCamelCase。
CI での運用
(1) pre-commit hook：codegen check。(2) CI で再生成：drift 検知。(3) スキーマ変更通知：breaking change 警告。(4) contract testing：消費者と生産者の契約。(5) scoped registration：規模が大きい場合の分割。CI/CD 実践 もご参考に。
tRPC との比較
(1) GraphQL Codegen：複数フロントエンド/外部公開向き。(2) tRPC：Single Monorepo の TS フルスタック。(3) 判断軸：公開APIなら GraphQL、内部閉じなら tRPC。(4) tRPC の限界：非 TS クライアントとの統合難。(5) 併用も可能：内外で使い分け。Hono 実践 もご参考に。
運用のベストプラクティス
(1) スキーマファースト：契約として扱う。(2) backward compatibility：フィールド削除回避。(3) fragment 粒度：コンポーネント単位。(4) パッケージ化：内部 npm パッケージ。(5) 型のコミット：CI で生成 vs リポにコミット の判断。
失敗しがちなパターン
(1) スキーマ変更で型崩壊。(2) codegen 忘れで型ズレ。(3) 巨大fragment：再利用性低下。(4) 不要なフィールド要求：オーバーフェッチ。(5) watch mode の不安定。対策は、(1)契約テスト、(2)pre-commit、(3)fragment 細粒度、(4)選択的取得、(5)watch代替で都度実行、です。