【TypeScript】GraphQL Code Generatorで型を自動生成 - GraphQLとTypeScriptの統合

概要

TypeScriptでGraphQL APIを扱う際に、手動でクエリやレスポンスの型を定義するのは手間がかかり、メンテナンスが難しくなります。そんなときに役立つのがGraphQL Code Generatorです。GraphQL Code Generatorを使うと、GraphQLスキーマやクエリから自動的に型定義を生成でき、APIの変更にも対応しやすくなります。本記事では、GraphQL Code Generatorを使ってTypeScriptプロジェクトで効率的に型を自動生成する方法を解説します。

GraphQL Code Generatorとは？

GraphQL Code Generatorは、GraphQLスキーマとクエリからTypeScriptの型定義を自動生成するツールです。GraphQL APIとTypeScriptを統合し、型安全性を高め、開発効率を向上させるためのツールで、APIの変更があった場合にも手動の型修正が不要になるため、保守性も向上します。

GraphQL Code Generatorの導入手順

GraphQL Code Generatorを導入するための基本的な手順を以下に示します。

パッケージのインストール

まず、プロジェクトに必要なパッケージをインストールします。

# GraphQL Code Generatorと必要なプラグインのインストール
npm install @graphql-codegen/cli @graphql-codegen/typescript @graphql-codegen/typescript-operations graphql

• @graphql-codegen/cli
  Code GeneratorのCLIツール
• @graphql-codegen/typescript
TypeScriptの型を生成するためのプラグイン
• @graphql-codegen/typescript-operations
  GraphQLの操作（クエリ、ミューテーションなど）ごとに型を生成するプラグイン
• graphql
  GraphQLライブラリ本体

設定ファイルの作成

プロジェクトのルートにcodegen.ymlという設定ファイルを作成し、以下のように設定します。

schema: "https://example.com/graphql" # スキーマのURLかローカルファイルのパス
documents: "src//*.graphql"         # クエリやミューテーションの定義ファイル
generates:
  src/generated/graphql.ts:           # 型を出力するファイル
    plugins:
      - "typescript"
      - "typescript-operations"

• schema
  GraphQLのスキーマのパスまたはURL
• documents
  GraphQLクエリやミューテーションの定義ファイル
• generates
  型定義の出力先ファイルとプラグイン設定 この設定により、指定したスキーマとクエリからTypeScriptの型が自動生成されます。

型の生成

設定が完了したら、次のコマンドを実行して型を生成します。

npx graphql-codegen

このコマンドを実行すると、src/generated/graphql.tsに自動的に型定義が生成されます。

自動生成された型の使用方法

GraphQL Code Generatorによって生成された型は、プロジェクト内で簡単にインポートして使用できます。例えば、以下のようなクエリをuser.graphqlファイルで定義したとします。

# src/queries/user.graphql
query GetUser($id: ID!) {
  user(id: $id) {
    id
    name
    email
  }
}

このクエリに基づいて自動生成された型は、次のように利用できます。

import { GetUserQuery, GetUserQueryVariables } from "./generated/graphql";
// `TypeScript`の型が自動生成されているため、安全にAPIレスポンスを扱える
async function fetchUser(id: string): Promise<GetUserQuery> {
  const response = await fetch("https://example.com/graphql", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      query: `
        query GetUser($id: ID!) {
          user(id: $id) {
            id
            name
            email
          }
        }
      `,
      variables: { id },
    }),
  });
  const data: { data: GetUserQuery } = await response.json();
  return data.data;
}

ここでは、GraphQLクエリGetUserに基づいたGetUserQuery型と、クエリの引数を型安全に扱うGetUserQueryVariables型を活用しています。これにより、APIレスポンスや引数の型が保証され、開発効率とコードの安全性が向上します。

高度な設定とプラグインの活用

GraphQL Code Generatorには多くのプラグインや設定があり、プロジェクトのニーズに合わせて型生成をカスタマイズできます。代表的なプラグインのいくつかを紹介します。

typescript-react-apollo - React Apollo用の型生成

typescript-react-apolloプラグインを使うと、Apollo Clientと連携したフック（例: useQueryやuseMutation）の型を自動生成できます。これにより、Apollo Clientでのデータフェッチが型安全に行えるようになります。

設定例

以下のように、codegen.ymlにプラグインを追加します。

generates:
  src/generated/graphql.tsx:
    plugins:
      - "typescript"
      - "typescript-operations"
      - "typescript-react-apollo"
    config:
      withHooks: true  # React Hooksの生成を有効化

この設定により、クエリに対応するuseGetUserQueryといったフックが生成され、Reactコンポーネント内で簡単に型安全なデータ取得が可能になります。

使用例

import React from "react";
import { useGetUserQuery } from "./generated/graphql";
const UserProfile: React.FC<{ userId: string }> = ({ userId }) => {
  const { data, loading, error } = useGetUserQuery({
    variables: { id: userId },
  });
  if (loading) return <p>Loading...</p>;
  if (error) return <p>Error: {error.message}</p>;
  return (
    <div>
      <h1>{data?.user?.name}</h1>
      <p>{data?.user?.email}</p>
    </div>
  );
};

typescript-resolvers - サーバー側のリゾルバ型生成

typescript-resolversプラグインは、サーバーサイドでGraphQLのリゾルバ関数の型を自動生成するために使用します。リゾルバの引数や戻り値の型を保証することで、バックエンドの開発効率と安全性が向上します。

設定例

以下のように、プラグインを設定します。

generates:
  src/generated/resolvers.ts:
    plugins:
      - "typescript"
      - "typescript-resolvers"

リゾルバ型が生成されるため、サーバ ー側でのGraphQL API開発がより型安全に行えます。

自動生成により得られる利点

GraphQL Code Generatorによる型自動生成の主な利点は以下の通りです。

• 型安全性の向上
  クエリとレスポンスの型が保証されるため、APIの変更に強く、コンパイル時にエラーが検出できるようになります。
• 開発効率の向上
  手動で型を定義する必要がなくなり、クエリを追加するたびに自動的に型が生成されるため、開発スピードが上がります。
• メンテナンス性の向上
  APIの変更があっても再生成によって型が反映されるため、コードの保守が容易になります。

まとめ

TypeScriptとGraphQL Code Generatorを組み合わせることで、GraphQLスキーマとクエリから自動で型を生成し、型安全なデータ取得が可能になります。ReactアプリケーションにおけるApollo Clientとの連携や、サーバーサイドでのリゾルバの型定義にも対応しており、柔軟かつ効率的な型管理が実現できます。GraphQL Code Generatorを活用して、保守性と開発効率の高いTypeScriptプロジェクトを構築しましょう。