Zum Hauptinhalt springen

GraphQL Codegen: So generierst du typensicheren Code aus einem GraphQL-Schema

Ein praxisnaher Guide zu GraphQL Code Generator: Setup und Konfiguration, generierte TypeScript-Typen und typisierte Document Nodes, Integration mit Apollo, urql und graphql-request sowie Automatisierung mit Watch-Mode und CI.
· 12 Min. lesen

Entdecke KI

Handgeschriebene TypeScript-Typen für eine GraphQL-API sind in dem Moment veraltet, in dem jemand das Schema ändert.

Angenommen, ein Backend-Developer benennt das Feld title im Typ Course in name um. Das Frontend kompiliert weiterhin, weil das manuell geschriebene Course-Interface nichts von der Änderung weiß – der Fehler taucht erst zur Laufzeit auf. In realen Anwendungen gibt es Dutzende Queries, Mutationen und Fragmente – du siehst, wie schnell das eskalieren kann.

GraphQL Code Generator – kurz GraphQL Codegen – liest dein Schema und deine GraphQL-Operationen und verwandelt sie in Typen, Query-Helper, Client-Integrationen und anderen Boilerplate-Code, den du sonst von Hand schreiben würdest. Am häufigsten nutzt man ihn mit TypeScript und beliebten Clients wie Apollo und urql. Mit einem Befehl bringst du deine Typen bei jeder Schema-Änderung wieder in Einklang.

In diesem Artikel zeige ich dir Schritt für Schritt, wie du GraphQL Codegen in einem kleinen TypeScript-Projekt einrichtest, konfigurierst, die generierten Typen nutzt und es automatisch in deinen Workflow einbindest.

Wie schneidet GraphQL im Vergleich zu REST ab? Lies unseren GraphQL vs REST: A Complete Guide und erfahre Unterschiede und Vorteile.

Was ist GraphQL Codegen?

GraphQL Codegen ist ein CLI-Tool, das GraphQL-Definitionen in Anwendungscode überführt.

Es ist ein Open-Source-Projekt von The Guild und wird als Dev-Dependency im Projekt installiert. Es verbindet drei Dinge:

  • GraphQL-Schema: Der Vertrag zwischen Server und Clients, mit allen Typen, Feldern und Argumenten, die die API bereitstellt
  • GraphQL-Operationen: Die Queries, Mutationen, Subscriptions und Fragmente, die deine Anwendung an die API sendet
  • Generierter Code: Die Typen und Helper, die Codegen basierend auf Schema und Operationen schreibt

Das Schema sagt Codegen, was möglich ist, und die Operationen sagen, was deine Anwendung anfragt.

Codegen kombiniert beides, sodass jeder generierte Typ exakt der Struktur der Antwort einer Operation entspricht. Es prüft außerdem jede Operation gegen das Schema. Das umbenannte Feld title aus der Einleitung würde die Generierung mit einem Fehler wie Cannot query field "title" on type "Course" stoppen – du fängst es ab, bevor der Code läuft.

Die Ausgabe hängt von deinen Plugins und der Konfiguration ab. Codegen selbst schreibt kein TypeScript – das machen die Plugins. Zum Beispiel generiert das Plugin typescript Schema-Typen, und typescript-operations erzeugt Typen für deine Queries und Mutationen. Es gibt auch Plugins für andere Sprachen wie Java und C#, aber dieser Artikel bleibt bei TypeScript.

Wichtig ist: Codegen ersetzt nicht deinen GraphQL-Server.

Es löst keine Queries und holt keine Daten. Es liest während der Entwicklung GraphQL-Definitionen und schreibt Dateien. Den Rest übernehmen dein Server und dein GraphQL-Client.

So funktioniert GraphQL Codegen

Jedes Codegen-Setup folgt demselben Ablauf: Schema + GraphQL-Operationen -> Codegen-Konfiguration -> generierter Code.

Diagramm des GraphQL-Codegen-Workflows

Diagramm des GraphQL-Codegen-Workflows

Die Idee in Kürze:

  1. Schema bereitstellen: Zeige Codegen eine lokale .graphql-Datei oder ein laufendes GraphQL-Endpoint, das Codegen per Introspection ausliest

  2. Codegen auf deine Operationen zeigen: Verwende Glob-Muster wie src/**/*.ts, damit Codegen Queries, Mutationen und Fragmente im Code findet

  3. Plugins und Ausgabepfade konfigurieren: Sage Codegen, welche Dateien es schreiben soll und welche Plugins jeweils zuständig sind

  4. Codegen ausführen: Führe npx graphql-codegen aus, um das Schema zu laden, deine Operationen zu validieren und die Ausgabe zu schreiben

  5. Generierte Artefakte verwenden: Importiere die generierten Typen und Document Nodes in deinen Anwendungscode

Die Schritte 1 bis 3 landen in einer einzigen Konfigurationsdatei, meist codegen.ts. Hier ist die kleinste Variante für ein Kurskatalog-Projekt:

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

const config: CodegenConfig = {
  // Step 1: Where the schema comes from
  schema: "schema.graphql",
  // Step 2: Where your operations are placed
  documents: ["src/**/*.ts"],
  // Step 3: What to generate and where to write it
  generates: {
    "./src/gql/": { preset: "client" },
  },
};

export default config;

Das Preset client ist ein Plugin-Bundle, das Schema-Typen, Operationstypen und typisierte Document Nodes in einem Rutsch erzeugt. Auf jedes davon gehe ich in Setup und Konfiguration ein.

GraphQL Codegen einrichten

Am besten verstehst du Codegen, wenn du es auf ein echtes Projekt anwendest.

In diesem Abschnitt baust du von Grund auf einen kleinen Kurskatalog. Es gibt ein Schema mit Courses und Instructors, eine Query und eine Codegen-Konfiguration, die die Query in TypeScript-Typen übersetzt. Du brauchst nur Node.js und npm.

Schritt 1: GraphQL Code Generator installieren

Erstelle einen neuen Ordner und initialisiere ein npm-Projekt:

