GraphQL Code Generation: Automate Client and Server Typing

You wrote a GraphQL schema, deployed a server, but client types don't match — runtime error in production. Manual synchronization eats up to 40% of development time, and each mismatch error accounts for 15–20% of pull requests that get returned for rework. We've seen projects where type mismatch crashed search, and the fix took a week. One such incident cost tens of hours of overtime, which at average team rates means a loss of $5,000–$10,000.

Automated typing with GraphQL Code Generator is 5x faster than manual type maintenance and completely eliminates mismatch errors. The tool analyzes the schema and operations, generates TypeScript types, hooks, and resolvers. No manual work — errors are caught at compile time. Over the last few years, we have integrated codegen into 20+ projects of various scales: from startups to enterprise systems with 200+ operations and 80+ GraphQL types. Average reduction in typing time is 70%, equivalent to a budget saving of up to $15,000 per year for a team of 5 developers. The number of bugs related to schema mismatch dropped to zero. Teams that previously spent hours on synchronization now simply run npm run codegen.

What problems we solve

• Schema and type desynchronization. Every schema change breaks types. Codegen updates them automatically on each run.
• N+1 query on the client. Generated hooks are strictly typed — it's impossible to request a non-existent field or forget to add a field to a query.
• Code duplication. One source of truth — the schema. Types, resolvers, and even validations are generated from it.
• Errors in resolvers. TypeScript checks signatures and return types — whole classes of errors disappear.

We integrated codegen into a project with 80+ types and 200+ operations. Typing time was reduced by 70%, and the number of bugs in resolvers dropped to zero. The integration took 3 days: configuration, testing, CI/CD.

Why automate type generation?

Manual type maintenance is a source of bugs and wasted time. Compare:

Time savings directly convert to money: at $50/hour, a team of 5 saves up to $1,500 per week.

Eliminating desynchronization with codegen

Codegen uses a configuration file codegen.yml, where you specify the schema, documents, and target plugins. It parses the schema, finds all operations, and generates types, resolvers, and hooks. On each run — full regeneration, so types are always up to date.

What is Fragment Masking and why do you need it?

Fragment Masking guarantees that a component receives only the requested fields — no accidental dependencies. For example, fragment fragment UserAvatar on User { id name avatarUrl } isolates data for the avatar component and prevents it from reading extra fields. This prevents errors where a change in one component's query breaks another.

Configuring Fragment Masking

To enable Fragment Masking, you need to add the typed-document-node plugin and use useFragment from @graphql-codegen/typescript-react-apollo. In codegen.yml, just specify withHooks: true — fragment masking is generated automatically. Example usage:

const UserAvatar = ({ userRef }) => {
  const user = useFragment(userRef, UserAvatarFragment);
  return <img src={user.avatarUrl} alt={user.name} />;
};

This guarantees that user contains only fields from the fragment.

Installation and configuration

npm install -D @graphql-codegen/cli @graphql-codegen/typescript \
  @graphql-codegen/typescript-resolvers \
  @graphql-codegen/typescript-operations \
  @graphql-codegen/typescript-react-apollo \
  @graphql-codegen/introspection

# codegen.yml
overwrite: true
schema: "http://localhost:4000/graphql"
documents: "src/**/*.graphql"

generates:
  src/generated/graphql-server.ts:
    plugins:
      - typescript
      - typescript-resolvers
    config:
      contextType: "../context#GraphQLContext"
      mappers:
        User: "../models/User#UserModel"
        Post: "../models/Post#PostModel"
      useIndexSignature: true
      enumsAsTypes: true
      avoidOptionals:
        field: true

  src/generated/graphql-client.ts:
    plugins:
      - typescript
      - typescript-operations
      - typescript-react-apollo
    config:
      withHooks: true
      withComponent: false
      withHOC: false
      dedupeFragments: true

  src/generated/introspection.json:
    plugins:
      - introspection

How we do it: implementation process

1. Schema and operations analysis. We study the current schema, documents, and file structure. We identify common patterns — mappers, context, nullability.
2. Configuration setup. We describe codegen.yml: specify schema, documents, target plugins, and mappers. We consider avoidOptionals and enumsAsTypes for strictness.
3. Generation and testing. We run codegen, verify that all types are correct, and compile the project. We enable strict mode and TypeScript.
4. CI/CD integration. We add a script to package.json and a workflow for GitHub Actions — we check that generated files are committed and synchronized.
5. Documentation and handover. We describe the process for the team, set up watch-mode for local development.

Example CI/CD workflow

