How to Use GraphQL Codegen: Simple Guide for Beginners

To use graphql-codegen, install it via npm, create a codegen.yml config file specifying your schema and documents, then run graphql-codegen to generate code like TypeScript types or React hooks automatically. This tool helps keep your GraphQL queries and types in sync with your backend.

Syntax

The basic syntax involves installing graphql-codegen, creating a configuration file, and running the codegen command.

• Installation: Use npm install -D @graphql-codegen/cli to add the tool.
• Config file: A codegen.yml file defines your GraphQL schema location, query documents, and output settings.
• Run command: Execute graphql-codegen in your terminal to generate code.

yaml

npm install -D @graphql-codegen/cli

# codegen.yml example
schema: ./schema.graphql
documents: ./src/**/*.graphql
generates:
  ./src/generated/graphql.ts:
    plugins:
      - typescript
      - typescript-operations
      - typescript-react-apollo

Example

This example shows how to generate TypeScript types and React Apollo hooks from a GraphQL schema and query.

bash

# 1. Install codegen CLI and plugins
npm install -D @graphql-codegen/cli @graphql-codegen/typescript @graphql-codegen/typescript-operations @graphql-codegen/typescript-react-apollo graphql

# 2. Create codegen.yml
schema: https://graphql-pokemon2.vercel.app/
documents: ./src/queries/*.graphql
generates:
  ./src/generated/graphql.ts:
    plugins:
      - typescript
      - typescript-operations
      - typescript-react-apollo

# 3. Example query file: src/queries/getPokemon.graphql
# query GetPokemon($name: String!) {
#   pokemon(name: $name) {
#     id
#     number
#     name
#   }
# }

# 4. Run codegen
npx graphql-codegen

# 5. Use generated hooks in React
# import { useGetPokemonQuery } from './generated/graphql';
# const { data, loading, error } = useGetPokemonQuery({ variables: { name: "Pikachu" } });

Output

✔ Parse configuration
✔ Generate outputs
✨  Done in 1.23s.

Common Pitfalls

Common mistakes when using GraphQL Codegen include:

• Not specifying correct paths for schema or documents in the config file, causing no code to generate.
• Forgetting to install required plugins for the desired output format.
• Running graphql-codegen without a config file or with syntax errors in it.
• Using outdated versions causing incompatibility with your GraphQL schema.

Always check your config file paths and plugin list carefully.

yaml

# Wrong config example (missing documents path)
schema: ./schema.graphql
generates:
  ./src/generated/graphql.ts:
    plugins:
      - typescript

# Correct config example
schema: ./schema.graphql
documents: ./src/**/*.graphql
generates:
  ./src/generated/graphql.ts:
    plugins:
      - typescript

Quick Reference

Here is a quick summary of key commands and config options:

Command / Config	Description
npm install -D @graphql-codegen/cli	Install GraphQL Codegen CLI
codegen.yml	Config file defining schema, documents, and output
schema	Path or URL to your GraphQL schema
documents	Path to your GraphQL query files
generates	Output files and plugins to use
npx graphql-codegen	Run code generation
plugins	Specify output types like typescript, react hooks

Key Takeaways

Install graphql-codegen CLI and required plugins before use.

Create a codegen.yml file specifying schema, documents, and output settings.

Run graphql-codegen command to generate types and hooks automatically.

Check paths and plugin names carefully to avoid generation errors.

Use generated code to keep your frontend GraphQL usage type-safe and synced.