mkdir course-catalog && cd course-catalog
npm init -y

Codegen benötigt ein paar Pakete. Zwei kommen in die regulären Abhängigkeiten, der Rest als Dev-Dependencies, weil sie nur während der Entwicklung laufen:

npm install graphql @graphql-typed-document-node/core
npm install -D typescript @graphql-codegen/cli @graphql-codegen/typescript-operations @graphql-codegen/typed-document-node

Dafür steht jedes Paket:

  • graphql: Die Referenzimplementierung von GraphQL für JavaScript, die Codegen zum Parsen von Schema und Operationen nutzt

  • @graphql-typed-document-node/core: Stellt den Typ TypedDocumentNode bereit, den dein generierter Code importiert

  • @graphql-codegen/cli: Das Codegen-Kommandozeilentool

  • @graphql-codegen/typescript-operations: Das Plugin, das Typen für deine Queries, Mutationen und Fragmente generiert

  • @graphql-codegen/typed-document-node: Das Plugin, das Dokumentobjekte mit angehängten Typen erzeugt

Schritt 2: Eine Konfigurationsdatei anlegen

Codegen liest seine Einstellungen aus einer Konfigurationsdatei im Projekt-Root. Erstelle codegen.ts mit einer leeren Konfiguration:

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

const config: CodegenConfig = {};

export default config;

Du kannst auch npx graphql-codegen init ausführen, ein paar Fragen beantworten und eine generierte Konfig bekommen. Ich schreibe sie hier von Hand, damit du siehst, was jede Einstellung bewirkt.

Schritt 3: Schema- und Dokumentpfade angeben

Codegen braucht zwei Eingaben – legen wir beide an.

Speichere zuerst das Schema als schema.graphql im Projekt-Root:

enum Level {
  BEGINNER
  INTERMEDIATE
  ADVANCED
}

type Instructor {
  id: ID!
  name: String!
  bio: String
}

type Course {
  id: ID!
  title: String!
  level: Level!
  durationHours: Int!
  instructor: Instructor!
}

type Enrollment {
  id: ID!
  course: Course!
  studentEmail: String!
}

type Query {
  courses(level: Level, limit: Int): [Course!]!
  course(id: ID!): Course
}

type Mutation {
  enrollStudent(courseId: ID!, studentEmail: String!): Enrollment!
}

Lege dann src/operations/courses.graphql mit einer Query an, die Kurse und ihre Instructors holt:

query GetCourses($level: Level, $limit: Int) {
  courses(level: $level, limit: $limit) {
    id
    title
    level
    instructor {
      name
    }
  }
}

Zeige Codegen jetzt beide Dateien. Der Schlüssel schema nimmt den Schema-Pfad, documents ein Glob-Muster für deine Operationen:

const config: CodegenConfig = {
  schema: "schema.graphql",
  documents: ["src/**/*.graphql"],
};

Schritt 4: Eine Ausgabedatei wählen

Der Schlüssel generates sagt Codegen, wohin die Ausgabe geschrieben wird. Jeder Key darin ist ein Dateipfad:

const config: CodegenConfig = {
  schema: "schema.graphql",
  documents: ["src/**/*.graphql"],
  generates: {
    "src/generated/graphql.ts": {},
  },
};

Codegen erstellt den Ordner src/generated/, falls er noch nicht existiert.

Schritt 5: Relevante Plugins hinzufügen

Eine Ausgabedatei ohne Plugins bleibt leer. Füge die beiden installierten Plugins hinzu:

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

const config: CodegenConfig = {
  schema: "schema.graphql",
  documents: ["src/**/*.graphql"],
  generates: {
    "src/generated/graphql.ts": {
      plugins: ["typescript-operations", "typed-document-node"],
    },
  },
};

export default config;

Wenn du einem älteren Tutorial gefolgt bist, hast du wahrscheinlich auch das Plugin typescript gesehen. Das kannst du hier weglassen: typescript-operations funktioniert allein und generiert nur Input-, Enum- und Operationstypen, die tatsächlich verwendet werden. Packst du aktuell beide in dieselbe Ausgabedatei, wirft TypeScript Fehler zu doppelten Deklarationen.

Schritt 6: Codegen ausführen

Lege ein npm-Script an, damit du dir den Befehl nicht merken musst:

npm pkg set scripts.codegen="graphql-codegen"

Und führe es aus:

npm run codegen

Codegen lädt das Schema, validiert die Query dagegen und schreibt die Ausgabe:

Ergebnis der Codegen-Generierung

Ergebnis der Codegen-Generierung

Verweist eine Operation auf ein Feld, das im Schema nicht existiert, schlägt der Lauf hier fehl, und es werden keine Dateien geschrieben.

Schritt 7: Die generierte Ausgabe prüfen

Öffne src/generated/graphql.ts. Das siehst du:

Die generierte Ausgabe

Codegen hat vier Dinge erzeugt:

  • Level: Eine String-Union für das Enum – nur generiert, weil die Query es nutzt

  • GetCoursesQueryVariables: Der Typ für die Variablen der Query – beide optional, weil das Schema sie nicht als erforderlich markiert

  • GetCoursesQuery: Die Form der Antwort – ausschließlich mit den Feldern, die die Query anfragt

  • GetCoursesDocument: Die geparste Query als typisierter Document Node – mit Ergebnis- und Variablentypen

Schau dir GetCoursesQuery noch einmal an. Es enthält weder durationHours noch die bio des Instructors, weil die Query sie nicht anfragt. Versuchst du in deinem Code course.durationHours zu lesen, gibt es einen Compile-Fehler statt ein undefined zur Laufzeit.

Und das war’s mit dem Setup: Du schreibst GraphQL – Codegen schreibt TypeScript.

GraphQL Codegen konfigurieren

Die meisten Codegen-Konfigurationen sind länger als oben, bauen aber auf denselben vier Einstellungen auf.