name: GraphQL Codegen Check
on: [pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: npm ci
      - name: Start GraphQL server
        run: npm run dev &
      - name: Wait for server
        run: npx wait-on http://localhost:4000/graphql
      - name: Run codegen
        run: npm run codegen
      - name: Check for uncommitted changes
        run: |
          if [[ -n $(git diff --name-only) ]]; then
            echo "Generated files are out of sync. Run npm run codegen."
            git diff
            exit 1
          fi
      - name: TypeScript check
        run: npm run type-check

What's included in the work

• Configuration of codegen.yml for your schema and operations.
• Generation of server and client types.
• Setup of mappers for resolvers and context.
• CI/CD integration with pull request checks.
• Documentation on running and maintenance.
• Team training (1–2 hours).

Timelines

Basic setup takes from 2 to 5 working days. The cost is calculated individually based on schema complexity and number of operations. We'll estimate your project for free — contact us.

Get a consultation. Order GraphQL Code Generator implementation — eliminate runtime errors and accelerate development. Our engineers hold GraphQL certifications and have experience with code generation on projects of any complexity.

GraphQL Code Generator Documentation

API Development with REST, GraphQL, WebSocket, and tRPC

A client comes to us with a Postman collection of 200 endpoints and says: 'Everything works, but the frontend is slow.' We open the Network tab — 47 sequential requests to load one dashboard page. Each one waits for the previous. This is not a server speed issue — it's an API architecture problem. With 10 years on the market, we've redesigned dozens of such integrations, and we guarantee: the right protocol and contract solve the problem at its root.

When REST stops being enough

REST works well for simple CRUD operations. But as soon as a mobile app appears alongside the web interface, over-fetching begins: the mobile app requests /api/users/123 and gets a 4KB object, but only needs name and avatar. Multiply that by a list of 50 users — 200KB traffic instead of 8KB.

GraphQL solves this with selection sets. The client describes exactly the fields it needs, and the server returns only those. On a project with React Native + Next.js, we migrated from REST to Apollo Server: payload size on the main screen dropped from 340KB to 28KB — a 92% traffic savings. Our certified engineers confirm: the typical pain when adopting GraphQL is N+1 query. A resolver for the author field on a post calls SELECT * FROM users WHERE id = ? for each post in the list. On a page with 20 posts — 21 database queries. Solved with DataLoader — it batches queries and turns them into one SELECT * FROM users WHERE id IN (...).

What is tRPC and how is it better than REST/GraphQL?

If the entire stack is TypeScript (Next.js + Node/Bun), tRPC removes a whole layer of problems. You define a procedure on the server — the client gets full type-safety automatically, without code generation and without Swagger. Renamed a field in the Zod schema — TypeScript highlights all places on the frontend where it's used. tRPC reduces code by 2 times compared to REST + Swagger + openapi-typescript: no need to maintain a separate specification and generate types — everything is inferred from runtime validators. However, tRPC is not suitable if the API is consumed by third-party clients or mobile apps in other languages — in such cases we use GraphQL or REST with OpenAPI specification.

WebSocket and real-time: when SSE, when WS?

HTTP polling every 5 seconds is an illusion of real-time with up to 5 seconds delay and useless server load. For chats, live notifications, collaborative editing — WebSocket or Server-Sent Events. SSE is a one-way stream from server to client, works over ordinary HTTP, automatically reconnects. Suitable for notifications, data streaming, progress bars. WebSocket is bidirectional, needed for chats and collaborative features. Experience shows: 80% of 'real-time' tasks are solved with SSE, not WebSocket — fewer infrastructure complexities.

A typical mistake: opening a WebSocket connection for each page component. On one project, the dashboard opened 12 parallel WS connections. The correct approach is one connection manager at the application level, subscriptions through it. In our work results, we always transfer the connection scheme and a ready solution.

Swagger / OpenAPI as a contract

Documentation written after the fact becomes outdated the day after release. We write the OpenAPI 3.1 specification before development starts; it becomes the contract between frontend and backend. The frontend generates types via openapi-typescript, the backend validates incoming data using generated schemas. Contract deviation from implementation is caught on CI, not during review. For Laravel — l5-swagger or dedoc/scramble. For Node.js — @fastify/swagger or Zod + zod-to-openapi.

How to properly authenticate an API?

JWT with long-lived access tokens without rotation is a source of problems when compromised. The correct scheme: access token for 15 minutes, refresh token for 30 days with rotation on each use. Refresh token stored in an httpOnly cookie, access token in memory (not in localStorage). For inter-service communication — API Keys with scope limitations or mTLS. OAuth 2.0 with PKCE for public clients (SPA, mobile).

How to handle versioning and backward compatibility?

Breaking changes in an API without versioning break clients. Three approaches we use in projects:

We guarantee backward compatibility through automated checks (oasdiff) on CI.

How we develop APIs: step-by-step plan

1. Analysis — audit of current integrations, data schema compilation, protocol selection (REST/GraphQL/tRPC/WebSocket).
2. Contract design — OpenAPI or SDL (GraphQL) before the first line of code.
3. Development — implementation per contract, unit tests for each endpoint.
4. Load testing — k6: 500 virtual users, 10 minutes, p95 latency ≤ 200ms.
5. Deployment — CI/CD with backward compatibility check, automatic documentation publication.
6. Team training — handover of Postman collection or Playground, connection instructions.

What is included (deliverables)

• OpenAPI 3.1 specification (or SDL for GraphQL).
• Generated client types for TypeScript / Dart / Kotlin.
• Set of automated tests covering all endpoints (unit + integration).
• Load tests (k6) and report (p50/p95/p99 latency, RPS).
• Documentation in Swagger UI / Redoc / GraphiQL.
• Team training (2–4 hour workshop).
• Support for 30 days after delivery (per contract).

Our experience

• 10+ years in the API development market.
• 200+ completed projects (REST, GraphQL, WebSocket, tRPC).
• 50+ certified engineers (AWS, Kubernetes, API Design).
• Traffic savings averaging 85% when migrating from REST to GraphQL for mobile apps.
• 100% backward compatibility — not a single broken client in the last 3 years.

Timeline

API development for a typical SaaS project with 30–50 endpoints: from 3 to 8 weeks depending on business logic complexity and number of external integrations. Migration of an existing REST API to GraphQL: from 2 to 6 weeks. Adding a WebSocket layer to an existing backend: from 1 to 3 weeks. Cost is calculated individually after an audit. Get a consultation — contact us to discuss your project.