Generating TypeScript Types from Schemas

The Query String That Lies

Every GraphQL client ships operations as strings. TypeScript stops at the quotation mark: the document is a DocumentNode, the result is any, and nothing connects the two to your schema.

const QUERY = gql`
  query GetUser($id: ID!) {
    user(id: $id) { id fullName }
  }
`;

const data: any = await client.request(QUERY, { id });
data.user.fullName.toUpperCase();   // compiles no matter what the schema says

Rename fullName back to name in the schema and this file still compiles. The failure arrives in production as Cannot query field "fullName" on type "User" — the exact error a schema check or a typed build would have surfaced at review time.

Code generation closes the gap by making the types derive from the selection you wrote, not just from the schema:

type GetUserQuery = {
  user: { id: string; fullName: string } | null;   // mirrors schema nullability exactly
};
type GetUserQueryVariables = { id: string };

const GetUser: TypedDocumentNode<GetUserQuery, GetUserQueryVariables> = graphql`
  query GetUser($id: ID!) { user(id: $id) { id fullName } }
`;

const data = await client.request(GetUser, { id: 1 });
data.user?.fullName;   // string | null | undefined — the compiler knows the shape

Two properties of that generated type do the real work. It is selection-shaped: drop fullName from the query and the property disappears from the type, so client code reading it fails to compile. And it is schema-accurate: every ! you wrote in the schema becomes a non-nullable property and every nullable position becomes | null, so the null checks clients write match reality.

The alternative — generated schema types used manually — helps less than it appears to. A User type describes the whole object; your query may select three fields of it, and a variable's type says nothing about which arguments the operation accepts. Operation types (result plus variables) are what make client code verifiable.

Wiring the Generator

graphql-codegen is a plugin pipeline: inputs (schema + documents), a set of plugins that each emit TypeScript, and an output location. A configuration that fits most applications:

// codegen.ts
import { CodegenConfig } from '@graphql-codegen/cli';

const config: CodegenConfig = {
  // SDL file, not a live endpoint: CI never needs the server running
  schema: './schema/schema.graphql',
  documents: ['src/**/*.{ts,tsx}', 'src/**/*.graphql'],
  generates: {
    'src/gql/types.ts': { plugins: ['typescript'] },
    'src/gql/': {
      preset: 'near-operation-file',
      presetConfig: {
        extension: '.generated.ts',
        baseTypesPath: 'types.ts',
      },
      plugins: ['typescript-operations', 'typed-document-node'],
    },
  },
  scalars: {
    DateTime: 'Date',
    JSON: 'Record<string, unknown>',
  },
};
export default config;

What each piece is doing:

• schema supplies the type system. Pointing at the committed SDL (the artifact from introspection mechanics) keeps builds deterministic; pointing at a live URL works for local development but fails the moment introspection is disabled.
• documents is the glob over files containing operations — template literals tagged with graphql and standalone .graphql documents, fragments included. Forget this glob and you get schema types with no operation types, which looks like success until you try to import one.
• typescript emits the schema-side types (enums, inputs, object shapes). typescript-operations emits one result and variables type per operation, filtered to the fields you actually selected. typed-document-node binds the two to the document constant so the client library infers types without casts.
• scalars maps custom scalars to TypeScript. Without it, a custom DateTime becomes any and your date handling silently loses its type; with DateTime: 'Date' the generated field is a real Date.
• near-operation-file writes each operation's types next to the component that uses them, with one shared types.ts for schema-side definitions. The alternative — one giant output — is simpler until three teams merge generated files into the same path.

The result after graphql-codegen --config codegen.ts:

// src/gql/GetUser.generated.ts
export type GetUserQuery = { user: { id: string; fullName: string } | null };
export type GetUserQueryVariables = { id: string };
export const GetUserDocument: TypedDocumentNode<GetUserQuery, GetUserQueryVariables>;

Freshness: Keeping Generated Types Honest

Generated types are a compiler artifact of two inputs. Change the schema or the query and the artifact is wrong until someone regenerates — and stale types are worse than no types, because they turn "the compiler would have caught this" into "the compiler agreed with a lie."

The mechanical fix is a check, not a habit:

{
  "scripts": {
    "codegen": "graphql-codegen --config codegen.ts",
    "codegen:watch": "graphql-codegen --config codegen.ts --watch",
    "codegen:check": "graphql-codegen --config codegen.ts --check"
  }
}

--check generates into memory and compares against the files on disk: exit 0 when identical, exit 1 when anything is stale, nothing written. Run it in CI alongside the type check so a pull request that edits operations or schema without regenerating fails before review.

Two operational traps worth knowing before you trust it:

• Formatting hooks skew the comparison. If Prettier rewrites generated files after they hit disk (an afterOneFileWrite hook), the in-memory output never matches what --check compares. Run the formatter through codegen's beforeAllFileWrite hook as well, so both sides of the comparison are formatted the same way.
• Commit or ignore generated files — choose deliberately. Committing them means type errors show up in review diffs and downstream packages compile without running codegen, at the cost of occasional merge conflicts in generated paths. Ignoring them keeps the repo clean but makes every build dependent on a codegen step, and a missed step ships any. Most teams commit them and let --check enforce freshness.

Watch mode covers the local loop (codegen:watch in a second terminal), and a pre-commit hook running --check catches staleness before it reaches CI — useful when the build queue is slower than the habit you are trying to build.

Common failure modes, in the order they appear in real projects:

1. Schema types without operation types — the documents glob is wrong or the graphql tag import is missing from the file.
2. Fragments invisible to components — a shared fragment lives outside the glob, so operation types silently omit its fields.
3. Custom scalars typed as any — no scalars mapping; every date and money value loses its type at the boundary.
4. Two schemas, one config — monorepos need separate configs per schema; merging documents from different schemas produces types that satisfy neither.

Interview framing: the question is usually "what happens when the schema changes?" Answer with the loop — schema edit regenerates types, a stale selection becomes a compile error, CI's --check guarantees regeneration actually happened — and mention that operation types, not schema types, are what make client code provably correct.