Die Konfigurationsdatei kann codegen.ts, codegen.yml oder codegen.json heißen. Ich nutze TypeScript, weil du Autovervollständigung und Typprüfungen für die Konfig selbst bekommst. Die Einstellungen sind in jedem Format gleich.

Schema

Der Schlüssel schema sagt Codegen, wo dein Schema liegt. Er akzeptiert mehrere Quellen.

Eine lokale Datei oder ein Glob-Muster funktioniert, wenn das Schema im Repo liegt:

schema: "schema.graphql",
// or, for a schema split across files
schema: "schema/**/*.graphql",

Eine URL funktioniert, wenn das Schema auf einem laufenden Server liegt. Codegen sendet eine Introspection-Query an das Endpoint, bei Bedarf mit Auth-Headern:

schema: [
  {
    "https://api.example.com/graphql": {
      headers: { Authorization: Bearer ${process.env.API_TOKEN} },
    },
  },
],

Die URL-Option funktioniert nur, wenn der Server Introspection aktiviert hat. Viele Produktions-APIs schalten sie ab – daher ist für CI eine ins Repo eingecheckte Schemadatei meist die verlässlichere Wahl.

Documents

Der Schlüssel documents sagt Codegen, wo Queries, Mutationen, Subscriptions und Fragmente liegen.

Operationen können in .graphql-Dateien stehen oder inline im TypeScript-Code. Codegen findet Inline-Operationen, wenn sie mit einem gql-Tag umschlossen oder mit einem Kommentar /* GraphQL */ markiert sind:

const EnrollStudent = /* GraphQL */ 
  mutation EnrollStudent($courseId: ID!, $studentEmail: String!) {
    enrollStudent(courseId: $courseId, studentEmail: $studentEmail) {
      id
      course {
        title
      }
    }
  }
;

Um beide Dateitypen zu scannen, erweitere das Glob-Muster. Füge ein Negativmuster hinzu, damit Codegen die eigene Ausgabe nicht scannt:

documents: ["src/**/*.{graphql,ts}", "!src/generated/**"],

Gib jeder Operation einen eindeutigen Namen. Codegen bildet Typnamen aus Operationsnamen – aus EnrollStudent werden EnrollStudentMutation und EnrollStudentMutationVariables.

Generates

Der Schlüssel generates ordnet Ausgabepfade dem Inhalt zu. Du kannst beliebig viele Ziele definieren, jedes mit eigenen Plugins.

Angenommen, du willst Operationstypen in einer Datei und die vollständigen Schema-Typen in einer anderen:

generates: {
  "src/generated/graphql.ts": {
    plugins: ["typescript-operations", "typed-document-node"],
    config: {
      useTypeImports: true,
    },
  },
  "src/generated/schema-types.ts": {
    plugins: ["typescript"],
  },
},

Das Objekt config innerhalb eines Ausgabesziels gilt nur für diese Datei. Hier sorgt useTypeImports dafür, dass import type verwendet wird – das ist in manchen Build-Setups erforderlich. Platzierst du config auf Root-Ebene, gilt es für alle Ausgaben.

Ein Ausgabepfad kann auch ein Ordner mit abschließendem Slash sein, z. B. "src/gql/". Das ist das Format, das Presets nutzen, da sie mehrere Dateien schreiben.

Plugins

Plugins entscheiden, was generiert wird. Codegen lädt Schema und Dokumente, und jedes Plugin macht daraus ein Stück Ausgabe.

Diese Plugins siehst du in TypeScript-Projekten am häufigsten:

  • typescript-operations: Typen für deine Queries, Mutationen, Subscriptions und Fragmente – plus die verwendeten Enums und Inputs

  • typed-document-node: Dokumentobjekte mit angehängten Ergebnis- und Variablentypen, die die meisten GraphQL-Clients verstehen

  • typescript: Typen für jedes Objekt, Enum und jeden Input im Schema – unabhängig davon, ob deine Operationen sie verwenden

  • typescript-resolvers: Typsignaturen für Resolver-Funktionen auf der Serverseite

Ein Preset ist ein Plugin-Bundle mit sinnvoller Standardkonfiguration. Das Preset client aus dem Abschnitt So funktioniert’s empfiehlt The Guild für Client-Apps. Es baut unter der Haube auf dem verbesserten typescript-operations auf – du bekommst die Vorteile ohne Extrakonfig.

Jedes Plugin hat viele eigene Optionen. Die musst du nicht auswendig lernen. Starte mit den Defaults und schau Optionen nach, wenn die Ausgabe nicht zu deinem Code passt.

Was kann GraphQL Codegen erzeugen?

Die Ausgabe hängt von den gewählten Plugins ab.

Das gleiche Schema und die gleichen Operationen können reine TypeScript-Typen oder fertigen Client-Code produzieren. Das sind die gängigsten Ausgaben.

TypeScript-Typen

Das Plugin typescript generiert für jedes Objekt, Enum und jeden Input in deinem Schema einen Typ. Für den Kurskatalog sieht Course so aus:

export type Course = {
  __typename?: 'Course';
  durationHours: Scalars['Int']['output'];
  id: Scalars['ID']['output'];
  instructor: Instructor;
  level: Level;
  title: Scalars['String']['output'];
};

Diese Typen beschreiben das komplette Schema – nützlich auf der Serverseite, in Test-Fixtures und in Utilities, die mit vollständigen Objekten arbeiten.

Für Client-Code passen sie weniger gut. Ein Course-Typ sagt, jedes Feld existiert – auch wenn deine Query es nie angefragt hat.

Operationstypen

Das Plugin typescript-operations erzeugt pro Operation zwei Typen: einen für das Ergebnis und einen für die Variablen. Das funktioniert für Queries und Subscriptions gleich.

So sieht es für die Mutation EnrollStudent aus:

export type EnrollStudentMutationVariables = Exact<{
  courseId: string | number;
  studentEmail: string;
}>;

export type EnrollStudentMutation = { enrollStudent: { id: string, course: { title: string } } };

Der Ergebnistyp entspricht eins zu eins dem Selection Set. Der Variablentyp ist Exact, wodurch TypeScript zusätzliche oder falsch geschriebene Variablen ablehnt.

