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.
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.
Schema bereitstellen: Zeige Codegen eine lokale .graphql-Datei oder ein laufendes GraphQL-Endpoint, das Codegen per Introspection ausliest
Codegen auf deine Operationen zeigen: Verwende Glob-Muster wie src/**/*.ts, damit Codegen Queries, Mutationen und Fragmente im Code findet
Plugins und Ausgabepfade konfigurieren: Sage Codegen, welche Dateien es schreiben soll und welche Plugins jeweils zuständig sind
Codegen ausführen: Führe npx graphql-codegen aus, um das Schema zu laden, deine Operationen zu validieren und die Ausgabe zu schreiben
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:
importtype{ 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"},},};exportdefault config;Bereitgestellt von
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:
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:
npminstall graphql @graphql-typed-document-node/core
npminstall-D typescript @graphql-codegen/cli @graphql-codegen/typescript-operations @graphql-codegen/typed-document-nodeBereitgestellt von
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:
importtype{ CodegenConfig }from"@graphql-codegen/cli";const config: CodegenConfig ={};exportdefault config;Bereitgestellt von
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:
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:
Codegen lädt das Schema, validiert die Query dagegen und schreibt die Ausgabe:
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",Bereitgestellt von
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}},},},],Bereitgestellt von
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
}}};Bereitgestellt von
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/**"],Bereitgestellt von
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"],},},Bereitgestellt von
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:
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:
exporttypeEnrollStudentMutationVariables= Exact<{
courseId:string|number;
studentEmail:string;}>;exporttypeEnrollStudentMutation={ enrollStudent:{ id:string, course:{ title:string}}};Bereitgestellt von
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:
exportconst GetCoursesDocument ={/* ... */}asunknownas DocumentNode<GetCoursesQuery, GetCoursesQueryVariables>;Bereitgestellt von
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
}Bereitgestellt von
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
}
}
}Bereitgestellt von
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";importtype{ TypedDocumentNode }from"@graphql-typed-document-node/core";constAPI_URL="http://localhost:4000/graphql";exportasyncfunctionexecute<TResult, TVariables>(
document: TypedDocumentNode<TResult, TVariables>,
variables: TVariables,):Promise<TResult>{const response =awaitfetch(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){thrownewError(errors[0].message);}return data as TResult;}Bereitgestellt von
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,typeGetCourseQuery}from"./generated/graphql";functionformatCourse(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 }=awaitexecute(GetCourseDocument,{ id:"c1"});if(course){console.log(formatCourse(course));}else{console.log("Course not found");}Bereitgestellt von
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
Das setzt einen laufenden GraphQL-Server voraus. Hier ist der Mock-Server, den ich genutzt habe:
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 variableawaitexecute(GetCourseDocument,{});const{ course }=awaitexecute(GetCourseDocument,{ id:"c1"});// Reading a field the query doesn't requestconsole.log(course?.level);// Forgetting that course can be nullconsole.log(course.title);Bereitgestellt von
TypeScript fängt alle drei Fehler ab, bevor der Code läuft:
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:
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
}
}
}Bereitgestellt von
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,},},Bereitgestellt von
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:
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
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.
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 }=awaitrequest("http://localhost:4000/graphql",
GetCourseDocument,{ id:"c2"},);console.log(course?.title);Bereitgestellt von
Starte es mit npx tsx src/graphql-request.ts:
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 ."}}Bereitgestellt von
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:
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 buildBereitgestellt von
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 Typen
Generierte Typen
Pflegeaufwand
Manuell bei jeder Schema-Änderung
Ein Befehl nach jeder Änderung
Schema-Drift
Möglich und unbemerkt
Bei Generierung oder Kompilierung erkannt
Boilerplate
Wächst mit jeder Operation
Keiner von Hand
Kontrolle über Custom-Typen
Voll
Begrenzt auf Plugin-Optionen
Schema-Driven Development
Manuelles Abgleichen
Compiler 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.
Introspection
GraphQL Codegen
Was es ist
Eingebautes GraphQL-Abfragesystem
CLI-Tool und Plugins
Eingabe
Eine Query an einen laufenden Server
Ein Schema und deine Operationen
Ausgabe
JSON-Beschreibung des Schemas
Typen, Document Nodes, Client-Code
Wann es läuft
Immer wenn ein Client den Server fragt
Wä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-apolloBereitgestellt von
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/**/*.gqlBereitgestellt von
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.
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.
Baue deine Python-Kenntnisse für die Softwareentwicklung aus. Schreib saubere Funktionen, meistere OOP, Datenstrukturen und Algorithmen und liefere gut getesteten Code.
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
titleim TypCourseinnameum. Das Frontend kompiliert weiterhin, weil das manuell geschriebeneCourse-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:
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
titleaus der Einleitung würde die Generierung mit einem Fehler wieCannot 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
typescriptSchema-Typen, undtypescript-operationserzeugt 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
Die Idee in Kürze:
Schema bereitstellen: Zeige Codegen eine lokale
.graphql-Datei oder ein laufendes GraphQL-Endpoint, das Codegen per Introspection ausliestCodegen auf deine Operationen zeigen: Verwende Glob-Muster wie
src/**/*.ts, damit Codegen Queries, Mutationen und Fragmente im Code findetPlugins und Ausgabepfade konfigurieren: Sage Codegen, welche Dateien es schreiben soll und welche Plugins jeweils zuständig sind
Codegen ausführen: Führe
npx graphql-codegenaus, um das Schema zu laden, deine Operationen zu validieren und die Ausgabe zu schreibenGenerierte 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:Das Preset
clientist 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:
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:
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 TypTypedDocumentNodebereit, 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 erzeugtSchritt 2: Eine Konfigurationsdatei anlegen
Codegen liest seine Einstellungen aus einer Konfigurationsdatei im Projekt-Root. Erstelle
codegen.tsmit einer leeren Konfiguration:Du kannst auch
npx graphql-codegen initausfü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.graphqlim Projekt-Root:Lege dann
src/operations/courses.graphqlmit einer Query an, die Kurse und ihre Instructors holt:Zeige Codegen jetzt beide Dateien. Der Schlüssel
schemanimmt den Schema-Pfad,documentsein Glob-Muster für deine Operationen:Schritt 4: Eine Ausgabedatei wählen
Der Schlüssel
generatessagt Codegen, wohin die Ausgabe geschrieben wird. Jeder Key darin ist ein Dateipfad: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:
Wenn du einem älteren Tutorial gefolgt bist, hast du wahrscheinlich auch das Plugin
typescriptgesehen. Das kannst du hier weglassen:typescript-operationsfunktioniert 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:
Und führe es aus:
Codegen lädt das Schema, validiert die Query dagegen und schreibt die Ausgabe:
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 nutztGetCoursesQueryVariables: Der Typ für die Variablen der Query – beide optional, weil das Schema sie nicht als erforderlich markiertGetCoursesQuery: Die Form der Antwort – ausschließlich mit den Feldern, die die Query anfragtGetCoursesDocument: Die geparste Query als typisierter Document Node – mit Ergebnis- und VariablentypenSchau dir
GetCoursesQuerynoch einmal an. Es enthält wederdurationHoursnoch diebiodes Instructors, weil die Query sie nicht anfragt. Versuchst du in deinem Codecourse.durationHourszu lesen, gibt es einen Compile-Fehler statt einundefinedzur 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.ymlodercodegen.jsonheiß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
schemasagt Codegen, wo dein Schema liegt. Er akzeptiert mehrere Quellen.Eine lokale Datei oder ein Glob-Muster funktioniert, wenn das Schema im Repo liegt:
Eine URL funktioniert, wenn das Schema auf einem laufenden Server liegt. Codegen sendet eine Introspection-Query an das Endpoint, bei Bedarf mit Auth-Headern:
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
documentssagt 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 einemgql-Tag umschlossen oder mit einem Kommentar/* GraphQL */markiert sind:Um beide Dateitypen zu scannen, erweitere das Glob-Muster. Füge ein Negativmuster hinzu, damit Codegen die eigene Ausgabe nicht scannt:
Gib jeder Operation einen eindeutigen Namen. Codegen bildet Typnamen aus Operationsnamen – aus
EnrollStudentwerdenEnrollStudentMutationundEnrollStudentMutationVariables.Generates
Der Schlüssel
generatesordnet 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:
Das Objekt
configinnerhalb eines Ausgabesziels gilt nur für diese Datei. Hier sorgtuseTypeImportsdafür, dassimport typeverwendet wird – das ist in manchen Build-Setups erforderlich. Platzierst duconfigauf 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 Inputstyped-document-node: Dokumentobjekte mit angehängten Ergebnis- und Variablentypen, die die meisten GraphQL-Clients verstehentypescript: Typen für jedes Objekt, Enum und jeden Input im Schema – unabhängig davon, ob deine Operationen sie verwendentypescript-resolvers: Typsignaturen für Resolver-Funktionen auf der ServerseiteEin Preset ist ein Plugin-Bundle mit sinnvoller Standardkonfiguration. Das Preset
clientaus dem Abschnitt So funktioniert’s empfiehlt The Guild für Client-Apps. Es baut unter der Haube auf dem verbessertentypescript-operationsauf – 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
typescriptgeneriert für jedes Objekt, Enum und jeden Input in deinem Schema einen Typ. Für den Kurskatalog siehtCourseso aus: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-operationserzeugt 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
EnrollStudentaus:Der Ergebnistyp entspricht eins zu eins dem Selection Set. Der Variablentyp ist
Exact, wodurch TypeScript zusätzliche oder falsch geschriebene Variablen ablehnt.Die Variable
courseIdakzeptiertstringundnumber, weil der GraphQL-ScalarIDbeides als Input annimmt. Seit v6 ist der Default-Typstring | number– korrekt für Client-Fälle.Typisierte Document Nodes
Ein regulärer
DocumentNodeist 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-nodegeneriert pro Operation einen solchen Knoten:So können Funktionen, die einen
TypedDocumentNodeannehmen, 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 Clienttypescript-urql: Generiert typisierte Hooks und Komponenten für urqltypescript-react-query: Generiert typisierte Hooks für TanStack Querytypescript-graphql-request: Generiert ein typisiertes SDK mit einer Funktion pro OperationAll 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/graphqlbereitstellt.Hier ist der Schema-Ausschnitt, den wir nutzen:
Zwei Details sind wichtig: Das Feld
coursegibtCourseohne!zurück – alsonull, wenn keine ID passt. Diebiodes Instructors ist ebenfalls nullable.Erstelle
src/operations/course.graphqlmit einer Query für einen Kurs:Führe erneut
npm run codegenaus. Codegen ergänzt zwei neue Typen insrc/generated/graphql.ts:Inhalt der Datei graphql.ts
Die Nullbarkeit aus dem Schema bleibt erhalten.
coursekannnullsein,biokannnullsein, undidist erforderlich, weil die Query es alsID!deklariert.Nun zum Anwendungscode. Erstelle
src/execute.ts– ein Helper, der jeden typisierten Document an die API sendet: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:Die Funktion
formatCourse()erhält ihren Parametertyp aus dem generierten Query-Typ.NonNullableentfernt dennull-Fall, weil die Funktion erst nach demif-Check läuft.Das Beispiel nutzt Top-Level-
await. Setze daher"type": "module"inpackage.jsonund starte es mitnpx tsx src/course-details.ts:Erfolgreicher Aufruf eines GraphQL-Mock-Servers
Das setzt einen laufenden GraphQL-Server voraus. Hier ist der Mock-Server, den ich genutzt habe:
Jetzt brechen wir es gezielt. Öffne
src/course-details.tsund ersetze alles unterhalb der FunktionformatCourse()durch drei typische Fehler, die handgeschriebene Typen oft durchlassen:Dann führe die Typprüfung aus:
TypeScript fängt alle drei Fehler ab, bevor der Code läuft:
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
durationHoursnullable, regenerierst du – der Typ wird zunumber | 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.tsund die Mock-API aus dem letzten Abschnitt – lassnpx tsx mock/server.tsin einem separaten Terminal laufen.GraphQL Codegen mit Apollo
Installiere Apollo Client und seine Peer-Dependency
rxjs:Das Beispiel führt außerdem die Mutation
EnrollStudentaus. Speichere sie alssrc/operations/enroll.graphql: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 incodegen.tshinzu: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 codegenerneut aus, damit die neue Mutation und Config erkannt werden.Apollo Client akzeptiert typisierte Document Nodes in
query()undmutate(). Speichere das alssrc/apollo.ts:Das Objekt
dataist alsGetCoursesQuery | undefinedtypisiert, und TypeScript prüftvariablesgegenGetCoursesQueryVariables. Die Mutation funktioniert analog mitEnrollStudentMutationund den zugehörigen Variablen.Starte es mit
npx tsx src/apollo.ts: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()unduseMutation()leiten die Typen aus typisierten Document Nodes genauso ab.GraphQL Codegen mit urql
Installiere das urql-Core-Paket:
urql funktioniert out of the box mit typisierten Document Nodes. Übergib das Dokument als erstes Argument an
query()insrc/urql.ts:Das zweite Argument ist als Variablentyp der Query typisiert, und
result.dataist als Ergebnis der Query typisiert.Starte es mit
npx tsx src/urql.ts:Urql-Ausgabe
Die Framework-Bindings, z. B.
useQuery()imurql-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-requestsendet minimalistisch eine Anfrage und gibt die Daten zurück. Installiere ihn so:Er leitet Typen aus typisierten Document Nodes genau wie Apollo und urql her. Speichere das als
src/graphql-request.ts:Starte es mit
npx tsx src/graphql-request.ts: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
GetCourseQueryundGetCourseQueryVariablesund ü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: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:Ohne Installation läuft Codegen einmal und meldet
Failed to import @parcel/watcherstatt zu beobachten.Der Watch-Mode verfolgt sowohl deine Operationen als auch eine lokale Schemadatei. Fügst du
course.graphqlein Feld hinzu, taucht es Sekunden später inGetCourseQueryauf. Machst dudurationHoursinschema.graphqlnullable, wird der Typ zunumber | 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
prebuildvorbuildaus. Mit den obigen Skripten regeneriertnpm run buildzuerst 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
--checkstartet 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:
Der Schritt
codegen:checkergibt nur Sinn, wenn ihr generierte Dateien eincheckt. Wenn nicht, lass ihn weg –npm run buildgeneriert ohnehin alles über denprebuild-Hook.Bei Schema-Änderungen regenerieren
Operationen ändern sich in deinem Repo – Watch-Mode und
prebuilddecken 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:
codegen:checkschlägt in der CI fehl, sobald das Server-Schema nicht mehr zur eingecheckten Ausgabe passtEin 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
Courseaus der Einleitung kompilierte weiter, nachdem das Backendtitleumbenannt 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:
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
__schemaund__typeAnfragen 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
schemaincodegen.tsauf 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/introspectionschreibt das Schema als Introspection-JSON, das einige Tools – etwa urqls Graphcache – für schema-bewusstes Caching nutzen.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-operationsnur noch Enums und Inputs, die deine Operationen verwenden. Wenn du einen vollständigen Schema-Typ wieCoursebrauchst, füge das Plugintypescriptin einer separaten Ausgabedatei hinzu.Wenn du ein nicht installiertes Plugin verwendest, bricht Codegen mit einer klaren Meldung ab:
Codegen findet keine Operationen
Dieser Fehler bedeutet, dass das
documents-Glob keine Datei mit einer Operation gefunden hat:Prüfe, ob die Erweiterung im Glob zu deinen Dateien passt. Ein Muster
.gqlfindet keine.graphql-Dateien undsrc/**/*.graphqlfindet keine Inline-Operationen in.ts-Dateien.Bei Inline-Operationen prüfe auch das Tag. Codegen findet nur Template-Literals, die in
gqleingeschlossen oder mit/* GraphQL */markiert sind. Ein einfaches Template-String mit Query ist unsichtbar.Wenn du
ignoreNoDocuments: truesetzt, 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 odercodegen.tserneut aus. Im Alltag erledigtnpm run codegen:watchdas 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
schemazeigt. 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
prebuildvor Builds, damit niemand mit alten Typen arbeitetOperationsspezifische Typen generieren: Nutze
typescript-operationsfür Client-Code, weil die Typen exakt dem entsprechen, was jede Query holtGenerierte Dateien nur committen, wenn euer Workflow es braucht: Commits erlauben Code-Reviews von Typänderungen und
--checkin der CI. Wenn ihr das nicht braucht, setzt den Ausgabeordner in die.gitignoreund 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 einprebuild-Hook fängt vergessene lokale Läufe abGenerierte 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.