GraphQL Codegen: hoe je type-veilige code genereert uit een GraphQL-schema
Een praktische gids voor GraphQL Code Generator met setup en configuratie, gegenereerde TypeScript-types en getypeerde document nodes, integratie met Apollo, urql en graphql-request, en automatisering met watch-modus en CI.
Handgeschreven TypeScript-types voor een GraphQL-API zijn verouderd zodra iemand het schema wijzigt.
Stel, een backenddeveloper hernoemt het veld title op het type Course naar name. De frontend compileert nog steeds, omdat de handgeschreven Course-interface niet weet dat er iets is veranderd, dus de bug verschijnt pas tijdens runtime. In echte applicaties zijn er vaak tientallen queries, mutaties en fragments, dus je ziet hoe dit snel kan escaleren.
GraphQL Code Generator, of kortweg GraphQL Codegen, leest je schema en GraphQL-operaties en zet ze om in types, queryhelpers, clientintegraties en andere boilerplate die je anders met de hand zou schrijven. Het wordt meestal gebruikt met TypeScript en populaire clients zoals Apollo en urql. Met één commando houd je je types in sync zodra het schema verandert.
In dit artikel laat ik je zien hoe je GraphQL Codegen opzet in een klein TypeScript-project, hoe je het configureert, de gegenereerde types gebruikt en het automatisch laat draaien als onderdeel van je workflow.
GraphQL Codegen is een commandlinetool die GraphQL-definities omzet in applicatiecode.
Het is een open-sourceproject van The Guild, en je installeert het als devdependency in je project. Het verbindt drie dingen:
GraphQL-schema: Het contract tussen de server en zijn clients, met elk type, veld en argument dat de API aanbiedt
GraphQL-operaties: De queries, mutaties, subscriptions en fragments die je applicatie naar de API stuurt
Gegenereerde code: De types en helpers die Codegen schrijft op basis van het schema en jouw operaties
Het schema vertelt Codegen wat mogelijk is en de operaties vertellen wat je applicatie opvraagt.
Codegen combineert beide, zodat elk gegenereerd type exact overeenkomt met de vorm van het antwoord voor één operatie. Het valideert ook elke operatie tegen het schema. Het hernoemde veld title uit de introductie zou de generatie stoppen met een fout zoals Cannot query field "title" on type "Course", en je vangt het voordat de code draait.
De output hangt af van je plugins en configuratie. Codegen zelf schrijft geen TypeScript. Plugins doen dat. Zo genereert de plugin typescript schematypes, en de plugin typescript-operations genereert types voor je queries en mutaties. Er zijn ook plugins voor andere talen, zoals Java en C#, maar dit artikel blijft bij TypeScript.
Onthoud wel dat Codegen je GraphQL-server niet vervangt.
Het voert geen queries uit en haalt geen data op. Het leest GraphQL-definities tijdens ontwikkeling en schrijft bestanden. Je server en je GraphQL-client doen de rest.
Voorzie in een schema: Verwijs Codegen naar een lokaal .graphql-bestand of een draaiend GraphQL-endpoint, dat Codegen via introspectie leest
Wijs Codegen naar je operaties: Gebruik globpatronen zoals src/**/*.ts zodat Codegen queries, mutaties en fragments in je code vindt
Configureer plugins en outputdoelen: Vertel Codegen welke bestanden te schrijven en welke plugins elk bestand genereren
Draai Codegen: Voer npx graphql-codegen uit om het schema te laden, je operaties te valideren en de output te schrijven
Gebruik de gegenereerde artefacten: Importeer de gegenereerde types en document nodes in je applicatiecode
Stappen 1 t/m 3 zet je in één configbestand, meestal codegen.ts. Dit is de kleinste versie ervan voor een cursuscatalogusproject:
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;Mogelijk gemaakt door
De preset client is een bundel van plugins die in één keer schematypes, operatietypes en getypeerde document nodes genereert. Ik behandel elk hiervan in de secties over setup en configuratie.
GraphQL Codegen instellen
De beste manier om Codegen te begrijpen is het op een echt project te draaien.
In deze sectie bouw je vanaf nul een klein cursuscatalogusproject. Het heeft een schema met cursussen en docenten, één query, en een Codegen-config die de query omzet in TypeScript-types. Je hebt alleen Node.js en npm nodig.
Stap 1: Installeer GraphQL Code Generator
Maak een nieuwe map en initialiseer een npm-project:
Codegen heeft een paar packages nodig. Twee gaan in reguliere dependencies, en de rest zijn devdependencies omdat ze alleen tijdens ontwikkeling draaien:
npminstall graphql @graphql-typed-document-node/core
npminstall-D typescript @graphql-codegen/cli @graphql-codegen/typescript-operations @graphql-codegen/typed-document-nodeMogelijk gemaakt door
Dit doet elk package:
graphql: De referentie-implementatie van GraphQL voor JavaScript, die Codegen gebruikt om het schema en de operaties te parsen
@graphql-typed-document-node/core: Levert het type TypedDocumentNode dat je gegenereerde code importeert
@graphql-codegen/cli: De Codegen-commandlinetool
@graphql-codegen/typescript-operations: De plugin die types voor je queries, mutaties en fragments genereert
@graphql-codegen/typed-document-node: De plugin die documentobjecten genereert met de bijbehorende types
Stap 2: Maak een configuratiebestand
Codegen leest zijn instellingen uit een configbestand in de projectroot. Maak codegen.ts en zet er voorlopig een lege config in:
importtype{ CodegenConfig }from"@graphql-codegen/cli";const config: CodegenConfig ={};exportdefault config;Mogelijk gemaakt door
Je kunt ook npx graphql-codegen init draaien om een paar vragen te beantwoorden en een gegenereerd configbestand te krijgen. Ik schrijf het hier met de hand zodat je ziet wat elke instelling doet.
Stap 3: Geef de locaties van schema en documenten op
Codegen heeft twee inputs nodig, dus laten we die beide maken.
Sla eerst het schema op als schema.graphql in de projectroot:
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!
}Mogelijk gemaakt door
Maak daarna src/operations/courses.graphql met een query die cursussen en hun docenten ophaalt:
query GetCourses($level: Level, $limit: Int) {
courses(level: $level, limit: $limit) {
id
title
level
instructor {
name
}
}
}Mogelijk gemaakt door
Wijs Codegen nu naar beide bestanden. De sleutel schema krijgt het schemapad, en documents krijgt een globpatroon dat je operaties matcht:
const config: CodegenConfig ={
schema:"schema.graphql",
documents:["src/**/*.graphql"],};Mogelijk gemaakt door
Stap 4: Kies een outputbestand
De sleutel generates vertelt Codegen waar de output moet komen. Elke sleutel daarbinnen is een bestandspad:
const config: CodegenConfig ={
schema:"schema.graphql",
documents:["src/**/*.graphql"],
generates:{"src/generated/graphql.ts":{},},};Mogelijk gemaakt door
Codegen maakt de map src/generated/ als die nog niet bestaat.
Stap 5: Voeg relevante plugins toe
Een outputbestand zonder plugins is leeg. Voeg de twee plugins toe die je hebt geïnstalleerd:
importtype{ 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"],},},};exportdefault config;Mogelijk gemaakt door
Als je een oudere tutorial hebt gevolgd, heb je waarschijnlijk ook de plugin typescript in deze lijst gezien. Je kunt die nu weglaten, want typescript-operations werkt zelfstandig en genereert alleen Input-, Enum- en Operatietypes die daadwerkelijk gebruikt worden. Als je beide in hetzelfde outputbestand zet op de huidige versies, gooit TypeScript fouten over dubbele declaraties.
Stap 6: Draai Codegen
Voeg een npm-script toe zodat je het commando niet hoeft te onthouden:
Codegen laadt het schema, valideert de query ertegen en schrijft de output:
Resultaten van Codegen-generatie
Als een operatie verwijst naar een veld dat niet bestaat in het schema, faalt de run hier en worden er geen bestanden geschreven.
Stap 7: Bekijk de gegenereerde output
Open src/generated/graphql.ts. Dit is wat je ziet:
De gegenereerde output
Codegen genereerde vier dingen:
Level: Een string-unie voor de enum, alleen gegenereerd omdat de query hem gebruikt
GetCoursesQueryVariables: Het type voor de variabelen die je aan de query doorgeeft, waarbij beide optioneel zijn omdat het schema ze niet als vereist markeert
GetCoursesQuery: De vorm van het antwoord, met alleen de velden waar de query om vraagt
GetCoursesDocument: De geparste query als een getypeerde document node, met de resultaat- en variabelentypes gekoppeld
Kijk nog eens naar GetCoursesQuery. Het bevat geen durationHours of de bio van de docent, omdat de query er niet om vraagt. Als je in je code course.durationHours probeert te lezen, krijg je een compileerfout, geen undefined tijdens runtime.
En dat is de hele setup – jij schrijft GraphQL en Codegen schrijft de TypeScript.
GraphQL Codegen configureren
De meeste Codegen-configs die je ziet zijn langer dan die hierboven, maar ze zijn opgebouwd uit dezelfde vier instellingen.
Het configbestand kan codegen.ts, codegen.yml of codegen.json zijn. Ik gebruik TypeScript omdat je autocomplete en typechecks op de config zelf krijgt. De instellingen zijn in elk formaat hetzelfde.
Schema
De sleutel schema vertelt Codegen waar je schema staat. Het accepteert een paar brontypes.
Een lokaal bestand of een globpatroon werkt wanneer het schema in je repo staat:
schema:"schema.graphql",// or, for a schema split across files
schema:"schema/**/*.graphql",Mogelijk gemaakt door
Een URL werkt wanneer het schema op een draaiende server staat. Codegen stuurt een introspectiequery naar het endpoint, en je kunt headers doorgeven voor authenticatie:
schema:[{"https://api.example.com/graphql":{
headers:{ Authorization: Bearer ${process.env.API_TOKEN}},},},],Mogelijk gemaakt door
De URLooptie werkt alleen als de server introspectie aan heeft staan. Veel productie-API’s zetten dat uit, dus voor CI is een schemabestand dat is gecommit in de repo meestal de veiligere keuze.
Documents
De sleutel documents vertelt Codegen waar je queries, mutaties, subscriptions en fragments te vinden zijn.
Operaties kunnen in .graphql-bestanden staan of inline in je TypeScript-code. Codegen vindt inline operaties wanneer ze zijn omwikkeld met een gql-tag of gemarkeerd met een /* GraphQL */-commentaar:
const EnrollStudent =/* GraphQL */
mutation EnrollStudent($courseId:ID!, $studentEmail: String!){enrollStudent(courseId: $courseId, studentEmail: $studentEmail){
id
course {
title
}}};Mogelijk gemaakt door
Om beide bestandstypen te scannen, verbreed je het globpatroon. Voeg een negatief patroon toe zodat Codegen zijn eigen output niet scant:
Geef elke operatie een unieke naam. Codegen bouwt typenames op basis van operatienamen, dus EnrollStudent wordt EnrollStudentMutation en EnrollStudentMutationVariables.
Generates
De sleutel generates koppelt outputpaden aan wat erin komt. Je kunt zoveel outputdoelen hebben als nodig, elk met eigen plugins.
Stel dat je operatietypes in één bestand wilt en de volledige schematypes in een ander:
generates:{"src/generated/graphql.ts":{
plugins:["typescript-operations","typed-document-node"],
config:{
useTypeImports:true,},},"src/generated/schema-types.ts":{
plugins:["typescript"],},},Mogelijk gemaakt door
Het config-object binnen een outputdoel geldt alleen voor dat bestand. Hier zorgt useTypeImports ervoor dat het gegenereerde bestand import type gebruikt, wat sommige buildsetups vereisen. Als je config in de root van het bestand plaatst, geldt het voor elke output.
Een outputpad kan ook een map zijn die eindigt op een slash, zoals "src/gql/". Dat is het formaat dat presets gebruiken, omdat ze meer dan één bestand schrijven.
Plugins
Plugins bepalen wat er wordt gegenereerd. Codegen laadt het schema en de documenten, en elke plugin zet die om in een stuk output.
Dit zijn de plugins die je het vaakst ziet in TypeScript-projecten:
typescript-operations: Types voor je queries, mutaties, subscriptions en fragments, plus de enums en inputs die ze gebruiken
typed-document-node: Documentobjecten met de resultaat- en variabelentypes gekoppeld, die de meeste GraphQL-clients begrijpen
typescript: Types voor elk object, elke enum en input in het schema, of je operaties ze nu gebruiken of niet
typescript-resolvers: Typesignatures voor resolverfuncties aan de serverkant
Een preset is een bundel van plugins met een verstandige standaardconfig. De preset client uit de sectie Hoe het werkt is degene die The Guild aanraadt voor clientapps. Hij bouwt onder de motorkap voort op de verbeterde typescript-operations, zodat je de voordelen krijgt zonder extra setup.
Elke plugin heeft zijn eigen configopties, en dat zijn er veel. Je hoeft ze niet vooraf te leren. Begin met de defaults en zoek een optie op wanneer de gegenereerde output niet matcht met wat je code verwacht.
Wat kan GraphQL Codegen genereren?
Wat je uit Codegen haalt, hangt af van de plugins die je kiest.
Hetzelfde schema en dezelfde operaties kunnen platte TypeScript-types opleveren of kant-en-klare clientcode. Dit zijn de outputs die je het vaakst gebruikt.
TypeScript-types
De plugin typescript genereert een type voor elk object, elke enum en input in je schema. Voor de cursuscatalogus ziet het type Course er zo uit:
exporttypeCourse={
__typename?:'Course';
durationHours: Scalars['Int']['output'];
id: Scalars['ID']['output'];
instructor: Instructor;
level: Level;
title: Scalars['String']['output'];};Mogelijk gemaakt door
Deze types beschrijven het volledige schema, wat ze handig maakt aan de serverkant, in testfixtures en in utilityfuncties die met complete objecten werken.
Maar ze passen minder goed bij clientcode. Een type Course zegt dat elk veld bestaat, ook de velden waar je query niet om vroeg.
Operatietypes
De plugin typescript-operations genereert twee types per operatie: één voor het resultaat en één voor de variabelen. Het werkt hetzelfde voor queries en subscriptions.
Dit genereert het voor een mutatie EnrollStudent:
exporttypeEnrollStudentMutationVariables= Exact<{
courseId:string|number;
studentEmail:string;}>;exporttypeEnrollStudentMutation={ enrollStudent:{ id:string, course:{ title:string}}};Mogelijk gemaakt door
Het resultatentype matcht de selectieset, veld voor veld. Het variabelentype is Exact, zodat TypeScript extra of verkeerd gespelde variabelen afwijst.
De variabele courseId accepteert zowel string als number omdat de GraphQL-scalar ID beide als input accepteert. Sinds v6 is het standaardtype string | number, wat het juiste type is voor clientgebruik.
Getypeerde document nodes
Een gewone DocumentNode is een geparste GraphQL-query. Die kent de structuur van de query, maar weet niet wat de query teruggeeft of welke variabelen nodig zijn.
Een getypeerde document node heeft beide types erbij. De plugin typed-document-node genereert er één per operatie:
exportconst GetCoursesDocument ={/* ... */}asunknownas DocumentNode<GetCoursesQuery, GetCoursesQueryVariables>;Mogelijk gemaakt door
Zo kan elke functie die een TypedDocumentNode accepteert het resultaat- en variabelentype afleiden uit alleen het document. Je geeft geen generics met de hand door, en je kunt geen query combineren met de verkeerde types.
De meeste moderne GraphQL-clients accepteren getypeerde document nodes, waaronder Apollo Client, urql en graphql-request. Je ziet alle drie later in dit artikel in actie.
Clientspeficieke integraties
Sommige plugins gaan verder en genereren code voor een specifieke client of framework. Bijvoorbeeld:
typescript-react-apollo: Genereert getypeerde React-hooks voor Apollo Client
typescript-urql: Genereert getypeerde hooks en componenten voor urql
typescript-react-query: Genereert getypeerde hooks voor TanStack Query
typescript-graphql-request: Genereert een getypte SDK met één functie per operatie
Dit zijn allemaal communityplugins. The Guild heeft ze verhuisd naar een aparte communityrepository, dus hun releasetempo verschilt van de coreplugins.
Je hebt ze ook minder vaak nodig dan vroeger. Wanneer een client getypeerde document nodes ondersteunt, voegen gegenereerde hooks weinig typesafety toe. De documentatie van Apollo raadt bijvoorbeeld aan om de plugin typescript-operations te gebruiken, die zich richt op alleen types genereren en geen extra runtimecode bevat.
In het algemeen begin je met operatietypes en getypeerde document nodes. Voeg daarna pas een clientspecifieke plugin toe als je team de gegenereerde hooks of SDK-functies wil.
GraphQL Codegen met TypeScript
Gegenereerde types zijn alleen nuttig als ze fouten vangen, dus laten we er een paar maken.
Dit voorbeeld breidt het cursuscatalogusproject uit met een tweede query, een kleine helper die die naar de API stuurt, en de code die het resultaat gebruikt. Het gaat uit van een GraphQL-server die het schema implementeert op http://localhost:4000/graphql.
Dit is het deel van het schema dat dit voorbeeld gebruikt:
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
}Mogelijk gemaakt door
Twee details zijn hier belangrijk. Het veld course retourneert Course zonder !, dus het is null wanneer geen cursus overeenkomt met het ID. De bio van de docent is ook nullable.
Maak src/operations/course.graphql met een query die één cursus ophaalt:
query GetCourse($id: ID!) {
course(id: $id) {
title
durationHours
instructor {
name
bio
}
}
}Mogelijk gemaakt door
Draai npm run codegen opnieuw. Codegen voegt twee nieuwe types toe aan src/generated/graphql.ts:
Inhoud van het bestand graphql.ts
De nullability uit het schema blijft behouden. course kan null zijn, bio kan null zijn, en id is vereist omdat de query die als ID! declareert.
Nu de applicatiecode. Maak src/execute.ts met een helper die elk getypt document naar de API stuurt:
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;}Mogelijk gemaakt door
De helper weet niets over cursussen. Hij haalt beide types uit het document dat je doorgeeft, en de functie print() zet het document terug om in een querystring voor het request.
Gebruik hem vervolgens 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");}Mogelijk gemaakt door
De functie formatCourse() haalt zijn parametertype uit het gegenereerde querytype. NonNullable verwijdert de null-case, omdat de functie pas draait na de if-check.
Het voorbeeld gebruikt top-level await, dus zet "type": "module" in package.json en draai het met npx tsx src/course-details.ts:
Geslaagde call naar een GraphQL-mockserver
Dit gaat er nu van uit dat je een GraphQL-server hebt draaien. Hier is een mockserver die ik gebruikte:
Probeer het nu te breken. Open src/course-details.ts en vervang alles onder de functie formatCourse() door drie fouten die handgeschreven types vaak doorlaten:
// 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);Mogelijk gemaakt door
TypeScript vangt alle drie voordat de code draait:
Fouten gedetecteerd door TypeScript
Zo reduceert Codegen mismatches tussen de frontend en de API. De types komen uit hetzelfde schema dat de server gebruikt, dus ze kunnen geen velden beschrijven die niet bestaan of nulls missen die de server kan teruggeven.
En de bescherming stopt niet na de eerste run. Stel dat het backendteam durationHours nullable maakt. Je regenereert, het type verandert naar number | null, en TypeScript wijst elke regel aan die van een number uitging.
GraphQL Codegen met GraphQL-clients
Codegen verstuurt geen requests. Dat is de taak van je GraphQL-client.
De gegenereerde getypeerde document nodes zijn het overdrachtspunt tussen beide. Je geeft ze door aan de client, en de client leidt de types af. De voorbeelden hieronder gebruiken hetzelfde bestand src/generated/graphql.ts en de mock-API uit de vorige sectie, dus laat npx tsx mock/server.ts in een aparte terminal draaien.
GraphQL Codegen met Apollo
Installeer Apollo Client en diens peer dependency rxjs:
Het voorbeeld draait ook de mutatie EnrollStudent. Sla die op als src/operations/enroll.graphql:
mutation EnrollStudent($courseId: ID!, $studentEmail: String!) {
enrollStudent(courseId: $courseId, studentEmail: $studentEmail) {
id
course {
title
}
}
}Mogelijk gemaakt door
De documentatie van Apollo raadt ook twee configopties voor Codegen aan, omdat Apollo Client altijd __typename-velden opneemt maar die niet toevoegt aan roottypes. Voeg ze toe aan het outputdoel in codegen.ts:
"src/generated/graphql.ts":{
plugins:["typescript-operations","typed-document-node"],
config:{
nonOptionalTypename:true,
skipTypeNameForRoot:true,},},Mogelijk gemaakt door
Met deze opties krijgt elk object in de gegenereerde resultatentypes een verplicht veld __typename, zoals __typename: 'Course'. Dat matcht wat de cache van Apollo teruggeeft.
Draai npm run codegen opnieuw om de nieuwe mutatie en config te detecteren.
Apollo Client accepteert getypeerde document nodes in query() en mutate(). Sla dit op als src/apollo.ts:
import{ ApolloClient, HttpLink, InMemoryCache }from"@apollo/client";import{ EnrollStudentDocument, GetCoursesDocument }from"./generated/graphql";const client =newApolloClient({
link:newHttpLink({ uri:"http://localhost:4000/graphql"}),
cache:newInMemoryCache(),});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);Mogelijk gemaakt door
Het object data is getypt als GetCoursesQuery | undefined, en TypeScript controleert variables tegen GetCoursesQueryVariables. De mutatie werkt hetzelfde met EnrollStudentMutation en de bijbehorende variabelen.
Draai het met npx tsx src/apollo.ts:
Apollo-output
De eerste regel komt van de query, omdat dat de enige beginnerscursus is. De tweede komt van de mutatie, die de titel retourneert van de cursus waarvoor de student zich inschreef.
De React-hooks, zoals useQuery() en useMutation(), leiden types op dezelfde manier af uit getypeerde document nodes.
Hij leidt types af uit getypeerde document nodes net als Apollo en urql. Sla dit op 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);Mogelijk gemaakt door
Draai het met npx tsx src/graphql-request.ts:
Output van GraphQL-request
Hetzelfde idee werkt met TanStack Query. Die stuurt zelf geen GraphQL-requests, dus je roept graphql-request aan of de helper execute() uit de vorige sectie binnen de queryfunctie, en het resultatentype loopt door naar je code.
En als je client helemaal geen getypeerde document nodes ondersteunt, kun je nog steeds de platte operatietypes gebruiken. Importeer GetCourseQuery en GetCourseQueryVariables en geef ze door als generics. Dat is wat meer handwerk, maar de types komen nog steeds uit het schema.
GraphQL Codegen automatisch draaien
Gegenereerde types helpen alleen als ze overeenkomen met het huidige schema en de huidige operaties.
Als je vergeet Codegen opnieuw te draaien na een wijziging, beschrijven de types code die niet meer bestaat. Dat is hetzelfde driftprobleem als bij handgeschreven types, alleen met extra stappen. De oplossing is de handmatige stap uit de workflow halen.
npm-scripts
Begin met een paar scripts in package.json, zodat iedereen in het team Codegen op dezelfde manier draait:
{"scripts":{"codegen":"graphql-codegen","codegen:watch":"graphql-codegen --watch","codegen:check":"graphql-codegen --check","prebuild":"npm run codegen","build":"tsc -p ."}}Mogelijk gemaakt door
De rest van deze sectie behandelt waar elk script voor is.
Watch-modus
De watch-modus draait Codegen opnieuw telkens wanneer een gevolgd bestand wijzigt. Het heeft het package @parcel/watcher nodig, dat Codegen niet voor je installeert:
Als je de installatie overslaat, draait Codegen één keer en print het Failed to import @parcel/watcher in plaats van te watchen.
De watch-modus volgt zowel je operaties als een lokaal schemabestand. Als je een veld toevoegt aan course.graphql, verschijnt het nieuwe veld een seconde later in GetCourseQuery. Als je durationHours nullable maakt in schema.graphql, verandert het type in number | null, en je editor markeert elke regel die van een number uitging.
Laat het tijdens ontwikkeling draaien in een terminal naast je devserver.
Genereren vóór builds
npm draait een script genaamd prebuild vóór build. Met de bovenstaande scripts regenereert npm run build eerst de types en draait pas daarna de TypeScript-compiler.
Zo draait een build nooit tegen verouderde types, zelfs niet als iemand vergat Codegen te draaien na het pullen van wijzigingen.
CI/CD
De vlag --check draait Codegen in dry-runmodus. Het schrijft geen bestanden, vergelijkt wat het zou genereren met wat op schijf staat en sluit af met code 1 als er iets verschilt.
Hier is een minimale GitHub Actions-workflow die het gebruikt:
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 buildMogelijk gemaakt door
De stap codegen:check heeft alleen zin als je gegenereerde bestanden commit naar de repo. Zo niet, laat die stap dan weg, want npm run build regenereert alles toch via de hook prebuild.
Regenereer bij schemawijzigingen
Operaties wijzigen in je repo, dus watch-modus en prebuild dekken die af. Schemawijzigingen zijn lastiger, omdat die meestal van een ander team komen.
Hoe je ze afhandelt, hangt af van waar het schema staat:
Schemabestand in dezelfde repo: Watch-modus en CI pikken wijzigingen op; dit is de makkelijkste setup om mee te werken
Schema via een URL: Codegen haalt bij elke run de nieuwste versie op, dus codegen:check in CI faalt zodra het schema van de server niet meer matcht met je gecommitte output
Schema gepubliceerd door een andere repo: Kopieer of download het als onderdeel van je build, draai dan Codegen op de lokale kopie
De URLooptie heeft één addertje. De watch-modus reageert op bestandswijzigingen, dus hij merkt niet wanneer een extern schema verandert. Je ziet die wijzigingen pas bij de volgende handmatige run of CI-job.
GraphQL Codegen vs handgeschreven types
Beide benaderingen geven je TypeScript-types voor GraphQL-data, maar er zijn enkele verschillen om te kennen.
Handgeschreven types
Met handgeschreven types lees je het schema en schrijf je zelf overeenkomende interfaces.
Dat geeft je volledige controle. Je kunt types noemen zoals jij wilt, een paar operaties samenvoegen tot één gedeeld type, of hulptyperingen toevoegen die het schema niet heeft.
Maar het is handwerk. Elk nieuw veld of hernoemd argument betekent dat je het bijbehorende type met de hand moet zoeken en bijwerken. En niets waarschuwt je als je er één mist.
Daar komt drift vandaan. De interface Course uit de introductie compileerde nog steeds nadat de backend title had hernoemd, omdat TypeScript je code alleen tegen je eigen types controleert, niet tegen de API.
Gegenereerde types
Gegenereerde types komen uit hetzelfde schema dat de server gebruikt, dus ze zijn per ontwerp gesynchroniseerd met je GraphQL-definities. Een schemawijziging plus een Codegen-run werkt alle getroffen types in één keer bij.
Je schrijft ook veel minder code. Het cursuscatalogusproject heeft drie operaties en nul handgeschreven types daarvoor.
En je krijgt vrijwel gratis schema-gedreven ontwikkeling. Je wijzigt het schema of een operatie, regenereert, en de compiler geeft je een lijst van alles wat moet worden aangepast.
Maar onthoud: Codegen weerspiegelt alleen wat je erin stopt.
Als het schema elk veld als nullable markeert, zitten je gegenereerde types vol met | null-checks. Als een operatie 40 velden ophaalt terwijl de pagina er vijf nodig heeft, heeft het gegenereerde type 40 velden.
Hier is een korte samenvatting van de verschillen:
Handgeschreven types
Gegenereerde types
Onderhoud
Handmatig bij elke schemawijziging
Eén commando na elke wijziging
Schemadrift
Mogelijk en stil
Opgevangen bij generatie of compileertijd
Boilerplate
Groeit met elke operatie
Niets om met de hand te schrijven
Controle over aangepaste types
Volledig
Beperkt tot pluginconfigopties
Schema-gedreven ontwikkeling
Handmatig kruisen en controleren
Compiler toont elke getroffen regel
Codegen vergeleken met handgeschreven types
GraphQL Codegen vs. GraphQL-introspectie
De twee worden vaak door elkaar gehaald omdat Codegen vaak introspectie gebruikt. Toch lossen ze verschillende problemen op.
Introspectie is een functie van de GraphQL-specificatie. Elke GraphQL-server kan queries over zijn eigen schema beantwoorden via speciale velden zoals __schema en __type. Het resultaat is een JSON-beschrijving van elk type, veld en argument dat de API aanbiedt.
In gewone taal beantwoordt introspectie de vraag "Hoe ziet deze API eruit?"
Codegen beantwoordt de vraag "Welke code heeft mijn applicatie nodig?" Het neemt schema-informatie en je operaties, en schrijft TypeScript-types en getypeerde document nodes.
Wanneer je schema instelt op een URL in codegen.ts, verstuurt Codegen een introspectiequery naar die server om het schema op te halen. Met een lokaal .graphql-bestand gebeurt er helemaal geen introspectie.
Codegen kan ook een introspectieresultaat als output produceren. De plugin @graphql-codegen/introspection schrijft het schema als introspectie-JSON, wat sommige tools, zoals de Graphcache van urql, gebruiken voor schema-bewuste caching.
Introspectie
GraphQL Codegen
Wat het is
Ingebouwd GraphQL-queriesysteem
Commandlinetool en plugin
Input
Een query naar een draaiende server
Een schema en je operaties
Output
JSON-beschrijving van het schema
Types, document nodes, clientcode
Wanneer het draait
Wanneer een client de server vraagt
Tijdens ontwikkeling, builds en CI
Codegen vergeleken met introspectie
Veelvoorkomende problemen met GraphQL Codegen
De meeste Codegen-fouten komen neer op één van vier problemen.
Gegenereerde types ontbreken
Codegen draait zonder fouten, maar het type dat je verwacht staat niet in het outputbestand.
Controleer deze drie dingen in volgorde:
Schema: Als het type niet bestaat in het schema dat Codegen laadt, kan het niet worden gegenereerd, dus open het schemabestand of draai de introspectiequery zelf en bevestig dat het er is
Documents: Operatietypes bestaan alleen voor operaties die Codegen heeft gevonden, dus als het bestand met je query niet wordt gematcht door het globpatroon documents, ontbreken de types
Plugins: Sinds v6 genereert typescript-operations alleen de enums en inputs die je operaties gebruiken, dus als je een volledig schematype zoals Course nodig hebt, voeg de plugin typescript toe aan een apart outputbestand
Als je een plugin gebruikt die je niet hebt geïnstalleerd, faalt Codegen met een duidelijke melding:
Unable to find template plugin matching 'typescript-react-apollo'
Install one of the following packages:
- @graphql-codegen/typescript-react-apolloMogelijk gemaakt door
Codegen kan geen operaties vinden
Deze fout betekent dat het globpatroon documents geen enkel bestand met een operatie heeft gematcht:
Unable to find any GraphQL type definitions for the following pointers:
- src/**/*.gqlMogelijk gemaakt door
Controleer of de extensie in het globpatroon overeenkomt met je bestanden. Een patroon .gql vindt geen .graphql-bestanden, en een patroon src/**/*.graphql vindt geen operaties inline in .ts-bestanden.
Controleer voor inline operaties ook de tag. Codegen vindt alleen template literals die zijn omwikkeld met gql of gemarkeerd met een /* GraphQL */-commentaar. Een gewone template literal met een query erin is onzichtbaar.
Als je ignoreNoDocuments: true instelt, toont Codegen deze fout niet en genereert het een output zonder operatietypes. Die optie is handig in een gloednieuw project, maar kan later een kapot globpatroon verbergen.
Gegenereerde types zijn verouderd
De types compileren, maar weerspiegelen niet de laatste wijziging in een operatie of het schema.
Codegen draait niet uit zichzelf. Draai het opnieuw na elke wijziging aan een .graphql-bestand, een inline operatie, het schema of codegen.ts. Tijdens ontwikkeling doet npm run codegen:watch dat voor je.
Als de types in CI verouderd zijn, commit de geregenereerde bestanden of laat de hook prebuild ze opnieuw genereren vóór de build.
Gegenereerde types komen niet overeen met de API
De types compileren, maar de data van de server heeft op runtime een andere vorm.
Dat betekent bijna altijd dat Codegen en je app met verschillende schema’s praten. Bijvoorbeeld: Codegen leest een lokaal schema.graphql dat een week oud is, terwijl de app een productie-API aanroept die sindsdien is veranderd.
Controleer waar de sleutel schema naar wijst. Als het een bestand is, vergelijk het met de API die je app aanroept en werk het bij. Als het een URL is, zorg dat het dezelfde omgeving is die je app gebruikt, niet een stagingserver met een nieuwer of ouder schema.
Genereer vervolgens opnieuw en bekijk de diff. Als een operatief bestand veranderd is maar het gegenereerde bestand niet, staat de operatie waarschijnlijk buiten het globpatroon documents.
Best practices voor GraphQL Codegen
Codegen heeft niet veel configuratie nodig om goed te werken. Deze practices houden het zo wanneer het project groeit:
Houd het schema en de gegenereerde bestanden in sync: Draai de watch-modus tijdens ontwikkeling en prebuild vóór builds, zodat niemand met types van een ouder schema werkt
Genereer operatiespecifieke types: Gebruik typescript-operations voor clientcode omdat die exact matchen wat elke query ophaalt
Commit gegenereerde bestanden alleen als je workflow ze nodig heeft: Gecommitte bestanden laten je typewijzigingen reviewen in pull requests en --check draaien in CI, en als je team dat niet nodig heeft, voeg de outputmap toe aan .gitignore en genereer bij elke build
Houd de config kort: Eén outputbestand met twee plugins dekt de meeste clientprojecten; elke extra optie is weer iets dat de volgende developer moet begrijpen voor hij iets aanpast
Draai Codegen in CI bij elke push: Een stap --check of een hook prebuild vangt de wijzigingen op die iemand lokaal vergat te regenereren
Bewerk nooit gegenereerde bestanden met de hand: De volgende Codegen-run overschrijft je wijzigingen, dus fix het schema, de operatie of de config in plaats daarvan
Conclusie
GraphQL Codegen neemt het meest repetitieve deel van GraphQL-ontwikkeling over: schema’s en operaties met de hand omzetten in TypeScript-types.
De workflow blijft hetzelfde, hoe groot het project ook wordt. Je definieert het schema en de operaties, configureert Codegen, genereert de types en getypeerde document nodes, en importeert ze in je applicatiecode.
De grootste waarde is dat je types altijd de API beschrijven die je daadwerkelijk aanroept, niet de code die je niet hoeft te schrijven. Wanneer het schema verandert, vertelt de compiler je of er iets stuk is gegaan zodat je fouten vroeg kunt vangen.
Wil je leren hoe GraphQL wordt gebruikt in een moderne NoSQL-database? Lees dan onze blogpost MongoDB en GraphQL.
Senior Data Scientist, gevestigd in Kroatië. Top Tech-schrijver met meer dan 700 gepubliceerde artikelen en meer dan 10 miljoen weergaven. Auteur van het boek Machine Learning Automation with TPOT.
GraphQL Codegen FAQ’s
Waarvoor wordt GraphQL Codegen gebruikt?⌄
GraphQL Codegen genereert code op basis van een GraphQL-schema en je GraphQL-operaties. De meeste teams gebruiken het om TypeScript-types en getypeerde document nodes voor hun queries en mutaties te krijgen, zodat ze die types niet met de hand hoeven te schrijven en bij te werken. Het kan ook resolvertype’s voor servers genereren en kant-en-klare hooks voor specifieke clients.
Heb ik een draaiende GraphQL-server nodig om Codegen te gebruiken?⌄
Nee. Codegen kan het schema lezen uit een lokaal .graphql-bestand, dus het werkt zonder server. Je hebt alleen een draaiende server nodig als je de sleutel schema naar een URL wijst, omdat Codegen dan het schema via introspectie ophaalt.
Moet ik gegenereerde bestanden naar Git committen?⌄
Dat hangt af van de workflow van je team. Gecommitte bestanden laten je typewijzigingen reviewen in pull requests en graphql-codegen --check gebruiken in CI om verouderde output te detecteren. Als je dat niet nodig hebt, voeg de outputmap toe aan .gitignore en regenereer de bestanden vóór elke build.
Moet ik de clientpreset of individuele plugins gebruiken?⌄
The Guild raadt de clientpreset aan voor de meeste clientapps, omdat die in één setup operatietypes, getypeerde document nodes en fragmentmasking bundelt. Apollo raadt in plaats daarvan de plugin typescript-operations aan, omdat de preset runtimecode en features toevoegt die conflicteren met Apollo Client. Gebruik je Apollo, ga dan voor de plugins. Anders is de preset een goede standaard.
Waarom krijg ik fouten over dubbele declaraties na het updaten van Codegen?⌄
Sinds v6 genereert de plugin typescript-operations zijn eigen enum- en inputtypes. Als je config nog steeds zowel typescript als typescript-operations voor hetzelfde outputbestand vermeldt, declareren beide plugins types zoals Level, en gooit TypeScript fouten over dubbele declaraties. Verwijder de plugin typescript uit dat outputbestand, of verplaats hem naar een apart bestand als je de volledige schematypes nog nodig hebt.
Ontwikkel je Python-vaardigheden voor software-engineering. Schrijf overzichtelijke functies, beheers OOP, datastructuren en algoritmen, en lever goed geteste code af.
Handgeschreven TypeScript-types voor een GraphQL-API zijn verouderd zodra iemand het schema wijzigt.
Stel, een backenddeveloper hernoemt het veld
titleop het typeCoursenaarname. De frontend compileert nog steeds, omdat de handgeschrevenCourse-interface niet weet dat er iets is veranderd, dus de bug verschijnt pas tijdens runtime. In echte applicaties zijn er vaak tientallen queries, mutaties en fragments, dus je ziet hoe dit snel kan escaleren.GraphQL Code Generator, of kortweg GraphQL Codegen, leest je schema en GraphQL-operaties en zet ze om in types, queryhelpers, clientintegraties en andere boilerplate die je anders met de hand zou schrijven. Het wordt meestal gebruikt met TypeScript en populaire clients zoals Apollo en urql. Met één commando houd je je types in sync zodra het schema verandert.
In dit artikel laat ik je zien hoe je GraphQL Codegen opzet in een klein TypeScript-project, hoe je het configureert, de gegenereerde types gebruikt en het automatisch laat draaien als onderdeel van je workflow.
Hoe verhoudt GraphQL zich tot REST? Lees onze Graph QL vs REST: A Complete Guide om de verschillen en voordelen te leren kennen.
Wat is GraphQL Codegen?
GraphQL Codegen is een commandlinetool die GraphQL-definities omzet in applicatiecode.
Het is een open-sourceproject van The Guild, en je installeert het als devdependency in je project. Het verbindt drie dingen:
Het schema vertelt Codegen wat mogelijk is en de operaties vertellen wat je applicatie opvraagt.
Codegen combineert beide, zodat elk gegenereerd type exact overeenkomt met de vorm van het antwoord voor één operatie. Het valideert ook elke operatie tegen het schema. Het hernoemde veld
titleuit de introductie zou de generatie stoppen met een fout zoalsCannot query field "title" on type "Course", en je vangt het voordat de code draait.De output hangt af van je plugins en configuratie. Codegen zelf schrijft geen TypeScript. Plugins doen dat. Zo genereert de plugin
typescriptschematypes, en de plugintypescript-operationsgenereert types voor je queries en mutaties. Er zijn ook plugins voor andere talen, zoals Java en C#, maar dit artikel blijft bij TypeScript.Onthoud wel dat Codegen je GraphQL-server niet vervangt.
Het voert geen queries uit en haalt geen data op. Het leest GraphQL-definities tijdens ontwikkeling en schrijft bestanden. Je server en je GraphQL-client doen de rest.
Hoe GraphQL Codegen werkt
Elke Codegen-setup volgt dezelfde flow: schema + GraphQL-operaties -> Codegen-configuratie -> gegenereerde code.
Diagram van de GraphQL Codegen-werkstroom
Dit is het algemene idee:
Voorzie in een schema: Verwijs Codegen naar een lokaal
.graphql-bestand of een draaiend GraphQL-endpoint, dat Codegen via introspectie leestWijs Codegen naar je operaties: Gebruik globpatronen zoals
src/**/*.tszodat Codegen queries, mutaties en fragments in je code vindtConfigureer plugins en outputdoelen: Vertel Codegen welke bestanden te schrijven en welke plugins elk bestand genereren
Draai Codegen: Voer
npx graphql-codegenuit om het schema te laden, je operaties te valideren en de output te schrijvenGebruik de gegenereerde artefacten: Importeer de gegenereerde types en document nodes in je applicatiecode
Stappen 1 t/m 3 zet je in één configbestand, meestal
codegen.ts. Dit is de kleinste versie ervan voor een cursuscatalogusproject:De preset
clientis een bundel van plugins die in één keer schematypes, operatietypes en getypeerde document nodes genereert. Ik behandel elk hiervan in de secties over setup en configuratie.GraphQL Codegen instellen
De beste manier om Codegen te begrijpen is het op een echt project te draaien.
In deze sectie bouw je vanaf nul een klein cursuscatalogusproject. Het heeft een schema met cursussen en docenten, één query, en een Codegen-config die de query omzet in TypeScript-types. Je hebt alleen Node.js en npm nodig.
Stap 1: Installeer GraphQL Code Generator
Maak een nieuwe map en initialiseer een npm-project:
Codegen heeft een paar packages nodig. Twee gaan in reguliere dependencies, en de rest zijn devdependencies omdat ze alleen tijdens ontwikkeling draaien:
Dit doet elk package:
graphql: De referentie-implementatie van GraphQL voor JavaScript, die Codegen gebruikt om het schema en de operaties te parsen@graphql-typed-document-node/core: Levert het typeTypedDocumentNodedat je gegenereerde code importeert@graphql-codegen/cli: De Codegen-commandlinetool@graphql-codegen/typescript-operations: De plugin die types voor je queries, mutaties en fragments genereert@graphql-codegen/typed-document-node: De plugin die documentobjecten genereert met de bijbehorende typesStap 2: Maak een configuratiebestand
Codegen leest zijn instellingen uit een configbestand in de projectroot. Maak
codegen.tsen zet er voorlopig een lege config in:Je kunt ook
npx graphql-codegen initdraaien om een paar vragen te beantwoorden en een gegenereerd configbestand te krijgen. Ik schrijf het hier met de hand zodat je ziet wat elke instelling doet.Stap 3: Geef de locaties van schema en documenten op
Codegen heeft twee inputs nodig, dus laten we die beide maken.
Sla eerst het schema op als
schema.graphqlin de projectroot:Maak daarna
src/operations/courses.graphqlmet een query die cursussen en hun docenten ophaalt:Wijs Codegen nu naar beide bestanden. De sleutel
schemakrijgt het schemapad, endocumentskrijgt een globpatroon dat je operaties matcht:Stap 4: Kies een outputbestand
De sleutel
generatesvertelt Codegen waar de output moet komen. Elke sleutel daarbinnen is een bestandspad:Codegen maakt de map
src/generated/als die nog niet bestaat.Stap 5: Voeg relevante plugins toe
Een outputbestand zonder plugins is leeg. Voeg de twee plugins toe die je hebt geïnstalleerd:
Als je een oudere tutorial hebt gevolgd, heb je waarschijnlijk ook de plugin
typescriptin deze lijst gezien. Je kunt die nu weglaten, want typescript-operations werkt zelfstandig en genereert alleen Input-, Enum- en Operatietypes die daadwerkelijk gebruikt worden. Als je beide in hetzelfde outputbestand zet op de huidige versies, gooit TypeScript fouten over dubbele declaraties.Stap 6: Draai Codegen
Voeg een npm-script toe zodat je het commando niet hoeft te onthouden:
Draai het vervolgens:
Codegen laadt het schema, valideert de query ertegen en schrijft de output:
Resultaten van Codegen-generatie
Als een operatie verwijst naar een veld dat niet bestaat in het schema, faalt de run hier en worden er geen bestanden geschreven.
Stap 7: Bekijk de gegenereerde output
Open
src/generated/graphql.ts. Dit is wat je ziet:De gegenereerde output
Codegen genereerde vier dingen:
Level: Een string-unie voor de enum, alleen gegenereerd omdat de query hem gebruiktGetCoursesQueryVariables: Het type voor de variabelen die je aan de query doorgeeft, waarbij beide optioneel zijn omdat het schema ze niet als vereist markeertGetCoursesQuery: De vorm van het antwoord, met alleen de velden waar de query om vraagtGetCoursesDocument: De geparste query als een getypeerde document node, met de resultaat- en variabelentypes gekoppeldKijk nog eens naar
GetCoursesQuery. Het bevat geendurationHoursof debiovan de docent, omdat de query er niet om vraagt. Als je in je codecourse.durationHoursprobeert te lezen, krijg je een compileerfout, geenundefinedtijdens runtime.En dat is de hele setup – jij schrijft GraphQL en Codegen schrijft de TypeScript.
GraphQL Codegen configureren
De meeste Codegen-configs die je ziet zijn langer dan die hierboven, maar ze zijn opgebouwd uit dezelfde vier instellingen.
Het configbestand kan
codegen.ts,codegen.ymlofcodegen.jsonzijn. Ik gebruik TypeScript omdat je autocomplete en typechecks op de config zelf krijgt. De instellingen zijn in elk formaat hetzelfde.Schema
De sleutel
schemavertelt Codegen waar je schema staat. Het accepteert een paar brontypes.Een lokaal bestand of een globpatroon werkt wanneer het schema in je repo staat:
Een URL werkt wanneer het schema op een draaiende server staat. Codegen stuurt een introspectiequery naar het endpoint, en je kunt headers doorgeven voor authenticatie:
De URLooptie werkt alleen als de server introspectie aan heeft staan. Veel productie-API’s zetten dat uit, dus voor CI is een schemabestand dat is gecommit in de repo meestal de veiligere keuze.
Documents
De sleutel
documentsvertelt Codegen waar je queries, mutaties, subscriptions en fragments te vinden zijn.Operaties kunnen in
.graphql-bestanden staan of inline in je TypeScript-code. Codegen vindt inline operaties wanneer ze zijn omwikkeld met eengql-tag of gemarkeerd met een/* GraphQL */-commentaar:Om beide bestandstypen te scannen, verbreed je het globpatroon. Voeg een negatief patroon toe zodat Codegen zijn eigen output niet scant:
Geef elke operatie een unieke naam. Codegen bouwt typenames op basis van operatienamen, dus
EnrollStudentwordtEnrollStudentMutationenEnrollStudentMutationVariables.Generates
De sleutel
generateskoppelt outputpaden aan wat erin komt. Je kunt zoveel outputdoelen hebben als nodig, elk met eigen plugins.Stel dat je operatietypes in één bestand wilt en de volledige schematypes in een ander:
Het
config-object binnen een outputdoel geldt alleen voor dat bestand. Hier zorgtuseTypeImportservoor dat het gegenereerde bestandimport typegebruikt, wat sommige buildsetups vereisen. Als jeconfigin de root van het bestand plaatst, geldt het voor elke output.Een outputpad kan ook een map zijn die eindigt op een slash, zoals
"src/gql/". Dat is het formaat dat presets gebruiken, omdat ze meer dan één bestand schrijven.Plugins
Plugins bepalen wat er wordt gegenereerd. Codegen laadt het schema en de documenten, en elke plugin zet die om in een stuk output.
Dit zijn de plugins die je het vaakst ziet in TypeScript-projecten:
typescript-operations: Types voor je queries, mutaties, subscriptions en fragments, plus de enums en inputs die ze gebruikentyped-document-node: Documentobjecten met de resultaat- en variabelentypes gekoppeld, die de meeste GraphQL-clients begrijpentypescript: Types voor elk object, elke enum en input in het schema, of je operaties ze nu gebruiken of niettypescript-resolvers: Typesignatures voor resolverfuncties aan de serverkantEen preset is een bundel van plugins met een verstandige standaardconfig. De preset
clientuit de sectie Hoe het werkt is degene die The Guild aanraadt voor clientapps. Hij bouwt onder de motorkap voort op de verbeterde typescript-operations, zodat je de voordelen krijgt zonder extra setup.Elke plugin heeft zijn eigen configopties, en dat zijn er veel. Je hoeft ze niet vooraf te leren. Begin met de defaults en zoek een optie op wanneer de gegenereerde output niet matcht met wat je code verwacht.
Wat kan GraphQL Codegen genereren?
Wat je uit Codegen haalt, hangt af van de plugins die je kiest.
Hetzelfde schema en dezelfde operaties kunnen platte TypeScript-types opleveren of kant-en-klare clientcode. Dit zijn de outputs die je het vaakst gebruikt.
TypeScript-types
De plugin
typescriptgenereert een type voor elk object, elke enum en input in je schema. Voor de cursuscatalogus ziet het typeCourseer zo uit:Deze types beschrijven het volledige schema, wat ze handig maakt aan de serverkant, in testfixtures en in utilityfuncties die met complete objecten werken.
Maar ze passen minder goed bij clientcode. Een type
Coursezegt dat elk veld bestaat, ook de velden waar je query niet om vroeg.Operatietypes
De plugin
typescript-operationsgenereert twee types per operatie: één voor het resultaat en één voor de variabelen. Het werkt hetzelfde voor queries en subscriptions.Dit genereert het voor een mutatie
EnrollStudent:Het resultatentype matcht de selectieset, veld voor veld. Het variabelentype is
Exact, zodat TypeScript extra of verkeerd gespelde variabelen afwijst.De variabele
courseIdaccepteert zowelstringalsnumberomdat de GraphQL-scalarIDbeide als input accepteert. Sinds v6 is het standaardtypestring | number, wat het juiste type is voor clientgebruik.Getypeerde document nodes
Een gewone
DocumentNodeis een geparste GraphQL-query. Die kent de structuur van de query, maar weet niet wat de query teruggeeft of welke variabelen nodig zijn.Een getypeerde document node heeft beide types erbij. De plugin
typed-document-nodegenereert er één per operatie:Zo kan elke functie die een
TypedDocumentNodeaccepteert het resultaat- en variabelentype afleiden uit alleen het document. Je geeft geen generics met de hand door, en je kunt geen query combineren met de verkeerde types.De meeste moderne GraphQL-clients accepteren getypeerde document nodes, waaronder Apollo Client, urql en graphql-request. Je ziet alle drie later in dit artikel in actie.
Clientspeficieke integraties
Sommige plugins gaan verder en genereren code voor een specifieke client of framework. Bijvoorbeeld:
typescript-react-apollo: Genereert getypeerde React-hooks voor Apollo Clienttypescript-urql: Genereert getypeerde hooks en componenten voor urqltypescript-react-query: Genereert getypeerde hooks voor TanStack Querytypescript-graphql-request: Genereert een getypte SDK met één functie per operatieDit zijn allemaal communityplugins. The Guild heeft ze verhuisd naar een aparte communityrepository, dus hun releasetempo verschilt van de coreplugins.
Je hebt ze ook minder vaak nodig dan vroeger. Wanneer een client getypeerde document nodes ondersteunt, voegen gegenereerde hooks weinig typesafety toe. De documentatie van Apollo raadt bijvoorbeeld aan om de plugin
typescript-operationste gebruiken, die zich richt op alleen types genereren en geen extra runtimecode bevat.In het algemeen begin je met operatietypes en getypeerde document nodes. Voeg daarna pas een clientspecifieke plugin toe als je team de gegenereerde hooks of SDK-functies wil.
GraphQL Codegen met TypeScript
Gegenereerde types zijn alleen nuttig als ze fouten vangen, dus laten we er een paar maken.
Dit voorbeeld breidt het cursuscatalogusproject uit met een tweede query, een kleine helper die die naar de API stuurt, en de code die het resultaat gebruikt. Het gaat uit van een GraphQL-server die het schema implementeert op
http://localhost:4000/graphql.Dit is het deel van het schema dat dit voorbeeld gebruikt:
Twee details zijn hier belangrijk. Het veld
courseretourneertCoursezonder!, dus het isnullwanneer geen cursus overeenkomt met het ID. Debiovan de docent is ook nullable.Maak
src/operations/course.graphqlmet een query die één cursus ophaalt:Draai
npm run codegenopnieuw. Codegen voegt twee nieuwe types toe aansrc/generated/graphql.ts:Inhoud van het bestand graphql.ts
De nullability uit het schema blijft behouden.
coursekannullzijn,biokannullzijn, enidis vereist omdat de query die alsID!declareert.Nu de applicatiecode. Maak
src/execute.tsmet een helper die elk getypt document naar de API stuurt:De helper weet niets over cursussen. Hij haalt beide types uit het document dat je doorgeeft, en de functie
print()zet het document terug om in een querystring voor het request.Gebruik hem vervolgens in
src/course-details.ts:De functie
formatCourse()haalt zijn parametertype uit het gegenereerde querytype.NonNullableverwijdert denull-case, omdat de functie pas draait na deif-check.Het voorbeeld gebruikt top-level
await, dus zet"type": "module"inpackage.jsonen draai het metnpx tsx src/course-details.ts:Geslaagde call naar een GraphQL-mockserver
Dit gaat er nu van uit dat je een GraphQL-server hebt draaien. Hier is een mockserver die ik gebruikte:
Probeer het nu te breken. Open
src/course-details.tsen vervang alles onder de functieformatCourse()door drie fouten die handgeschreven types vaak doorlaten:Typecheck vervolgens het project:
TypeScript vangt alle drie voordat de code draait:
Fouten gedetecteerd door TypeScript
Zo reduceert Codegen mismatches tussen de frontend en de API. De types komen uit hetzelfde schema dat de server gebruikt, dus ze kunnen geen velden beschrijven die niet bestaan of nulls missen die de server kan teruggeven.
En de bescherming stopt niet na de eerste run. Stel dat het backendteam
durationHoursnullable maakt. Je regenereert, het type verandert naarnumber | null, en TypeScript wijst elke regel aan die van een number uitging.GraphQL Codegen met GraphQL-clients
Codegen verstuurt geen requests. Dat is de taak van je GraphQL-client.
De gegenereerde getypeerde document nodes zijn het overdrachtspunt tussen beide. Je geeft ze door aan de client, en de client leidt de types af. De voorbeelden hieronder gebruiken hetzelfde bestand
src/generated/graphql.tsen de mock-API uit de vorige sectie, dus laatnpx tsx mock/server.tsin een aparte terminal draaien.GraphQL Codegen met Apollo
Installeer Apollo Client en diens peer dependency
rxjs:Het voorbeeld draait ook de mutatie
EnrollStudent. Sla die op alssrc/operations/enroll.graphql:De documentatie van Apollo raadt ook twee configopties voor Codegen aan, omdat Apollo Client altijd
__typename-velden opneemt maar die niet toevoegt aan roottypes. Voeg ze toe aan het outputdoel incodegen.ts:Met deze opties krijgt elk object in de gegenereerde resultatentypes een verplicht veld
__typename, zoals__typename: 'Course'. Dat matcht wat de cache van Apollo teruggeeft.Draai
npm run codegenopnieuw om de nieuwe mutatie en config te detecteren.Apollo Client accepteert getypeerde document nodes in
query()enmutate(). Sla dit op alssrc/apollo.ts:Het object
datais getypt alsGetCoursesQuery | undefined, en TypeScript controleertvariablestegenGetCoursesQueryVariables. De mutatie werkt hetzelfde metEnrollStudentMutationen de bijbehorende variabelen.Draai het met
npx tsx src/apollo.ts:Apollo-output
De eerste regel komt van de query, omdat dat de enige beginnerscursus is. De tweede komt van de mutatie, die de titel retourneert van de cursus waarvoor de student zich inschreef.
De React-hooks, zoals
useQuery()enuseMutation(), leiden types op dezelfde manier af uit getypeerde document nodes.GraphQL Codegen met urql
Installeer het corepakket van urql:
urql werkt out of the box met getypeerde document nodes. Geef het document als eerste argument door aan
query()insrc/urql.ts:Het tweede argument is getypt als de queryvariabelen, en
result.datais getypt als het queryresultaat.Draai het met
npx tsx src/urql.ts:Urql-output
De frameworkbindings, zoals
useQuery()in het pakketurqlvoor React, accepteren ook getypeerde document nodes.GraphQL Codegen met andere clients
Je hebt geen volwaardige client nodig om getypte resultaten te krijgen.
De client
graphql-requestis een minimale client die één request verstuurt en de data teruggeeft. Installeer hem met het volgende commando:Hij leidt types af uit getypeerde document nodes net als Apollo en urql. Sla dit op als
src/graphql-request.ts:Draai het met
npx tsx src/graphql-request.ts:Output van GraphQL-request
Hetzelfde idee werkt met TanStack Query. Die stuurt zelf geen GraphQL-requests, dus je roept graphql-request aan of de helper
execute()uit de vorige sectie binnen de queryfunctie, en het resultatentype loopt door naar je code.En als je client helemaal geen getypeerde document nodes ondersteunt, kun je nog steeds de platte operatietypes gebruiken. Importeer
GetCourseQueryenGetCourseQueryVariablesen geef ze door als generics. Dat is wat meer handwerk, maar de types komen nog steeds uit het schema.GraphQL Codegen automatisch draaien
Gegenereerde types helpen alleen als ze overeenkomen met het huidige schema en de huidige operaties.
Als je vergeet Codegen opnieuw te draaien na een wijziging, beschrijven de types code die niet meer bestaat. Dat is hetzelfde driftprobleem als bij handgeschreven types, alleen met extra stappen. De oplossing is de handmatige stap uit de workflow halen.
npm-scripts
Begin met een paar scripts in
package.json, zodat iedereen in het team Codegen op dezelfde manier draait:De rest van deze sectie behandelt waar elk script voor is.
Watch-modus
De watch-modus draait Codegen opnieuw telkens wanneer een gevolgd bestand wijzigt. Het heeft het package
@parcel/watchernodig, dat Codegen niet voor je installeert:Als je de installatie overslaat, draait Codegen één keer en print het
Failed to import @parcel/watcherin plaats van te watchen.De watch-modus volgt zowel je operaties als een lokaal schemabestand. Als je een veld toevoegt aan
course.graphql, verschijnt het nieuwe veld een seconde later inGetCourseQuery. Als jedurationHoursnullable maakt inschema.graphql, verandert het type innumber | null, en je editor markeert elke regel die van een number uitging.Laat het tijdens ontwikkeling draaien in een terminal naast je devserver.
Genereren vóór builds
npm draait een script genaamd
prebuildvóórbuild. Met de bovenstaande scripts regenereertnpm run buildeerst de types en draait pas daarna de TypeScript-compiler.Zo draait een build nooit tegen verouderde types, zelfs niet als iemand vergat Codegen te draaien na het pullen van wijzigingen.
CI/CD
De vlag
--checkdraait Codegen in dry-runmodus. Het schrijft geen bestanden, vergelijkt wat het zou genereren met wat op schijf staat en sluit af met code 1 als er iets verschilt.Hier is een minimale GitHub Actions-workflow die het gebruikt:
De stap
codegen:checkheeft alleen zin als je gegenereerde bestanden commit naar de repo. Zo niet, laat die stap dan weg, wantnpm run buildregenereert alles toch via de hookprebuild.Regenereer bij schemawijzigingen
Operaties wijzigen in je repo, dus watch-modus en
prebuilddekken die af. Schemawijzigingen zijn lastiger, omdat die meestal van een ander team komen.Hoe je ze afhandelt, hangt af van waar het schema staat:
codegen:checkin CI faalt zodra het schema van de server niet meer matcht met je gecommitte outputDe URLooptie heeft één addertje. De watch-modus reageert op bestandswijzigingen, dus hij merkt niet wanneer een extern schema verandert. Je ziet die wijzigingen pas bij de volgende handmatige run of CI-job.
GraphQL Codegen vs handgeschreven types
Beide benaderingen geven je TypeScript-types voor GraphQL-data, maar er zijn enkele verschillen om te kennen.
Handgeschreven types
Met handgeschreven types lees je het schema en schrijf je zelf overeenkomende interfaces.
Dat geeft je volledige controle. Je kunt types noemen zoals jij wilt, een paar operaties samenvoegen tot één gedeeld type, of hulptyperingen toevoegen die het schema niet heeft.
Maar het is handwerk. Elk nieuw veld of hernoemd argument betekent dat je het bijbehorende type met de hand moet zoeken en bijwerken. En niets waarschuwt je als je er één mist.
Daar komt drift vandaan. De interface
Courseuit de introductie compileerde nog steeds nadat de backendtitlehad hernoemd, omdat TypeScript je code alleen tegen je eigen types controleert, niet tegen de API.Gegenereerde types
Gegenereerde types komen uit hetzelfde schema dat de server gebruikt, dus ze zijn per ontwerp gesynchroniseerd met je GraphQL-definities. Een schemawijziging plus een Codegen-run werkt alle getroffen types in één keer bij.
Je schrijft ook veel minder code. Het cursuscatalogusproject heeft drie operaties en nul handgeschreven types daarvoor.
En je krijgt vrijwel gratis schema-gedreven ontwikkeling. Je wijzigt het schema of een operatie, regenereert, en de compiler geeft je een lijst van alles wat moet worden aangepast.
Maar onthoud: Codegen weerspiegelt alleen wat je erin stopt.
Als het schema elk veld als nullable markeert, zitten je gegenereerde types vol met
| null-checks. Als een operatie 40 velden ophaalt terwijl de pagina er vijf nodig heeft, heeft het gegenereerde type 40 velden.Hier is een korte samenvatting van de verschillen:
Codegen vergeleken met handgeschreven types
GraphQL Codegen vs. GraphQL-introspectie
De twee worden vaak door elkaar gehaald omdat Codegen vaak introspectie gebruikt. Toch lossen ze verschillende problemen op.
Introspectie is een functie van de GraphQL-specificatie. Elke GraphQL-server kan queries over zijn eigen schema beantwoorden via speciale velden zoals
__schemaen__type. Het resultaat is een JSON-beschrijving van elk type, veld en argument dat de API aanbiedt.In gewone taal beantwoordt introspectie de vraag "Hoe ziet deze API eruit?"
Codegen beantwoordt de vraag "Welke code heeft mijn applicatie nodig?" Het neemt schema-informatie en je operaties, en schrijft TypeScript-types en getypeerde document nodes.
Wanneer je
schemainstelt op een URL incodegen.ts, verstuurt Codegen een introspectiequery naar die server om het schema op te halen. Met een lokaal.graphql-bestand gebeurt er helemaal geen introspectie.Codegen kan ook een introspectieresultaat als output produceren. De plugin
@graphql-codegen/introspectionschrijft het schema als introspectie-JSON, wat sommige tools, zoals de Graphcache van urql, gebruiken voor schema-bewuste caching.Codegen vergeleken met introspectie
Veelvoorkomende problemen met GraphQL Codegen
De meeste Codegen-fouten komen neer op één van vier problemen.
Gegenereerde types ontbreken
Codegen draait zonder fouten, maar het type dat je verwacht staat niet in het outputbestand.
Controleer deze drie dingen in volgorde:
Schema: Als het type niet bestaat in het schema dat Codegen laadt, kan het niet worden gegenereerd, dus open het schemabestand of draai de introspectiequery zelf en bevestig dat het er is
Documents: Operatietypes bestaan alleen voor operaties die Codegen heeft gevonden, dus als het bestand met je query niet wordt gematcht door het globpatroon
documents, ontbreken de typesPlugins: Sinds v6 genereert
typescript-operationsalleen de enums en inputs die je operaties gebruiken, dus als je een volledig schematype zoalsCoursenodig hebt, voeg de plugintypescripttoe aan een apart outputbestandAls je een plugin gebruikt die je niet hebt geïnstalleerd, faalt Codegen met een duidelijke melding:
Codegen kan geen operaties vinden
Deze fout betekent dat het globpatroon
documentsgeen enkel bestand met een operatie heeft gematcht:Controleer of de extensie in het globpatroon overeenkomt met je bestanden. Een patroon
.gqlvindt geen.graphql-bestanden, en een patroonsrc/**/*.graphqlvindt geen operaties inline in.ts-bestanden.Controleer voor inline operaties ook de tag. Codegen vindt alleen template literals die zijn omwikkeld met
gqlof gemarkeerd met een/* GraphQL */-commentaar. Een gewone template literal met een query erin is onzichtbaar.Als je
ignoreNoDocuments: trueinstelt, toont Codegen deze fout niet en genereert het een output zonder operatietypes. Die optie is handig in een gloednieuw project, maar kan later een kapot globpatroon verbergen.Gegenereerde types zijn verouderd
De types compileren, maar weerspiegelen niet de laatste wijziging in een operatie of het schema.
Codegen draait niet uit zichzelf. Draai het opnieuw na elke wijziging aan een
.graphql-bestand, een inline operatie, het schema ofcodegen.ts. Tijdens ontwikkeling doetnpm run codegen:watchdat voor je.Als de types in CI verouderd zijn, commit de geregenereerde bestanden of laat de hook
prebuildze opnieuw genereren vóór de build.Gegenereerde types komen niet overeen met de API
De types compileren, maar de data van de server heeft op runtime een andere vorm.
Dat betekent bijna altijd dat Codegen en je app met verschillende schema’s praten. Bijvoorbeeld: Codegen leest een lokaal
schema.graphqldat een week oud is, terwijl de app een productie-API aanroept die sindsdien is veranderd.Controleer waar de sleutel
schemanaar wijst. Als het een bestand is, vergelijk het met de API die je app aanroept en werk het bij. Als het een URL is, zorg dat het dezelfde omgeving is die je app gebruikt, niet een stagingserver met een nieuwer of ouder schema.Genereer vervolgens opnieuw en bekijk de diff. Als een operatief bestand veranderd is maar het gegenereerde bestand niet, staat de operatie waarschijnlijk buiten het globpatroon
documents.Best practices voor GraphQL Codegen
Codegen heeft niet veel configuratie nodig om goed te werken. Deze practices houden het zo wanneer het project groeit:
Houd het schema en de gegenereerde bestanden in sync: Draai de watch-modus tijdens ontwikkeling en
prebuildvóór builds, zodat niemand met types van een ouder schema werktGenereer operatiespecifieke types: Gebruik
typescript-operationsvoor clientcode omdat die exact matchen wat elke query ophaaltCommit gegenereerde bestanden alleen als je workflow ze nodig heeft: Gecommitte bestanden laten je typewijzigingen reviewen in pull requests en
--checkdraaien in CI, en als je team dat niet nodig heeft, voeg de outputmap toe aan.gitignoreen genereer bij elke buildHoud de config kort: Eén outputbestand met twee plugins dekt de meeste clientprojecten; elke extra optie is weer iets dat de volgende developer moet begrijpen voor hij iets aanpast
Draai Codegen in CI bij elke push: Een stap
--checkof een hookprebuildvangt de wijzigingen op die iemand lokaal vergat te regenererenBewerk nooit gegenereerde bestanden met de hand: De volgende Codegen-run overschrijft je wijzigingen, dus fix het schema, de operatie of de config in plaats daarvan
Conclusie
GraphQL Codegen neemt het meest repetitieve deel van GraphQL-ontwikkeling over: schema’s en operaties met de hand omzetten in TypeScript-types.
De workflow blijft hetzelfde, hoe groot het project ook wordt. Je definieert het schema en de operaties, configureert Codegen, genereert de types en getypeerde document nodes, en importeert ze in je applicatiecode.
De grootste waarde is dat je types altijd de API beschrijven die je daadwerkelijk aanroept, niet de code die je niet hoeft te schrijven. Wanneer het schema verandert, vertelt de compiler je of er iets stuk is gegaan zodat je fouten vroeg kunt vangen.
Wil je leren hoe GraphQL wordt gebruikt in een moderne NoSQL-database? Lees dan onze blogpost MongoDB en GraphQL.