Die Variable courseId akzeptiert string und number, weil der GraphQL-Scalar ID beides als Input annimmt. Seit v6 ist der Default-Typ string | number – korrekt für Client-Fälle.

Typisierte Document Nodes

Ein regulärer DocumentNode ist eine geparste GraphQL-Query. Er kennt die Struktur, aber nicht, was die Query zurückgibt oder welche Variablen sie erwartet.

Typisierte Document Nodes enthalten beides. Das Plugin typed-document-node generiert pro Operation einen solchen Knoten:

export const GetCoursesDocument = { /* ... */ } as unknown as DocumentNode<GetCoursesQuery, GetCoursesQueryVariables>;

So können Funktionen, die einen TypedDocumentNode annehmen, Ergebnis- und Variablentypen direkt aus dem Dokument ableiten. Du musst keine Generics von Hand übergeben und kannst keine Query mit falschen Typen kombinieren.

Die meisten modernen GraphQL-Clients verstehen typisierte Document Nodes – darunter Apollo Client, urql und graphql-request. Später im Artikel siehst du alle drei im Einsatz.

Client-spezifische Integrationen

Manche Plugins gehen weiter und erzeugen Code für einen bestimmten Client oder ein Framework. Zum Beispiel:

  • typescript-react-apollo: Generiert typisierte React-Hooks für Apollo Client

  • typescript-urql: Generiert typisierte Hooks und Komponenten für urql

  • typescript-react-query: Generiert typisierte Hooks für TanStack Query

  • typescript-graphql-request: Generiert ein typisiertes SDK mit einer Funktion pro Operation

All das sind Community-Plugins. The Guild hat sie in ein separates Community-Repository verschoben – ihr Release-Takt unterscheidet sich von den Core-Plugins.

Und du brauchst sie heute seltener. Wenn ein Client typisierte Document Nodes unterstützt, bringen generierte Hooks wenig zusätzliche Typsicherheit. Apollo empfiehlt zum Beispiel selbst das Plugin typescript-operations, das sich auf Typen konzentriert und keinen zusätzlichen Runtime-Code erzeugt.

Grundsätzlich solltest du mit Operationstypen und typisierten Document Nodes starten. Füge ein client-spezifisches Plugin nur hinzu, wenn dein Team die generierten Hooks oder SDK-Funktionen wirklich nutzen will.

GraphQL Codegen mit TypeScript

Generierte Typen bringen nur etwas, wenn sie Fehler auch aufdecken – also machen wir welche.

Dieses Beispiel erweitert das Kurskatalog-Projekt um eine zweite Query, einen kleinen Helper, der sie an die API sendet, und den Code, der das Ergebnis nutzt. Es setzt einen GraphQL-Server voraus, der das Schema unter http://localhost:4000/graphql bereitstellt.

Hier ist der Schema-Ausschnitt, den wir nutzen:

type Instructor {
  id: ID!
  name: String!
  bio: String
}

type Course {
  id: ID!
  title: String!
  level: Level!
  durationHours: Int!
  instructor: Instructor!
}

type Query {
  course(id: ID!): Course
}

Zwei Details sind wichtig: Das Feld course gibt Course ohne ! zurück – also null, wenn keine ID passt. Die bio des Instructors ist ebenfalls nullable.

Erstelle src/operations/course.graphql mit einer Query für einen Kurs:

query GetCourse($id: ID!) {
  course(id: $id) {
    title
    durationHours
    instructor {
      name
      bio
    }
  }
}

Führe erneut npm run codegen aus. Codegen ergänzt zwei neue Typen in src/generated/graphql.ts:

Inhalt der Datei graphql.ts

Die Nullbarkeit aus dem Schema bleibt erhalten. course kann null sein, bio kann null sein, und id ist erforderlich, weil die Query es als ID! deklariert.

Nun zum Anwendungscode. Erstelle src/execute.ts – ein Helper, der jeden typisierten Document an die API sendet:

import { print } from "graphql";
import type { TypedDocumentNode } from "@graphql-typed-document-node/core";

const API_URL = "http://localhost:4000/graphql";

export async function execute<TResult, TVariables>(
  document: TypedDocumentNode<TResult, TVariables>,
  variables: TVariables,
): Promise<TResult> {
  const response = await fetch(API_URL, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ query: print(document), variables }),
  });
  const { data, errors } = await response.json();
  if (errors?.length) {
    throw new Error(errors[0].message);
  }
  return data as TResult;
}

Der Helper weiß nichts über Kurse. Er bekommt beide Typen aus dem übergebenen Dokument, und print() wandelt es für die Anfrage wieder in einen Query-String.

Nutze ihn in src/course-details.ts:

import { execute } from "./execute";
import { GetCourseDocument, type GetCourseQuery } from "./generated/graphql";

function formatCourse(course: NonNullable<GetCourseQuery["course"]>): string {
  const bio = course.instructor.bio ?? "No bio yet";
  return course.title({course.durationHours}h) by ${course.instructor.name} - ${bio};
}

const { course } = await execute(GetCourseDocument, { id: "c1" });

if (course) {
  console.log(formatCourse(course));
} else {
  console.log("Course not found");
}

Die Funktion formatCourse() erhält ihren Parametertyp aus dem generierten Query-Typ. NonNullable entfernt den null-Fall, weil die Funktion erst nach dem if-Check läuft.

Das Beispiel nutzt Top-Level-await. Setze daher "type": "module" in package.json und starte es mit npx tsx src/course-details.ts:

Erfolgreicher Aufruf eines GraphQL-Mock-Servers

Erfolgreicher Aufruf eines GraphQL-Mock-Servers

Das setzt einen laufenden GraphQL-Server voraus. Hier ist der Mock-Server, den ich genutzt habe:

import { createServer } from "node:http";
import { readFileSync } from "node:fs";
import { createSchema, createYoga } from "graphql-yoga";

const instructors = [{ id: "i1", name: "Dario Radecic", bio: "Developer" }];

