Typed operations with GraphQL Codegen

This chapter follows Getting started with urql.

String queries in components drift from the schema silently. GraphQL Code Generator reads your schema and operation documents, then emits TypeScript that tracks field types through refactors.

Install

1
pnpm add -D @graphql-codegen/cli @graphql-codegen/client-preset
2
pnpm add graphql

Point the schema at your NestJS schema.gql, introspection URL, or a checked-in SDL file.

Configure codegen.ts

1
import type { CodegenConfig } from "@graphql-codegen/cli";
2

3
const config: CodegenConfig = {
4
  schema: "http://localhost:3000/graphql",
5
  documents: ["src/**/*.graphql"],
6
  ignoreNoDocuments: true,
7
  generates: {
8
    "./src/gql/": {
9
      preset: "client",
10
      presetConfig: {
11
        fragmentMasking: { unmaskFunctionName: "getFragmentData" },
12
      },
13
      config: {
14
        useTypeImports: true,
15
      },
16
    },
17
  },
18
};
19

20
export default config;

Add a script:

1
"scripts": {
2
  "codegen": "graphql-codegen --config codegen.ts",
3
  "codegen:watch": "graphql-codegen --config codegen.ts --watch"
4
}

Run pnpm codegen whenever schema or documents change; use watch during development.

Write operations in .graphql files

1
query Books {
2
  books {
3
    id
4
    title
5
  }
6
}
7

8
mutation CreateBook($input: CreateBookInput!) {
9
  createBook(input: $input) {
10
    id
11
    title
12
  }
13
}

The client preset emits the graphql() function and typed document constants—no separate @graphql-codegen/typescript-urql plugin is required when you call urql with generated documents.

Use generated documents with urql

1
import { useQuery } from "urql";
2
import { graphql } from "../../gql";
3

4
const BooksDocument = graphql(`
5
  query Books {
6
    books {
7
      id
8
      title
9
    }
10
  }
11
`);
12

13
export function BooksList() {
14
  const [result] = useQuery({ query: BooksDocument });
15
  // result.data is typed
16
}

Import graphql only from the generated folder so the compiler validates operations.

Fragment masking

Colocate fragments and unwrap them with FragmentType and getFragmentData (or your configured unmask name):

1
fragment BookSummary on Book {
2
  id
3
  title
4
}

1
import { type FragmentType, getFragmentData } from "../../gql";
2
import { graphql } from "../../gql";
3

4
const BookSummaryFragment = graphql(`
5
  fragment BookSummary on Book {
6
    id
7
    title
8
  }
9
`);
10

11
type Props = { book: FragmentType<typeof BookSummaryFragment> };
12

13
export function BookCard({ book }: Props) {
14
  const data = getFragmentData(BookSummaryFragment, book);
15
  return <span>{data.title}</span>;
16
}

Masking prevents parent components from relying on fields they did not spread.

Persisted documents (optional)

For trusted documents / APQ-style allowlists, add a plugin output that hashes operations:

1
generates: {
2
  "./src/gql/": { preset: "client" },
3
  "./persisted-documents.json": {
4
    plugins: ["persisted-operations"],
5
  },
6
}

Upload hashes to the gateway so only known operations execute in production—a security pattern covered later in this series.

Next: Normalized caching with urql Graphcache.