GraphQL Code Generator の使い方。〜GraphQLのSchemaからTSの型定義を自動生成する〜

TypeScript × GraphQLの開発で必須のライブラリ GraphQL Code Generator の紹介です。

graphql codegenとは？

GraphQLのエンドポイントや、GraphQLのschema定義からTypeScriptの型定義を生成するCLIツールです。
しかも、生成するものはTypeScriptの型定義だけに限らず、Pluginを使うことでApolloクライアントのコードや、TypeScriptのリゾルバ、Javaのリゾルバまで様々なものを生成できます。

生成するもの一例

• TypeScriptの型定義 <= 今回説明
• TypeScriptのオペーレーションの型定義 <= 今回説明
• schema.graphqlファイル <= 今回説明
• vue-apolloのクライアントコード
• react-apolloのクライアントコード
• TypeScriptのリゾルバ
• Floq Type
• Javaのリゾルバ
  ...などなど

setup

プロジェクトのディレクトリで以下を実行してください。

npx graphql-codegen init

init時の選択内容に合わせてcodegen.ymlが生成されます。

最小の設定ファイルは以下の通りです。

codegen.yaml

schema: エンドポイントのURL、schemaファイルパス
generates:
  生成したいファイルパス
    plugins:
      使用するプラグイン

TypeScriptの型定義を生成

まず、基本のGraphQLのschemaからTypeScriptの型定義を生成する方法です。
codegen.yamlを以下のように設定します。

schema: "https://example.com/v1/graphql"
generates:
  ./src/@types/types.d.ts:
    plugins:
      - typescript

そしてcli設定時に指定したnpmスクリプトを実行すると./src/@typesにtypes.d.tsが生成されるはずです。

# init時に設定したnpmスクリプト名で実行
yarn codegen

operationsの型定義の生成

schemaからの自動生成の型以外にも、プロダクトで使っているQuery, Mutationsからその操作専用の型を作ることもできます。
@graphql-codegen/typescript-operations を 追加して以下のようにcodegen.ymlを修正しましょう。

yarn add -D @graphql-codegen/typescript-operations 

codegen.yaml

  schema: "https://example.com/v1/graphql"
+ documents: src/graphql/**/*.ts
  generates:
    ./src/@types/types.d.ts:
      plugins:
        - typescript
+       - typescript-operations

この状態でyarn codegenを実行すると、以下の生成対象のオペレーション（Mutation）のから、

addProduct.ts

export const ADD_PRODUCT = gql`
    mutation AddProduct($name: String!) {
        insert_products(objects: { name: $name }) {
            returning {
                id
                name
                created_at
            }
        }
    }
  `

Mutationの戻り値と、引数の型が自動生成されます。apolloクライアントを使う際の型指定などでそのまま使えます！

type.d.ts

export type AddProductMutationVariables = {
  name: Scalars['String'];
};

export type AddProductMutation = (
  { __typename?: 'mutation_root' }
  & { insert_products?: Maybe<(
    { __typename?: 'products_mutation_response' }
    & { returning: Array<(
      { __typename?: 'products' }
      & Pick<Products, 'id' | 'name' | 'created_at'>
    )> }
  )> }
);

schema.graphqlの生成

HASURAなどのGraphQLエンジンを使っていて、手元にschema.graphqlがない場合にはそちらも生成することが出来ます。

yarn add -D @graphql-codegen/schema-ast

codegen.yaml

  schema: "https://example.com/v1/graphql"
  documents: src/graphql/**/*.ts
  generates:
    ./src/@types/types.d.ts:
      plugins:
        - typescript
        - typescript-operations
+   ./schema.graphql:
+     plugins:
+       - schema-ast

この状態でyarn codegenを実行するとプロジェクトルートに./schema.graphqlが生成されます。

schema.graphqlがあるとIntelliJのJS-GraphQLプラグインなどでコード補完が効くようになりとても便利です。

JS-GraphQLについては、intelliJでgraphQLを書くときに便利なプラグイン で紹介してます。

終わりに

GraphQLとTypeScriptに合わせてgraphql codegenを使うことで開発体験が大きく変わるな〜と思います。