const courses = [
  { id: "c1", title: "Intro to GraphQL", level: "BEGINNER", durationHours: 4, instructor: instructors[0] },
  { id: "c2", title: "GraphQL Schema Design", level: "ADVANCED", durationHours: 6, instructor: instructors[0] },
];

const schema = createSchema({
  typeDefs: readFileSync("schema.graphql", "utf8"),
  resolvers: {
    Query: {
      courses: (_: unknown, args: { level?: string; limit?: number }) =>
        courses
          .filter((course) => !args.level || course.level === args.level)
          .slice(0, args.limit ?? undefined),
      course: (_: unknown, args: { id: string }) =>
        courses.find((course) => course.id === args.id) ?? null,
    },
    Mutation: {
      enrollStudent: (_: unknown, args: { courseId: string; studentEmail: string }) => ({
        id: "e1",
        course: courses.find((course) => course.id === args.courseId),
        studentEmail: args.studentEmail,
      }),
    },
  },
});

createServer(createYoga({ schema })).listen(4000, () => {
  console.log("Mock API running at http://localhost:4000/graphql");
});

Jetzt brechen wir es gezielt. Öffne src/course-details.ts und ersetze alles unterhalb der Funktion formatCourse() durch drei typische Fehler, die handgeschriebene Typen oft durchlassen:

// Missing the required id variable
await execute(GetCourseDocument, {});

const { course } = await execute(GetCourseDocument, { id: "c1" });

// Reading a field the query doesn't request
console.log(course?.level);

// Forgetting that course can be null
console.log(course.title);

Dann führe die Typprüfung aus:

npx tsc -p .

TypeScript fängt alle drei Fehler ab, bevor der Code läuft:

Von TypeScript erkannte Fehler

Von TypeScript erkannte Fehler

So reduziert Codegen Fehlanpassungen zwischen Frontend und API. Die Typen kommen aus demselben Schema wie der Server – sie können keine Felder beschreiben, die es nicht gibt, und keine möglichen Nulls übersehen.

Und der Schutz endet nicht nach dem ersten Lauf. Macht das Backend-Team durationHours nullable, regenerierst du – der Typ wird zu number | null, und TypeScript markiert jede Stelle, die eine Zahl vorausgesetzt hat.

GraphQL Codegen mit GraphQL-Clients

Codegen sendet keine Anfragen – das übernimmt dein GraphQL-Client.

Die generierten typisierten Document Nodes sind die Übergabe zwischen beiden. Du gibst sie an den Client, und der leitet die Typen her. Die folgenden Beispiele nutzen die gleiche Datei src/generated/graphql.ts und die Mock-API aus dem letzten Abschnitt – lass npx tsx mock/server.ts in einem separaten Terminal laufen.

GraphQL Codegen mit Apollo

Installiere Apollo Client und seine Peer-Dependency rxjs:

npm install @apollo/client rxjs

Das Beispiel führt außerdem die Mutation EnrollStudent aus. Speichere sie als src/operations/enroll.graphql:

mutation EnrollStudent($courseId: ID!, $studentEmail: String!) {
  enrollStudent(courseId: $courseId, studentEmail: $studentEmail) {
    id
    course {
      title
    }
  }
}

Apollo empfiehlt in der Doku zwei Codegen-Optionen, da Apollo Client immer __typename-Felder einfügt, sie aber nicht zu Root-Typen ergänzt. Füge sie im Ausgabziel in codegen.ts hinzu:

"src/generated/graphql.ts": {
  plugins: ["typescript-operations", "typed-document-node"],
  config: {
    nonOptionalTypename: true,
    skipTypeNameForRoot: true,
  },
},

Damit bekommt jedes Objekt in den generierten Ergebnistypen ein Pflichtfeld __typename, etwa __typename: 'Course'. Das entspricht dem, was Apollos Cache zurückliefert.

Führe npm run codegen erneut aus, damit die neue Mutation und Config erkannt werden.

Apollo Client akzeptiert typisierte Document Nodes in query() und mutate(). Speichere das als src/apollo.ts:

import { ApolloClient, HttpLink, InMemoryCache } from "@apollo/client";
import { EnrollStudentDocument, GetCoursesDocument } from "./generated/graphql";

const client = new ApolloClient({
  link: new HttpLink({ uri: "http://localhost:4000/graphql" }),
  cache: new InMemoryCache(),
});

const { data } = await client.query({
  query: GetCoursesDocument,
  variables: { level: "BEGINNER", limit: 5 },
});

data?.courses.forEach((course) => console.log(course.title));

const result = await client.mutate({
  mutation: EnrollStudentDocument,
  variables: { courseId: "c1", studentEmail: "[email protected]" },
});

console.log(result.data?.enrollStudent.course.title);

Das Objekt data ist als GetCoursesQuery | undefined typisiert, und TypeScript prüft variables gegen GetCoursesQueryVariables. Die Mutation funktioniert analog mit EnrollStudentMutation und den zugehörigen Variablen.

Starte es mit npx tsx src/apollo.ts:

Apollo-Ausgabe

Apollo-Ausgabe

Die erste Zeile kommt von der Query (es gibt nur einen Einsteigerkurs). Die zweite von der Mutation, die den Kurstitel des eingeschriebenen Studenten zurückgibt.

Die React-Hooks wie useQuery() und useMutation() leiten die Typen aus typisierten Document Nodes genauso ab.

GraphQL Codegen mit urql

Installiere das urql-Core-Paket:

npm install @urql/core

urql funktioniert out of the box mit typisierten Document Nodes. Übergib das Dokument als erstes Argument an query() in src/urql.ts:

import { Client, cacheExchange, fetchExchange } from "@urql/core";
import { GetCoursesDocument } from "./generated/graphql";

const client = new Client({
  url: "http://localhost:4000/graphql",
  exchanges: [cacheExchange, fetchExchange],
});

const result = await client
  .query(GetCoursesDocument, { level: "ADVANCED" })
  .toPromise();

