1. はじめに
フロントエンド開発で、こんな経験はありませんか？
- バックエンドの API 仕様が変わったのに気づかず、画面がクラッシュした
- サーバーのレスポンスに合わせて、手作業で
type User = { ... }と何十行も型定義を書くのが苦痛 - タイポ（打ち間違い）で
createdAtをcreated_atと書いてバグらせた
これらを一撃で解決し、フロントエンドとバックエンドの型を 100% 完全同期 させてくれる技術が 「GraphQL Code Generator（通称: codegen）」 です。
今回は、この GraphQL Code Generator の基本と、現場で必ず巻き起こる 「自動生成されたコードは .gitignore すべき？ それとも Git にコミットすべき？」 という大論争のベストプラクティスについて解説します。
2. GraphQL Code Generator とは？
「サーバーの仕様書（スキーマ）を読み取り、TypeScript の型定義ファイルを自動で生成（ジェネレート）してくれるツール」 です。
なぜ使うのか？（手動との圧倒的な違い）
-
手作業ゼロで数千行の型が手に入る
巨大なサービスになると、データモデルは数十〜数百種類に及びます。人間が手書きしたら何日もかかる作業が、コマンド一発（数秒）で終わります。 -
「スキーマ駆動開発」の実現
サーバー側でフィールド名が変わったり削除されたりした場合、codegen を叩くだけで TypeScript のコンパイラが「ここの型が変わったよ！」と赤波線で瞬時にエラーを教えてくれます。本番デプロイ前にバグを 100% 炙り出せます。 -
IDE のオートコンプリート（補完）が超快適
エディタでdata.と打つだけで、サーバーから返ってくるプロパティ一覧がサジェストされます。ドキュメントをいちいち見に行く必要すらなくなります。
3. 基本的な仕組みとコード例
設定ファイル（codegen.ts）に「どこからスキーマを取得して、どこに出力するか」を記述します。
// codegen.ts
import type { CodegenConfig } from "@graphql-codegen/cli";
const config: CodegenConfig = {
overwrite: true,
// 1. サーバーのスキーマ（設計図）の場所
schema: "https://api.example.com/graphql",
// 2. フロントエンドで GraphQL を使っているファイルを指定
documents: ["src/**/*.tsx", "src/**/*.ts"],
// 3. 生成先と出力形式
generates: {
"src/gql/": {
preset: "client", // 最新の推奨プリセット
},
},
};
export default config;
あとはコマンドを実行するだけです。
$ yarn codegen
✔ Parse Configuration
✔ Generate outputs
✨ Done in 1.45s.
たったこれだけで、src/gql/graphql.ts の中に数千〜数万行の完全な TypeScript 型定義が一瞬で生成されます。
4. 【本題】自動生成されたファイルは .gitignore するのが最善なの？
ここからが本題です。
実はこの問い、エンジニア界隈でも意見が真っ二つに分かれる有名な論争テーマです。
結論から言うと、「どちらにも明確なメリット・デメリットがあり、プロジェクトの運用体制によって最善が変わる」 のが現実です。
それぞれの主張を見てみましょう。
アプローチ A：.gitignore に追加する派（Git 管理しない）
「コンパイル結果や自動生成物はリポジトリを汚すからコミットしないのが美学！」
メリット
-
プルリクエスト（PR）が汚れない（超重要）
自動生成ファイルは数千行〜数万行になることがあります。Git 管理外にしておけば、PR の Diff（差分画面）が自動生成コードで埋め尽くされる悲劇を防げます。 -
コンフリクト（衝突）が起きない
複数人が同時に開発しているとき、自動生成ファイルの衝突マージ地獄に悩まされずに済みます。
デメリット・落とし穴
-
git clone直後にプロジェクトが壊れる（型エラー祭り）
新メンバーがリポジトリを clone して開くと、型ファイルが存在しないため、エディタ全体が真っ赤（インポートエラー）になります。「まず最初にyarn codegenを叩いてね」という手順が必須になります。 -
CI（自動テスト・ビルド）でサーバー接続が必要になる
GitHub Actions 等でビルドや型チェック（tsc）を行う際、CI 上でもyarn codegenを叩く必要があります。しかし、CI 環境から開発サーバーや本番 API にアクセスできない（ネットワーク制限・VPN・認証）場合、ビルドがコケます。
アプローチ B：Git にコミットする派（Git 管理する）
「clone したら即動くべき！ CI をシンプルにするためにもコミットすべし！」
メリット
-
clone してすぐに動く・型チェックが通る（開発者体験が良い）
リポジトリを落としてきてyarn installすれば、codegen を叩かなくても即座にアプリがビルドでき、型チェックも通ります。 -
CI 環境が外部 API に依存しない
CI パイプライン上で GraphQL サーバーと通信する必要がありません。API サーバーがダウンしていても、CI の型チェックやビルドは正常に動きます。 -
スキーマの変更履歴（History）が Git で追える
「いつ、どの PR でこの型が追加されたのか」を Git のコミットログから追跡できます。
デメリット
-
PR のレビューが地獄になる（差分爆発）
ちょっとした機能追加の PR なのに、codegen の差分が 10,000 行混ざってしまい、レビュアーが「本当に手書きした 5 行」を探せなくなります。
5. 現場での結論：どちらが「最善」なのか？
現在、モダンな Web 開発における 業界のデファクトスタンダード（主流）は「コミットする派（アプローチ B）」に傾きつつあります。
なぜなら、CI 環境のセキュリティ（API へのアクセス権限管理）や、新しく入った開発者のオンボーディングコストを考えると、「リポジトリ内に型が存在している」状態の方が圧倒的にトラブルが少ないからです。
「でも、PR の差分が埋まる問題はどうするの？」への神対応
「コミットしたいけれど、PR の差分が巨大になるのが嫌だ」という問題は、GitHub の公式機能 .gitattributes を使うことで完全に解決できます！
プロジェクトのルートに .gitattributes というファイルを作り、以下を1行書くだけです：
# 自動生成ファイルを「Generated（生成物）」として GitHub に認識させる
src/gql/** linguist-generated=true
これを設定すると、GitHub の PR 画面で 自動生成ファイルの差分がデフォルトで自動的に折りたたまれる（Collapsed） ようになります！
▼ src/gql/graphql.ts (Generated - 5,420 lines hidden) [Load diff]
レビュアーは手書きしたコードだけに集中でき、必要なときだけ「Load diff」を押して生成差分を確認できます。これで 両方のいいとこ取り ができます。
6. まとめ：あなたのチームはどちらを選ぶべき？
| 判断基準 | おすすめ |
|---|---|
| CI 環境から GraphQL API に直接アクセスできない（またはさせたくない） |
コミットする（.gitattributes を併用） |
| 新メンバーが参加したときに「動かない」トラブルを減らしたい |
コミットする（.gitattributes を併用） |
外部 API との通信が不要なローカル完結のスキーマファイル（.graphql）がある |
どちらでもOK（CI で高速に生成できるなら .gitignore もあり） |
| 何が何でもリポジトリを軽量に保ち、手書きコード以外一切入れたくない |
.gitignore する（ビルドスクリプトに codegen を組み込む） |
GraphQL Code Generator はフロントエンドの生産性を劇的に引き上げてくれる強力な武器です。
チームの CI/CD パイプラインやレビュー文化に合わせて、最適な管理方法を選択してみてください！