if (result.error) {
  throw result.error;
}

result.data?.courses.forEach((course) => console.log(course.title));

Das zweite Argument ist als Variablentyp der Query typisiert, und result.data ist als Ergebnis der Query typisiert.

Starte es mit npx tsx src/urql.ts:

urql-Ausgabe

Urql-Ausgabe

Die Framework-Bindings, z. B. useQuery() im urql-Paket für React, akzeptieren ebenfalls typisierte Document Nodes.

GraphQL Codegen mit anderen Clients

Du brauchst keinen ausgewachsenen Client, um typisierte Ergebnisse zu erhalten.

Der Client graphql-request sendet minimalistisch eine Anfrage und gibt die Daten zurück. Installiere ihn so:

npm install graphql-request

Er leitet Typen aus typisierten Document Nodes genau wie Apollo und urql her. Speichere das als src/graphql-request.ts:

import { request } from "graphql-request";
import { GetCourseDocument } from "./generated/graphql";

const { course } = await request(
  "http://localhost:4000/graphql",
  GetCourseDocument,
  { id: "c2" },
);

console.log(course?.title);

Starte es mit npx tsx src/graphql-request.ts:

Ausgabe von graphql-request

Ausgabe von graphql-request

Das gleiche Prinzip funktioniert mit TanStack Query. Es sendet selbst keine GraphQL-Anfragen, daher rufst du innerhalb der Query-Funktion graphql-request oder den Helper execute() aus dem vorherigen Abschnitt auf – der Ergebnistyp fließt in deinen Code durch.

Und falls dein Client keine typisierten Document Nodes unterstützt, kannst du immer noch die reinen Operationstypen nutzen. Importiere GetCourseQuery und GetCourseQueryVariables und übergib sie als Generics. Das ist etwas manueller, aber die Typen stammen weiterhin aus dem Schema.

GraphQL Codegen automatisch ausführen

Generierte Typen helfen nur, wenn sie zum aktuellen Schema und zu den Operationen passen.

Vergisst du, Codegen nach einer Änderung erneut auszuführen, beschreiben die Typen Code, den es so nicht mehr gibt. Das ist das gleiche Drift-Problem wie bei handgeschriebenen Typen – nur mit Extra-Schritt. Die Lösung: Den manuellen Schritt aus dem Workflow entfernen.

npm-Skripte

Starte mit ein paar Skripten in package.json, damit alle im Team Codegen gleich ausführen:

{
  "scripts": {
    "codegen": "graphql-codegen",
    "codegen:watch": "graphql-codegen --watch",
    "codegen:check": "graphql-codegen --check",
    "prebuild": "npm run codegen",
    "build": "tsc -p ."
  }
}

Im Folgenden siehst du, wofür welches Skript da ist.

Watch-Mode

Der Watch-Mode führt Codegen bei jeder Änderung an überwachten Dateien erneut aus. Er benötigt das Paket @parcel/watcher, das Codegen nicht automatisch installiert:

npm install -D @parcel/watcher
npm run codegen:watch

Ohne Installation läuft Codegen einmal und meldet Failed to import @parcel/watcher statt zu beobachten.

Der Watch-Mode verfolgt sowohl deine Operationen als auch eine lokale Schemadatei. Fügst du course.graphql ein Feld hinzu, taucht es Sekunden später in GetCourseQuery auf. Machst du durationHours in schema.graphql nullable, wird der Typ zu number | null, und dein Editor markiert alle Stellen, die eine Zahl erwartet haben.

Lass ihn während der Entwicklung in einem Terminal neben deinem Dev-Server laufen.

Vor dem Build generieren

npm führt ein Skript namens prebuild vor build aus. Mit den obigen Skripten regeneriert npm run build zuerst die Typen und startet erst dann den TypeScript-Compiler.

So läuft ein Build nie mit veralteten Typen – selbst wenn jemand nach dem Pull nicht regeneriert hat.

CI/CD

Der Flag --check startet Codegen im Dry-Run. Es werden keine Dateien geschrieben – stattdessen vergleicht Codegen die zukünftige Ausgabe mit dem, was auf der Platte liegt, und beendet sich mit Code 1, wenn etwas abweicht.

Ein minimales GitHub-Actions-Workflow dafür:

name: CI

on: [push, pull_request]

jobs:
  typecheck:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 24
      - run: npm ci
      - run: npm run codegen:check
      - run: npm run build

Der Schritt codegen:check ergibt nur Sinn, wenn ihr generierte Dateien eincheckt. Wenn nicht, lass ihn weg – npm run build generiert ohnehin alles über den prebuild-Hook.

Bei Schema-Änderungen regenerieren

Operationen ändern sich in deinem Repo – Watch-Mode und prebuild decken sie ab. Schema-Änderungen sind schwieriger, weil sie oft aus einem anderen Team kommen.

Wie du damit umgehst, hängt vom Ort des Schemas ab:

  • Schemadatei im gleichen Repo: Watch-Mode und CI greifen Änderungen auf – das ist am einfachsten
  • Schema per URL: Codegen holt bei jedem Lauf die neueste Version – codegen:check schlägt in der CI fehl, sobald das Server-Schema nicht mehr zur eingecheckten Ausgabe passt
  • Schema aus einem anderen Repo: Kopiere oder lade es im Build und führe Codegen auf der lokalen Kopie aus

Ein Haken bei der URL-Option: Der Watch-Mode reagiert auf Dateisystem-Änderungen – Remote-Änderungen am Schema bemerkt er nicht. Du siehst sie erst beim nächsten manuellen Lauf oder im CI-Job.

GraphQL Codegen vs. handgeschriebene Typen

Beide Ansätze liefern TypeScript-Typen für GraphQL-Daten – die Unterschiede solltest du kennen.

Handgeschriebene Typen

Bei handgeschriebenen Typen liest du das Schema und schreibst passende Interfaces selbst.

Das gibt dir volle Kontrolle. Du kannst Typen frei benennen, mehrere Operationen in einem gemeinsamen Typ bündeln oder Hilfstypen ergänzen, die es im Schema nicht gibt.

Aber es ist Handarbeit. Jedes neue Feld oder umbenannte Argument bedeutet: passenden Typ finden und anpassen. Und es warnt dich niemand, wenn du etwas übersiehst.

So entsteht Drift. Das Interface Course aus der Einleitung kompilierte weiter, nachdem das Backend title umbenannt hatte – TypeScript prüft nur deinen Code gegen deine Typen, nicht gegen die API.

Generierte Typen

Generierte Typen kommen aus demselben Schema wie der Server – sie sind per Design synchron mit deinen GraphQL-Definitionen. Eine Schema-Änderung plus ein Codegen-Lauf aktualisiert alle betroffenen Typen auf einmal.

Du schreibst außerdem deutlich weniger Code. Das Kurskatalog-Projekt hat drei Operationen und null handgeschriebene Typen dafür.

Und du bekommst Schema-Driven Development fast gratis: Schema oder Operation ändern, regenerieren – und der Compiler zeigt dir alle Stellen, die angepasst werden müssen.

Wichtig bleibt: Codegen spiegelt nur das wider, was du vorgibst.

Wenn im Schema jedes Feld nullable ist, sind deine generierten Typen voll mit | null. Holt eine Operation 40 Felder, obwohl die Seite fünf braucht, hat der generierte Typ 40 Felder.

Hier die Unterschiede im Überblick:

 Handgeschriebene TypenGenerierte Typen
PflegeaufwandManuell bei jeder Schema-ÄnderungEin Befehl nach jeder Änderung
Schema-DriftMöglich und unbemerktBei Generierung oder Kompilierung erkannt
BoilerplateWächst mit jeder OperationKeiner von Hand
Kontrolle über Custom-TypenVollBegrenzt auf Plugin-Optionen
Schema-Driven DevelopmentManuelles AbgleichenCompiler zeigt jede betroffene Zeile

Codegen im Vergleich zu handgeschriebenen Typen

GraphQL Codegen vs. GraphQL-Introspection

Beides wird oft verwechselt, weil Codegen häufig Introspection nutzt. Trotzdem lösen sie unterschiedliche Aufgaben.

Introspection ist eine Funktion der GraphQL-Spezifikation. Jeder GraphQL-Server kann über spezielle Felder wie __schema und __type Anfragen zu seinem eigenen Schema beantworten. Das Ergebnis ist eine JSON-Beschreibung aller Typen, Felder und Argumente der API.

Einfach gesagt: Introspection beantwortet die Frage „Wie sieht diese API aus?“

Codegen beantwortet die Frage „Welchen Code braucht meine Anwendung?“. Es nimmt Schema-Informationen und deine Operationen und schreibt TypeScript-Typen und typisierte Document Nodes.

Wenn du schema in codegen.ts auf eine URL setzt, sendet Codegen eine Introspection-Query an diesen Server, um das Schema zu holen. Bei einer lokalen .graphql-Datei passiert keine Introspection.

Codegen kann auch ein Introspection-Ergebnis erzeugen. Das Plugin @graphql-codegen/introspection schreibt das Schema als Introspection-JSON, das einige Tools – etwa urqls Graphcache – für schema-bewusstes Caching nutzen.

 IntrospectionGraphQL Codegen
Was es istEingebautes GraphQL-AbfragesystemCLI-Tool und Plugins
EingabeEine Query an einen laufenden ServerEin Schema und deine Operationen
AusgabeJSON-Beschreibung des SchemasTypen, Document Nodes, Client-Code
Wann es läuftImmer wenn ein Client den Server fragtWährend Entwicklung, Builds und CI

Codegen im Vergleich zur Introspection

Häufige Probleme mit GraphQL Codegen

Die meisten Codegen-Fehler lassen sich auf vier Ursachen zurückführen.

Generierte Typen fehlen

Codegen läuft ohne Fehler durch, aber der erwartete Typ steht nicht in der Ausgabedatei.

Prüfe diese drei Punkte der Reihe nach:

  • Schema: Wenn der Typ im von Codegen geladenen Schema nicht existiert, kann er nicht generiert werden. Öffne die Schemadatei oder führe die Introspection-Query selbst aus und überprüfe, ob er vorhanden ist.

  • Dokumente: Operationstypen existieren nur für Operationen, die Codegen gefunden hat. Passt das documents-Glob nicht zu deiner Query-Datei, fehlen deren Typen.

  • Plugins: Seit v6 generiert typescript-operations nur noch Enums und Inputs, die deine Operationen verwenden. Wenn du einen vollständigen Schema-Typ wie Course brauchst, füge das Plugin typescript in einer separaten Ausgabedatei hinzu.

Wenn du ein nicht installiertes Plugin verwendest, bricht Codegen mit einer klaren Meldung ab:

Unable to find template plugin matching 'typescript-react-apollo'
Install one of the following packages:
- @graphql-codegen/typescript-react-apollo

Codegen findet keine Operationen

Dieser Fehler bedeutet, dass das documents-Glob keine Datei mit einer Operation gefunden hat:

Unable to find any GraphQL type definitions for the following pointers:
  - src/**/*.gql

Prüfe, ob die Erweiterung im Glob zu deinen Dateien passt. Ein Muster .gql findet keine .graphql-Dateien und src/**/*.graphql findet keine Inline-Operationen in .ts-Dateien.

Bei Inline-Operationen prüfe auch das Tag. Codegen findet nur Template-Literals, die in gql eingeschlossen oder mit /* GraphQL */ markiert sind. Ein einfaches Template-String mit Query ist unsichtbar.

Wenn du ignoreNoDocuments: true setzt, zeigt Codegen diesen Fehler nicht an und generiert eine Ausgabe ohne Operationstypen. In ganz neuen Projekten ist das hilfreich, später kann es ein kaputtes Glob verbergen.

Generierte Typen sind veraltet

Die Typen kompilieren, spiegeln aber nicht die letzte Änderung an Operation oder Schema wider.

Codegen läuft nicht von allein. Führe es nach jeder Änderung an einer .graphql-Datei, einer Inline-Operation, dem Schema oder codegen.ts erneut aus. Im Alltag erledigt npm run codegen:watch das für dich.

Sind die Typen in der CI veraltet, dann checke die generierten Dateien ein oder lass sie über den prebuild-Hook vor dem Build regenerieren.

Generierte Typen passen nicht zur API

Die Typen kompilieren, aber die Serverdaten haben zur Laufzeit eine andere Form.

Fast immer sprechen Codegen und App mit unterschiedlichen Schemata. Beispiel: Codegen liest ein lokales, eine Woche altes schema.graphql, während die App eine Produktions-API aufruft, die sich inzwischen geändert hat.

Prüfe, wohin schema zeigt. Wenn es eine Datei ist, vergleiche sie mit der API deiner App und aktualisiere sie. Wenn es eine URL ist, stelle sicher, dass sie der gleichen Umgebung wie deine App entspricht – nicht ein Staging-Server mit anderem Schema.

Regeneriere danach und schau dir den Diff an. Hat sich eine Operationsdatei geändert, aber die generierte Datei nicht, liegt die Operation wahrscheinlich außerhalb des documents-Globs.

Best Practices für GraphQL Codegen

Codegen braucht nicht viel Konfiguration, um gut zu funktionieren. Diese Praktiken halten es auch bei wachsendem Projektumfang schlank:

  • Schema und generierte Dateien synchron halten: Nutze den Watch-Mode in der Entwicklung und prebuild vor Builds, damit niemand mit alten Typen arbeitet

  • Operationsspezifische Typen generieren: Nutze typescript-operations für Client-Code, weil die Typen exakt dem entsprechen, was jede Query holt

  • Generierte Dateien nur committen, wenn euer Workflow es braucht: Commits erlauben Code-Reviews von Typänderungen und --check in der CI. Wenn ihr das nicht braucht, setzt den Ausgabeordner in die .gitignore und generiert bei jedem Build neu.

  • Konfiguration kurz halten: Eine Ausgabedatei mit zwei Plugins deckt die meisten Client-Projekte ab – jede zusätzliche Option ist etwas, das die nächste Person zuerst verstehen muss

  • Codegen in der CI bei jedem Push laufen lassen: Ein --check-Schritt oder ein prebuild-Hook fängt vergessene lokale Läufe ab

  • Generierte Dateien nie von Hand ändern: Der nächste Codegen-Lauf überschreibt Änderungen – passe stattdessen Schema, Operation oder Konfiguration an

Fazit

GraphQL Codegen übernimmt den repetitivsten Teil der GraphQL-Entwicklung – das manuelle Übersetzen von Schemas und Operationen in TypeScript-Typen.

Der Workflow bleibt gleich, egal wie groß das Projekt wird: Du definierst Schema und Operationen, konfigurierst Codegen, generierst Typen und typisierte Document Nodes und importierst sie in deinen Anwendungscode.

Der größte Mehrwert: Deine Typen beschreiben immer die API, die du tatsächlich aufrufst – nicht Code, den du nicht mehr schreiben musst. Ändert sich das Schema, sagt dir der Compiler, was bricht – so fängst du Fehler früh ab.

Wenn du lernen willst, wie GraphQL in einer modernen NoSQL-Datenbank eingesetzt wird, lies unseren MongoDB and GraphQL-Blogpost.

Dario Radečić

Autor

Dario Radečić

Senior Data Scientist mit Sitz in Kroatien. Top Tech Writer mit über 700 veröffentlichten Artikeln, die mehr als 10 Millionen Mal aufgerufen wurden. Buchautor von Machine Learning Automation with TPOT.

GraphQL Codegen FAQs

Wofür wird GraphQL Codegen verwendet?

GraphQL Codegen erzeugt Code aus einem GraphQL-Schema und deinen GraphQL-Operationen. Die meisten Teams nutzen es, um TypeScript-Typen und typisierte Document Nodes für ihre Queries und Mutationen zu erhalten – ohne diese Typen von Hand schreiben und pflegen zu müssen. Es kann auch Resolver-Typen für Server und fertige Hooks für bestimmte Clients generieren.

Brauche ich einen laufenden GraphQL-Server für Codegen?

Nein. Codegen kann das Schema aus einer lokalen .graphql-Datei lesen und funktioniert daher ohne Server. Du brauchst nur dann einen laufenden Server, wenn du den Schlüssel schema auf eine URL setzt – dann holt Codegen das Schema per Introspection.

Sollte ich generierte Dateien in Git committen?

Das hängt von eurem Workflow ab. EingecHECKte Dateien erlauben Code-Reviews von Typänderungen in Pull Requests und die Nutzung von graphql-codegen --check in der CI, um veraltete Ausgaben zu erkennen. Wenn ihr das nicht braucht, setzt den Ausgabeordner in die .gitignore und generiert die Dateien vor jedem Build neu.

Sollte ich das Client-Preset oder einzelne Plugins verwenden?

The Guild empfiehlt für die meisten Client-Apps das Client-Preset, weil es Operationstypen, typisierte Document Nodes und Fragment Masking in einem Setup bündelt. Apollo empfiehlt stattdessen das Plugin typescript-operations, weil das Preset Runtime-Code und Features mitbringt, die mit Apollo Client kollidieren. Wenn du Apollo nutzt, nimm die Plugins. Andernfalls ist das Preset eine gute Wahl.

Warum bekomme ich nach einem Codegen-Update Fehler zu doppelten Deklarationen?

Seit v6 generiert das Plugin typescript-operations eigene Enum- und Input-Typen. Wenn deine Konfig weiterhin typescript und typescript-operations für dieselbe Ausgabedatei listet, deklarieren beide Plugins Typen wie Level – TypeScript meldet doppelte Deklarationen. Entferne das Plugin typescript aus dieser Ausgabe – oder verschiebe es in eine separate Datei, wenn du vollständige Schema-Typen weiterhin brauchst.