GraphQL Codegen: cómo generar código con tipos seguros desde un esquema GraphQL
Guía práctica de GraphQL Code Generator que cubre configuración inicial y avanzada, tipos de TypeScript y typed document nodes, integración con Apollo, urql y graphql-request, y automatización con watch mode y CI.
Los tipos de TypeScript escritos a mano para una API GraphQL se quedan obsoletos en cuanto alguien cambia el esquema.
Imagina que una persona del backend renombra el campo title del tipo Course a name. El frontend sigue compilando porque la interfaz Course escrita a mano no sabe que algo ha cambiado, así que el fallo solo aparece en tiempo de ejecución. En aplicaciones reales suele haber decenas de consultas, mutaciones y fragmentos, así que puedes ver lo rápido que esto se descontrola.
GraphQL Code Generator, o GraphQL Codegen, lee tu esquema y tus operaciones GraphQL y las convierte en tipos, utilidades para consultas, integraciones de cliente y otros "boilerplates" que de otro modo escribirías a mano. Se usa sobre todo con TypeScript y clientes populares como Apollo y urql. Con un solo comando vuelves a sincronizar tus tipos siempre que cambie el esquema.
En este artículo, verás cómo configurar GraphQL Codegen en un proyecto pequeño de TypeScript, cómo ajustarlo, cómo usar los tipos generados y cómo ejecutarlo automáticamente dentro de tu flujo de trabajo.
GraphQL Codegen es una herramienta de línea de comandos que transforma definiciones de GraphQL en código de aplicación.
Es un proyecto open source de The Guild, y lo instalas como dependencia de desarrollo. Conecta tres piezas:
Esquema GraphQL: el contrato entre el servidor y sus clientes, con cada tipo, campo y argumento que expone la API
Operaciones GraphQL: las consultas, mutaciones, suscripciones y fragmentos que tu aplicación envía a la API
Código generado: los tipos y utilidades que Codegen escribe a partir del esquema y tus operaciones
El esquema le dice a Codegen qué es posible y las operaciones le dicen qué pide tu aplicación.
Codegen combina ambos, de modo que cada tipo generado encaja exactamente con la forma de la respuesta de una operación. Además, valida cada operación frente al esquema. El campo title renombrado del ejemplo inicial detendría la generación con un error como Cannot query field "title" on type "Course", y lo detectarías antes de ejecutar el código.
La salida depende de tus plugins y de la configuración. Codegen en sí no escribe TypeScript. Lo hacen los plugins. Por ejemplo, el plugin typescript genera tipos del esquema, y typescript-operations genera tipos para tus consultas y mutaciones. Hay plugins para otros lenguajes, como Java y C#, pero aquí nos quedamos en TypeScript.
Importante: Codegen no sustituye a tu servidor GraphQL.
No resuelve consultas ni obtiene datos. Lee definiciones de GraphQL durante el desarrollo y escribe archivos. Tu servidor y tu cliente GraphQL hacen el resto.
Cómo funciona GraphQL Codegen
Toda configuración de Codegen sigue el mismo flujo: esquema + operaciones GraphQL -> configuración de Codegen -> código generado.
Diagrama del flujo de trabajo de GraphQL Codegen
La idea general es esta:
Proporciona un esquema: señala a Codegen un archivo .graphql local o un endpoint GraphQL en ejecución, que Codegen lee mediante introspección
Indica a Codegen tus operaciones: usa patrones glob como src/**/*.ts para que Codegen encuentre consultas, mutaciones y fragmentos en tu código
Configura plugins y destinos de salida: dile a Codegen qué archivos escribir y qué plugins generan cada uno
Ejecuta Codegen: ejecuta npx graphql-codegen para cargar el esquema, validar tus operaciones y escribir la salida
Usa los artefactos generados: importa los tipos y los document nodes generados en tu código de aplicación
Los pasos del 1 al 3 van en un único archivo de configuración, normalmente codegen.ts. Aquí tienes la versión mínima para un proyecto de catálogo de cursos:
importtype{ CodegenConfig }from"@graphql-codegen/cli";const config: CodegenConfig ={// Paso 1: de dónde viene el esquema
schema:"schema.graphql",// Paso 2: dónde están tus operaciones
documents:["src/**/*.ts"],// Paso 3: qué generar y dónde escribirlo
generates:{"./src/gql/":{ preset:"client"},},};exportdefault config;Con la tecnología de
El preset client es un paquete de plugins que genera tipos de esquema, tipos de operaciones y typed document nodes de una sola vez. Verás cada uno en las secciones de configuración y puesta en marcha.
Cómo configurar GraphQL Codegen
La mejor forma de entender Codegen es ejecutarlo en un proyecto real.
En esta sección, construirás desde cero un pequeño proyecto de catálogo de cursos. Incluye un esquema con cursos e instructores, una consulta y una configuración de Codegen que convierte esa consulta en tipos de TypeScript. Solo necesitas Node.js y npm.
Paso 1: instala GraphQL Code Generator
Crea una carpeta nueva e inicializa un proyecto npm:
Codegen necesita varios paquetes. Dos van en dependencias normales y el resto como dependencias de desarrollo, porque solo se usan durante el desarrollo:
npminstall graphql @graphql-typed-document-node/core
npminstall-D typescript @graphql-codegen/cli @graphql-codegen/typescript-operations @graphql-codegen/typed-document-nodeCon la tecnología de
Para qué sirve cada paquete:
graphql: la implementación de referencia de GraphQL para JavaScript, que Codegen usa para analizar el esquema y las operaciones
@graphql-typed-document-node/core: proporciona el tipo TypedDocumentNode que importará tu código generado
@graphql-codegen/cli: la herramienta de línea de comandos de Codegen
@graphql-codegen/typescript-operations: el plugin que genera tipos para tus consultas, mutaciones y fragmentos
@graphql-codegen/typed-document-node: el plugin que genera objetos de documento con los tipos asociados
Paso 2: crea un archivo de configuración
Codegen lee su configuración desde un archivo en la raíz del proyecto. Crea codegen.ts con una configuración vacía por ahora:
importtype{ CodegenConfig }from"@graphql-codegen/cli";const config: CodegenConfig ={};exportdefault config;Con la tecnología de
También puedes ejecutar npx graphql-codegen init para responder unas preguntas y obtener un archivo de config generado. Aquí lo escribo a mano para que veas qué hace cada ajuste.
Paso 3: indica las ubicaciones del esquema y los documentos
Codegen necesita dos entradas, así que vamos a crear ambas.
Primero, guarda el esquema como schema.graphql en la raíz del proyecto:
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!
}Con la tecnología de
Luego, crea src/operations/courses.graphql con una consulta que trae cursos y sus instructores:
query GetCourses($level: Level, $limit: Int) {
courses(level: $level, limit: $limit) {
id
title
level
instructor {
name
}
}
}Con la tecnología de
Ahora apunta Codegen a ambos archivos. La clave schema acepta la ruta del esquema, y documents un patrón glob que encuentre tus operaciones:
const config: CodegenConfig ={
schema:"schema.graphql",
documents:["src/**/*.graphql"],};Con la tecnología de
Paso 4: elige un archivo de salida
La clave generates indica a Codegen dónde escribir la salida. Cada clave dentro es una ruta de archivo:
const config: CodegenConfig ={
schema:"schema.graphql",
documents:["src/**/*.graphql"],
generates:{"src/generated/graphql.ts":{},},};Con la tecnología de
Codegen crea la carpeta src/generated/ si no existe.
Paso 5: añade los plugins necesarios
Un archivo de salida sin plugins estará vacío. Añade los dos plugins que instalaste:
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;Con la tecnología de
Si seguiste un tutorial antiguo, habrás visto también el plugin typescript. Puedes quitarlo ahora: typescript-operations funciona por sí solo y solo genera tipos de Input, Enum y Operación que realmente se usan. Si pones ambos en el mismo archivo de salida con las versiones actuales, TypeScript lanza errores por declaraciones duplicadas.
Paso 6: ejecuta Codegen
Añade un script de npm para no tener que recordar el comando:
Codegen carga el esquema, valida la consulta contra él y escribe la salida:
Resultados de la generación con Codegen
Si una operación hace referencia a un campo que no existe en el esquema, la ejecución fallará aquí y no se escribirá ningún archivo.
Paso 7: inspecciona la salida generada
Abre src/generated/graphql.ts. Verás algo como esto:
La salida generada
Codegen generó cuatro elementos:
Level: una unión de cadenas para el enum, generada solo porque la consulta lo usa
GetCoursesQueryVariables: el tipo para las variables que pasas a la consulta, donde ambas son opcionales porque el esquema no las marca como obligatorias
GetCoursesQuery: la forma de la respuesta, con solo los campos que solicita la consulta
GetCoursesDocument: la consulta parseada como typed document node, con los tipos de resultado y variables adjuntos
Fíjate de nuevo en GetCoursesQuery. No incluye durationHours ni el bio del instructor, porque la consulta no los pide. Si intentas leer course.durationHours en tu código, obtendrás un error de compilación, no un undefined en tiempo de ejecución.
Y eso es toda la puesta en marcha: tú escribes GraphQL y Codegen escribe TypeScript.
Cómo ajustar la configuración de GraphQL Codegen
La mayoría de configs de Codegen que verás son más largas que la anterior, pero se basan en los mismos cuatro ajustes.
El archivo de config puede ser codegen.ts, codegen.yml o codegen.json. Uso TypeScript porque obtienes autocompletado y tipos en la propia configuración. Los ajustes son iguales en cualquier formato.
Schema
La clave schema indica a Codegen dónde está tu esquema. Acepta varios tipos de origen.
Un archivo local o un patrón glob funcionan cuando el esquema está en tu repositorio:
schema:"schema.graphql",// o, si el esquema está dividido en varios archivos
schema:"schema/**/*.graphql",Con la tecnología de
Una URL funciona cuando el esquema está en un servidor en ejecución. Codegen envía una consulta de introspección al endpoint, y puedes pasar cabeceras para autenticarte:
schema:[{"https://api.example.com/graphql":{
headers:{ Authorization: Bearer ${process.env.API_TOKEN}},},},],Con la tecnología de
La opción de URL solo funciona si el servidor tiene la introspección activada. Muchas APIs en producción la desactivan, así que para CI suele ser más seguro un archivo de esquema en el repo.
Documents
La clave documents le dice a Codegen dónde encontrar tus consultas, mutaciones, suscripciones y fragmentos.
Las operaciones pueden ir en archivos .graphql o inline en tu código TypeScript. Codegen encuentra operaciones inline cuando están envueltas en una etiqueta gql o marcadas con un comentario /* GraphQL */:
const EnrollStudent =/* GraphQL */
mutation EnrollStudent($courseId:ID!, $studentEmail: String!){enrollStudent(courseId: $courseId, studentEmail: $studentEmail){
id
course {
title
}}};Con la tecnología de
Para escanear ambos tipos de archivo, amplía el glob. Añade un patrón negado para que Codegen no escanee su propia salida:
Pon un nombre único a cada operación. Codegen construye los nombres de tipos a partir del nombre de la operación, así que EnrollStudent se convierte en EnrollStudentMutation y EnrollStudentMutationVariables.
Generates
La clave generates mapea rutas de salida con lo que irá en ellas. Puedes tener tantas salidas como necesites, cada una con sus plugins.
Imagina que quieres los tipos de operaciones en un archivo y los tipos completos del esquema en otro:
generates:{"src/generated/graphql.ts":{
plugins:["typescript-operations","typed-document-node"],
config:{
useTypeImports:true,},},"src/generated/schema-types.ts":{
plugins:["typescript"],},},Con la tecnología de
El objeto config dentro de una salida se aplica solo a ese archivo. Aquí, useTypeImports hace que el archivo generado use import type, que algunos entornos necesitan. Si pones config en la raíz de la config, se aplica a todas las salidas.
Una ruta de salida también puede ser una carpeta que termine en barra, como "src/gql/". Es el formato que usan los presets, ya que escriben más de un archivo.
Plugins
Los plugins deciden qué se genera. Codegen carga el esquema y los documentos, y cada plugin los convierte en una parte de la salida.
Estos son los plugins que más verás en proyectos TypeScript:
typescript-operations: tipos para consultas, mutaciones, suscripciones y fragmentos, además de los enums e inputs que utilizan
typed-document-node: objetos documento con los tipos de resultado y variables adjuntos, que la mayoría de clientes GraphQL entienden
typescript: tipos para cada objeto, enum e input del esquema, los use o no tu código
typescript-resolvers: firmas de tipo para funciones resolver en el lado servidor
Un preset es un paquete de plugins con una config sensata por defecto. El preset client de la sección Cómo funciona es el que The Guild recomienda para apps cliente. Se apoya en el typescript-operations mejorado, así que obtienes sus ventajas sin configuración extra.
Cada plugin tiene sus propias opciones, y hay muchas. No necesitas aprendértelas de memoria. Empieza con los valores por defecto y busca una opción cuando la salida generada no encaje con lo que espera tu código.
¿Qué puede generar GraphQL Codegen?
Lo que obtienes de Codegen depende de los plugins que elijas.
Con el mismo esquema y operaciones puedes generar desde tipos de TypeScript planos hasta código listo para clientes específicos. Estos son los outputs más comunes.
Tipos de TypeScript
El plugin typescript genera un tipo para cada objeto, enum e input del esquema. Para el catálogo de cursos, el tipo Course se ve así:
exporttypeCourse={
__typename?:'Course';
durationHours: Scalars['Int']['output'];
id: Scalars['ID']['output'];
instructor: Instructor;
level: Level;
title: Scalars['String']['output'];};Con la tecnología de
Estos tipos describen el esquema completo, lo que los hace útiles en el servidor, en datos de prueba y en utilidades que trabajan con objetos completos.
Pero no encajan bien en código cliente. Un tipo Course dice que todos los campos existen, incluso los que tu consulta no pidió.
Tipos de operaciones
El plugin typescript-operations genera dos tipos por operación: uno para el resultado y otro para las variables. Funciona igual para consultas y suscripciones.
Esto es lo que genera para la mutación EnrollStudent:
exporttypeEnrollStudentMutationVariables= Exact<{
courseId:string|number;
studentEmail:string;}>;exporttypeEnrollStudentMutation={ enrollStudent:{ id:string, course:{ title:string}}};Con la tecnología de
El tipo de resultado refleja el selection set, campo a campo. El tipo de variables es Exact, así que TypeScript rechaza variables extra o con errores tipográficos.
La variable courseId acepta string y number porque el escalar ID de GraphQL acepta ambos como entrada. Desde la v6, el tipo por defecto es string | number, que es lo correcto en clientes.
Typed document nodes
Un DocumentNode normal es una consulta GraphQL parseada. Conoce la estructura de la consulta, pero no sabe qué devuelve ni qué variables acepta.
Un typed document node lleva ambos tipos consigo. El plugin typed-document-node genera uno por operación:
exportconst GetCoursesDocument ={/* ... */}asunknownas DocumentNode<GetCoursesQuery, GetCoursesQueryVariables>;Con la tecnología de
Así, cualquier función que acepte un TypedDocumentNode puede inferir los tipos de resultado y variables a partir del propio documento. No pasas genéricos a mano y no puedes combinar una consulta con tipos incorrectos.
La mayoría de clientes GraphQL modernos aceptan typed document nodes, incluidos Apollo Client, urql y graphql-request. Verás los tres en acción más adelante.
Integraciones específicas de cliente
Algunos plugins van más allá y generan código para un cliente o framework concreto. Por ejemplo:
typescript-react-apollo: genera hooks tipados de React para Apollo Client
typescript-urql: genera hooks y componentes tipados para urql
typescript-react-query: genera hooks tipados para TanStack Query
typescript-graphql-request: genera un SDK tipado con una función por operación
Todos estos son plugins de la comunidad. The Guild los trasladó a un repositorio comunitario, por lo que su cadencia de lanzamientos difiere de los plugins core.
Además, hoy en día los necesitas menos. Cuando un cliente acepta typed document nodes, los hooks generados no añaden mucha más seguridad de tipos. La propia documentación de Apollo, por ejemplo, recomienda usar el plugin typescript-operations, que se centra en generar tipos y no incluye código de runtime adicional.
En general, empieza con tipos de operaciones y typed document nodes. Luego añade un plugin específico de cliente solo si tu equipo quiere los hooks o funciones de SDK generados.
GraphQL Codegen con TypeScript
Los tipos generados solo importan si detectan errores, así que vamos a provocarlos.
Este ejemplo amplía el proyecto del catálogo con una segunda consulta, un pequeño helper que la envía a la API y el código que usa el resultado. Asume un servidor GraphQL que implementa el esquema en http://localhost:4000/graphql.
Esta es la parte del esquema que usa el ejemplo:
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
}Con la tecnología de
Aquí importan dos detalles. El campo course devuelve Course sin !, así que es null cuando ningún curso coincide con el ID. El bio del instructor también puede ser nulo.
Crea src/operations/course.graphql con una consulta que trae un curso:
query GetCourse($id: ID!) {
course(id: $id) {
title
durationHours
instructor {
name
bio
}
}
}Con la tecnología de
Ejecuta npm run codegen de nuevo. Codegen añade dos tipos nuevos a src/generated/graphql.ts:
Contenido del archivo graphql.ts
La anulabilidad del esquema se mantiene. course puede ser null, bio puede ser null, e id es obligatorio porque la consulta lo declara como ID!.
Ahora el código de aplicación. Crea src/execute.ts con un helper que envía cualquier documento tipado a la API:
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;}Con la tecnología de
El helper no sabe nada de cursos. Obtiene ambos tipos del documento que le pasas, y la función print() convierte el documento de nuevo en una cadena de consulta para la petición.
Después úsalo en 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");}Con la tecnología de
La función formatCourse() toma su tipo de parámetro del tipo de la consulta generada. NonNullable elimina el caso null, porque la función solo se ejecuta tras el if.
El ejemplo usa await a nivel superior, así que pon "type": "module" en package.json y ejecútalo con npx tsx src/course-details.ts:
Llamada correcta a un servidor GraphQL simulado
Esto asume que tienes un servidor GraphQL ejecutándose. Aquí tienes uno simulado que utilicé:
Ahora intenta romperlo. Abre src/course-details.ts y sustituye todo lo que hay debajo de la función formatCourse() por tres errores que los tipos escritos a mano suelen dejar pasar:
// Falta la variable id obligatoriaawaitexecute(GetCourseDocument,{});const{ course }=awaitexecute(GetCourseDocument,{ id:"c1"});// Leer un campo que la consulta no pideconsole.log(course?.level);// Olvidar que course puede ser nullconsole.log(course.title);Con la tecnología de
TypeScript detecta los tres errores antes de ejecutar el código:
Errores detectados por TypeScript
Así reduce Codegen los desajustes entre el frontend y la API. Los tipos vienen del mismo esquema que usa el servidor, así que no pueden describir campos que no existen ni pasar por alto nulls que el servidor podría devolver.
Y la protección no termina tras la primera ejecución. Imagina que el equipo de backend hace durationHours anulable. Regeneras, el tipo cambia a number | null, y TypeScript te señala cada línea que asumía un número.
GraphQL Codegen con clientes GraphQL
Codegen no envía peticiones. Eso le toca a tu cliente GraphQL.
Los typed document nodes generados son el punto de traspaso entre ambos. Se los pasas al cliente y el cliente infiere los tipos. Los ejemplos siguientes usan el mismo src/generated/graphql.ts y la API simulada de la sección anterior, así que mantén npx tsx mock/server.ts ejecutándose en otra terminal.
El ejemplo también ejecuta la mutación EnrollStudent. Guárdala como src/operations/enroll.graphql:
mutation EnrollStudent($courseId: ID!, $studentEmail: String!) {
enrollStudent(courseId: $courseId, studentEmail: $studentEmail) {
id
course {
title
}
}
}Con la tecnología de
La documentación de Apollo también recomienda dos opciones de config para Codegen, ya que Apollo Client siempre incluye los campos __typename pero no los añade a los tipos raíz. Añádelas al destino de salida en codegen.ts:
"src/generated/graphql.ts":{
plugins:["typescript-operations","typed-document-node"],
config:{
nonOptionalTypename:true,
skipTypeNameForRoot:true,},},Con la tecnología de
Con estas opciones, cada objeto de los tipos de resultado generados lleva un campo __typename obligatorio, como __typename: 'Course'. Eso coincide con lo que devuelve la caché de Apollo.
Ejecuta npm run codegen otra vez para detectar la nueva mutación y configuración.
Apollo Client acepta typed document nodes en query() y mutate(). Guarda esto como 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);Con la tecnología de
El objeto data está tipado como GetCoursesQuery | undefined, y TypeScript comprueba variables contra GetCoursesQueryVariables. La mutación funciona igual con EnrollStudentMutation y sus variables.
Ejecútalo con npx tsx src/apollo.ts:
Salida de Apollo
La primera línea viene de la consulta, ya que es el único curso para principiantes. La segunda viene de la mutación, que devuelve el título del curso en el que se ha matriculado el alumno.
Los hooks de React, como useQuery() y useMutation(), infieren los tipos a partir de typed document nodes del mismo modo.
Infiere tipos a partir de typed document nodes igual que Apollo y urql. Guarda esto como 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);Con la tecnología de
Ejecútalo con npx tsx src/graphql-request.ts:
Salida de graphql-request
La misma idea funciona con TanStack Query. No envía peticiones GraphQL por sí mismo, así que llamas a graphql-request o al helper execute() anterior dentro de la función de consulta, y el tipo del resultado fluye hasta tu código.
Y si tu cliente no soporta typed document nodes, aún puedes usar los tipos de operación planos. Importa GetCourseQuery y GetCourseQueryVariables y pásalos como genéricos. Es más manual, pero los tipos siguen viniendo del esquema.
Cómo ejecutar GraphQL Codegen automáticamente
Los tipos generados solo ayudan si coinciden con el esquema y las operaciones actuales.
Si olvidas volver a ejecutar Codegen tras un cambio, los tipos describen un código que ya no existe. Es el mismo problema de deriva que con los tipos escritos a mano, solo que con pasos extra. La solución es eliminar el paso manual del flujo de trabajo.
Scripts de npm
Empieza con un par de scripts en package.json, para que todo el equipo ejecute Codegen del mismo modo:
{"scripts":{"codegen":"graphql-codegen","codegen:watch":"graphql-codegen --watch","codegen:check":"graphql-codegen --check","prebuild":"npm run codegen","build":"tsc -p ."}}Con la tecnología de
El resto de la sección explica para qué sirve cada uno.
Modo watch
El modo watch vuelve a ejecutar Codegen cada vez que cambia un archivo vigilado. Necesita el paquete @parcel/watcher, que Codegen no instala por ti:
Si te saltas la instalación, Codegen se ejecuta una vez e imprime Failed to import @parcel/watcher en lugar de quedarse observando.
El modo watch vigila tanto tus operaciones como un archivo de esquema local. Si añades un campo a course.graphql, el campo aparece en GetCourseQuery un segundo después. Si haces durationHours anulable en schema.graphql, el tipo cambia a number | null, y tu editor marca cada línea que asumía un número.
Déjalo ejecutándose en una terminal junto a tu servidor de desarrollo.
Genera antes de compilar
npm ejecuta un script llamado prebuild antes de build. Con los scripts anteriores, npm run build regenera los tipos primero y solo después ejecuta el compilador de TypeScript.
Así, una build nunca se ejecuta con tipos desactualizados, incluso si alguien olvidó ejecutar Codegen tras hacer pull.
CI/CD
La bandera --check ejecuta Codegen en modo dry-run. No escribe archivos, compara lo que generaría con lo que hay en disco y sale con código 1 si algo difiere.
Este es un workflow mínimo de GitHub Actions que lo usa:
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 buildCon la tecnología de
El paso codegen:check solo tiene sentido si haces commit de los archivos generados. Si no lo haces, elimina ese paso, ya que npm run build lo regenera todo mediante el hook prebuild.
Regenera cuando cambie el esquema
Las operaciones cambian en tu repo, así que el modo watch y prebuild las cubren. Los cambios de esquema son más complicados porque suelen venir de otro equipo.
Cómo gestionarlos depende de dónde esté el esquema:
Archivo de esquema en el mismo repo: el modo watch y el CI detectan los cambios; es el montaje más sencillo
Esquema desde una URL: Codegen obtiene la última versión en cada ejecución, así que codegen:check en CI falla en cuanto el esquema del servidor ya no coincide con tu salida en el repo
Esquema publicado desde otro repo: cópialo o descárgalo como parte de tu build y luego ejecuta Codegen sobre la copia local
La opción de URL tiene una pega: el modo watch reacciona a cambios en archivos, así que no ve cuando cambia un esquema remoto. Solo verás esos cambios en la siguiente ejecución manual o en CI.
GraphQL Codegen vs tipos escritos a mano
Ambos enfoques te dan tipos de TypeScript para datos GraphQL, pero hay diferencias que debes conocer.
Tipos escritos a mano
Con tipos escritos a mano, lees el esquema y escribes tú mismo interfaces equivalentes.
Esto te da control total: puedes nombrar tipos como quieras, fusionar varias operaciones en un tipo compartido o añadir ayudas que el esquema no tiene.
Pero es trabajo manual. Cada campo nuevo o argumento renombrado implica buscar y actualizar a mano el tipo correspondiente. Y nada te avisa si te dejas alguno.
De ahí viene la deriva. La interfaz Course del inicio seguía compilando tras renombrar title en el backend, porque TypeScript solo comprueba tu código contra tus tipos, no contra la API.
Tipos generados
Los tipos generados vienen del mismo esquema que usa el servidor, así que están sincronizados con tus definiciones GraphQL por diseño. Un cambio en el esquema más una ejecución de Codegen actualiza todos los tipos afectados a la vez.
También escribes mucho menos código. El proyecto del catálogo tiene tres operaciones y cero tipos escritos a mano para ellas.
Y prácticamente obtienes desarrollo guiado por esquema. Cambias el esquema o una operación, regeneras y el compilador te da la lista de todo lo que debes tocar.
Pero recuerda: Codegen solo refleja lo que le das.
Si el esquema marca todos los campos como anulables, tus tipos generados estarán llenos de | null. Si una operación trae 40 campos cuando la página necesita cinco, el tipo generado tendrá 40 campos.
Resumen rápido de diferencias:
Tipos escritos a mano
Tipos generados
Mantenimiento
Manual en cada cambio de esquema
Un comando tras cada cambio
Deriva del esquema
Posible y silenciosa
Se detecta al generar o compilar
Boilerplate
Aumenta con cada operación
Ninguno a mano
Control sobre tipos a medida
Total
Limitado a las opciones de los plugins
Desarrollo guiado por esquema
Comprobación manual
El compilador señala cada línea afectada
Codegen frente a tipos escritos a mano
GraphQL Codegen vs. introspección de GraphQL
A menudo se confunden porque Codegen suele usar introspección. Aun así, resuelven problemas distintos.
La introspección es una característica del estándar GraphQL. Cualquier servidor GraphQL puede responder consultas sobre su propio esquema mediante campos especiales como __schema y __type. El resultado es una descripción JSON de cada tipo, campo y argumento que expone la API.
En palabras llanas, la introspección responde a la pregunta «¿Cómo es esta API?»
Codegen responde a «¿Qué código necesita mi aplicación?». Toma la información del esquema y tus operaciones, y escribe tipos de TypeScript y typed document nodes.
Cuando estableces schema a una URL en codegen.ts, Codegen envía una consulta de introspección a ese servidor para obtener el esquema. Con un archivo .graphql local, no hay introspección.
Codegen también puede producir un resultado de introspección como salida. El plugin @graphql-codegen/introspection escribe el esquema en JSON de introspección, que algunas herramientas, como Graphcache de urql, usan para caché con conocimiento de esquema.
Introspección
GraphQL Codegen
Qué es
Sistema de consultas integrado en GraphQL
Herramienta de línea de comandos y plugins
Entrada
Una consulta a un servidor en ejecución
Un esquema y tus operaciones
Salida
Descripción JSON del esquema
Tipos, document nodes, código de cliente
Cuándo se ejecuta
Siempre que un cliente se lo pida al servidor
Durante desarrollo, builds y CI
Codegen frente a introspección
Problemas comunes con GraphQL Codegen
La mayoría de errores de Codegen se deben a uno de cuatro problemas.
Faltan tipos generados
Codegen se ejecuta sin errores, pero el tipo que esperas no aparece en el archivo de salida.
Comprueba estas tres cosas, en orden:
Esquema: si el tipo no existe en el esquema que carga Codegen, no puede generarlo, así que abre el archivo de esquema o lanza tú mismo la introspección y confirma que está
Documentos: los tipos de operación solo existen para operaciones que Codegen ha encontrado; si el archivo con tu consulta no lo encuentra el glob de documents, faltarán sus tipos
Plugins: desde la v6, typescript-operations solo genera enums e inputs que usan tus operaciones; si necesitas un tipo completo del esquema como Course, añade el plugin typescript a un archivo de salida aparte
Si usas un plugin que no has instalado, Codegen falla con un mensaje claro:
Unable to find template plugin matching 'typescript-react-apollo'
Install one of the following packages:
- @graphql-codegen/typescript-react-apolloCon la tecnología de
Codegen no encuentra operaciones
Este error significa que el glob de documents no coincidió con ningún archivo que contenga una operación:
Unable to find any GraphQL type definitions for the following pointers:
- src/**/*.gqlCon la tecnología de
Comprueba que la extensión del glob coincida con tus archivos. Un patrón .gql no encontrará archivos .graphql, y un patrón src/**/*.graphql no encontrará operaciones inline en archivos .ts.
Para operaciones inline, revisa también la etiqueta. Codegen solo encuentra literales de plantilla envueltos en gql o marcados con un comentario /* GraphQL */. Una template string normal con una consulta dentro es invisible para él.
Si estableces ignoreNoDocuments: true, Codegen no muestra este error y genera una salida sin tipos de operación. Esa opción es útil en un proyecto nuevo, pero puede ocultar un glob roto más adelante.
Tipos generados desactualizados
Los tipos compilan, pero no reflejan el último cambio de una operación o del esquema.
Codegen no se ejecuta solo. Vuelve a ejecutarlo tras cada cambio en un archivo .graphql, una operación inline, el esquema o codegen.ts. Durante el desarrollo, npm run codegen:watch lo hace por ti.
Si los tipos están obsoletos en CI, haz commit de los archivos regenerados o deja que el hook prebuild los regenere antes de compilar.
Los tipos generados no coinciden con la API
Los tipos compilan, pero los datos del servidor tienen otra forma en tiempo de ejecución.
Casi siempre significa que Codegen y tu app hablan con esquemas distintos. Por ejemplo, Codegen lee un schema.graphql local de hace una semana, mientras la app llama a una API de producción que ha cambiado desde entonces.
Comprueba a dónde apunta la clave schema. Si es un archivo, compáralo con la API que llama tu app y actualízalo. Si es una URL, asegúrate de que es el mismo entorno que usa tu app, no un staging con un esquema más nuevo o más viejo.
Luego regenera y mira el diff. Si un archivo de operación cambió pero el generado no, probablemente la operación está fuera del glob de documents.
Buenas prácticas para GraphQL Codegen
Codegen no necesita mucha configuración para funcionar bien. Estas prácticas lo mantienen así a medida que el proyecto crece:
Mantén sincronizados el esquema y los archivos generados: ejecuta el modo watch en desarrollo y prebuild antes de compilar, para que nadie trabaje con tipos de un esquema antiguo
Genera tipos específicos por operación: usa typescript-operations en código cliente porque encajan exactamente con lo que trae cada consulta
Haz commit de los archivos generados solo si tu flujo lo necesita: tenerlos en el repo permite revisar cambios de tipos en PRs y ejecutar --check en CI; si tu equipo no lo necesita, añade la carpeta de salida a .gitignore y genera en cada build
Mantén la config corta: un archivo de salida con dos plugins cubre la mayoría de proyectos cliente, y cada opción extra es algo que la siguiente persona debe entender antes de tocar nada
Ejecuta Codegen en CI en cada push: un paso --check o un hook prebuild detecta los cambios que alguien olvidó regenerar en local
No edites archivos generados a mano jamás: la próxima ejecución de Codegen sobrescribirá tus cambios; corrige el esquema, la operación o la config
Conclusión
GraphQL Codegen se encarga de la parte más repetitiva del desarrollo con GraphQL: convertir a mano esquemas y operaciones en tipos de TypeScript.
El flujo de trabajo se mantiene igual por grande que sea el proyecto. Defines el esquema y las operaciones, configuras Codegen, generas los tipos y los typed document nodes, y los importas en tu aplicación.
Lo mejor es que tus tipos siempre describen la API real a la que llamas, no el código que no tienes que escribir. Cuando cambie el esquema, el compilador te dirá si algo ha roto para que puedas detectar errores cuanto antes.
Si quieres aprender cómo se usa GraphQL en una base de datos NoSQL moderna, lee nuestro post MongoDB y GraphQL.
Científico de Datos Senior con base en Croacia. Top Tech Writer con más de 700 artículos publicados, generando más de 10M de visitas. Autor del libro Automatización del aprendizaje automático con TPOT.
Preguntas frecuentes sobre GraphQL Codegen
¿Para qué se usa GraphQL Codegen?⌄
GraphQL Codegen genera código a partir de un esquema GraphQL y de tus operaciones GraphQL. La mayoría de equipos lo usan para obtener tipos de TypeScript y typed document nodes para sus consultas y mutaciones, y así no tener que escribir y actualizar esos tipos a mano. También puede generar tipos de resolvers para servidores y hooks listos para clientes concretos.
¿Necesito un servidor GraphQL en ejecución para usar Codegen?⌄
No. Codegen puede leer el esquema desde un archivo .graphql local, así que funciona sin servidor. Solo necesitas un servidor en ejecución si la clave schema apunta a una URL, porque entonces Codegen obtiene el esquema mediante introspección.
¿Debo hacer commit de los archivos generados en Git?⌄
Depende del flujo de trabajo de tu equipo. Hacer commit de los archivos te permite revisar cambios de tipos en los pull requests y usar graphql-codegen --check en CI para detectar salidas obsoletas. Si no lo necesitas, añade la carpeta de salida a .gitignore y regenera los archivos antes de cada build.
¿Debo usar el preset client o los plugins individuales?⌄
The Guild recomienda el preset client para la mayoría de apps cliente, ya que agrupa tipos de operaciones, typed document nodes y enmascarado de fragmentos en una sola configuración. Apollo recomienda en cambio el plugin typescript-operations, porque el preset añade código de runtime y funciones que entran en conflicto con Apollo Client. Si usas Apollo, elige los plugins. Si no, el preset es un buen punto de partida.
¿Por qué obtengo errores de declaraciones duplicadas tras actualizar Codegen?⌄
Desde la v6, el plugin typescript-operations genera sus propios tipos de enum e input. Si tu config sigue listando typescript y typescript-operations para el mismo archivo de salida, ambos declaran tipos como Level y TypeScript lanza errores por declaraciones duplicadas. Quita el plugin typescript de esa salida o muévelo a un archivo aparte si sigues necesitando los tipos completos del esquema.
Desarrolla tus habilidades de Python para la ingeniería de software. Escribe funciones limpias, domina la programación orientada a objetos (POO), las estructuras de datos y los algoritmos, y entrega código bien probado.
Escribe código y crea aplicaciones de software más rápido que nunca con las herramientas de desarrollo de IA más recientes, como GitHub Copilot, Windsurf y Replit.
Los tipos de TypeScript escritos a mano para una API GraphQL se quedan obsoletos en cuanto alguien cambia el esquema.
Imagina que una persona del backend renombra el campo
titledel tipoCourseaname. El frontend sigue compilando porque la interfazCourseescrita a mano no sabe que algo ha cambiado, así que el fallo solo aparece en tiempo de ejecución. En aplicaciones reales suele haber decenas de consultas, mutaciones y fragmentos, así que puedes ver lo rápido que esto se descontrola.GraphQL Code Generator, o GraphQL Codegen, lee tu esquema y tus operaciones GraphQL y las convierte en tipos, utilidades para consultas, integraciones de cliente y otros "boilerplates" que de otro modo escribirías a mano. Se usa sobre todo con TypeScript y clientes populares como Apollo y urql. Con un solo comando vuelves a sincronizar tus tipos siempre que cambie el esquema.
En este artículo, verás cómo configurar GraphQL Codegen en un proyecto pequeño de TypeScript, cómo ajustarlo, cómo usar los tipos generados y cómo ejecutarlo automáticamente dentro de tu flujo de trabajo.
¿Cómo se compara GraphQL con REST? Lee nuestra guía completa de GraphQL vs REST para conocer diferencias y ventajas.
¿Qué es GraphQL Codegen?
GraphQL Codegen es una herramienta de línea de comandos que transforma definiciones de GraphQL en código de aplicación.
Es un proyecto open source de The Guild, y lo instalas como dependencia de desarrollo. Conecta tres piezas:
El esquema le dice a Codegen qué es posible y las operaciones le dicen qué pide tu aplicación.
Codegen combina ambos, de modo que cada tipo generado encaja exactamente con la forma de la respuesta de una operación. Además, valida cada operación frente al esquema. El campo
titlerenombrado del ejemplo inicial detendría la generación con un error comoCannot query field "title" on type "Course", y lo detectarías antes de ejecutar el código.La salida depende de tus plugins y de la configuración. Codegen en sí no escribe TypeScript. Lo hacen los plugins. Por ejemplo, el plugin
typescriptgenera tipos del esquema, ytypescript-operationsgenera tipos para tus consultas y mutaciones. Hay plugins para otros lenguajes, como Java y C#, pero aquí nos quedamos en TypeScript.Importante: Codegen no sustituye a tu servidor GraphQL.
No resuelve consultas ni obtiene datos. Lee definiciones de GraphQL durante el desarrollo y escribe archivos. Tu servidor y tu cliente GraphQL hacen el resto.
Cómo funciona GraphQL Codegen
Toda configuración de Codegen sigue el mismo flujo: esquema + operaciones GraphQL -> configuración de Codegen -> código generado.
Diagrama del flujo de trabajo de GraphQL Codegen
La idea general es esta:
Proporciona un esquema: señala a Codegen un archivo
.graphqllocal o un endpoint GraphQL en ejecución, que Codegen lee mediante introspecciónIndica a Codegen tus operaciones: usa patrones glob como
src/**/*.tspara que Codegen encuentre consultas, mutaciones y fragmentos en tu códigoConfigura plugins y destinos de salida: dile a Codegen qué archivos escribir y qué plugins generan cada uno
Ejecuta Codegen: ejecuta
npx graphql-codegenpara cargar el esquema, validar tus operaciones y escribir la salidaUsa los artefactos generados: importa los tipos y los document nodes generados en tu código de aplicación
Los pasos del 1 al 3 van en un único archivo de configuración, normalmente
codegen.ts. Aquí tienes la versión mínima para un proyecto de catálogo de cursos:El preset
clientes un paquete de plugins que genera tipos de esquema, tipos de operaciones y typed document nodes de una sola vez. Verás cada uno en las secciones de configuración y puesta en marcha.Cómo configurar GraphQL Codegen
La mejor forma de entender Codegen es ejecutarlo en un proyecto real.
En esta sección, construirás desde cero un pequeño proyecto de catálogo de cursos. Incluye un esquema con cursos e instructores, una consulta y una configuración de Codegen que convierte esa consulta en tipos de TypeScript. Solo necesitas Node.js y npm.
Paso 1: instala GraphQL Code Generator
Crea una carpeta nueva e inicializa un proyecto npm:
Codegen necesita varios paquetes. Dos van en dependencias normales y el resto como dependencias de desarrollo, porque solo se usan durante el desarrollo:
Para qué sirve cada paquete:
graphql: la implementación de referencia de GraphQL para JavaScript, que Codegen usa para analizar el esquema y las operaciones@graphql-typed-document-node/core: proporciona el tipoTypedDocumentNodeque importará tu código generado@graphql-codegen/cli: la herramienta de línea de comandos de Codegen@graphql-codegen/typescript-operations: el plugin que genera tipos para tus consultas, mutaciones y fragmentos@graphql-codegen/typed-document-node: el plugin que genera objetos de documento con los tipos asociadosPaso 2: crea un archivo de configuración
Codegen lee su configuración desde un archivo en la raíz del proyecto. Crea
codegen.tscon una configuración vacía por ahora:También puedes ejecutar
npx graphql-codegen initpara responder unas preguntas y obtener un archivo de config generado. Aquí lo escribo a mano para que veas qué hace cada ajuste.Paso 3: indica las ubicaciones del esquema y los documentos
Codegen necesita dos entradas, así que vamos a crear ambas.
Primero, guarda el esquema como
schema.graphqlen la raíz del proyecto:Luego, crea
src/operations/courses.graphqlcon una consulta que trae cursos y sus instructores:Ahora apunta Codegen a ambos archivos. La clave
schemaacepta la ruta del esquema, ydocumentsun patrón glob que encuentre tus operaciones:Paso 4: elige un archivo de salida
La clave
generatesindica a Codegen dónde escribir la salida. Cada clave dentro es una ruta de archivo:Codegen crea la carpeta
src/generated/si no existe.Paso 5: añade los plugins necesarios
Un archivo de salida sin plugins estará vacío. Añade los dos plugins que instalaste:
Si seguiste un tutorial antiguo, habrás visto también el plugin
typescript. Puedes quitarlo ahora: typescript-operations funciona por sí solo y solo genera tipos de Input, Enum y Operación que realmente se usan. Si pones ambos en el mismo archivo de salida con las versiones actuales, TypeScript lanza errores por declaraciones duplicadas.Paso 6: ejecuta Codegen
Añade un script de npm para no tener que recordar el comando:
Y ejecútalo:
Codegen carga el esquema, valida la consulta contra él y escribe la salida:
Resultados de la generación con Codegen
Si una operación hace referencia a un campo que no existe en el esquema, la ejecución fallará aquí y no se escribirá ningún archivo.
Paso 7: inspecciona la salida generada
Abre
src/generated/graphql.ts. Verás algo como esto:La salida generada
Codegen generó cuatro elementos:
Level: una unión de cadenas para el enum, generada solo porque la consulta lo usaGetCoursesQueryVariables: el tipo para las variables que pasas a la consulta, donde ambas son opcionales porque el esquema no las marca como obligatoriasGetCoursesQuery: la forma de la respuesta, con solo los campos que solicita la consultaGetCoursesDocument: la consulta parseada como typed document node, con los tipos de resultado y variables adjuntosFíjate de nuevo en
GetCoursesQuery. No incluyedurationHoursni elbiodel instructor, porque la consulta no los pide. Si intentas leercourse.durationHoursen tu código, obtendrás un error de compilación, no unundefineden tiempo de ejecución.Y eso es toda la puesta en marcha: tú escribes GraphQL y Codegen escribe TypeScript.
Cómo ajustar la configuración de GraphQL Codegen
La mayoría de configs de Codegen que verás son más largas que la anterior, pero se basan en los mismos cuatro ajustes.
El archivo de config puede ser
codegen.ts,codegen.ymlocodegen.json. Uso TypeScript porque obtienes autocompletado y tipos en la propia configuración. Los ajustes son iguales en cualquier formato.Schema
La clave
schemaindica a Codegen dónde está tu esquema. Acepta varios tipos de origen.Un archivo local o un patrón glob funcionan cuando el esquema está en tu repositorio:
Una URL funciona cuando el esquema está en un servidor en ejecución. Codegen envía una consulta de introspección al endpoint, y puedes pasar cabeceras para autenticarte:
La opción de URL solo funciona si el servidor tiene la introspección activada. Muchas APIs en producción la desactivan, así que para CI suele ser más seguro un archivo de esquema en el repo.
Documents
La clave
documentsle dice a Codegen dónde encontrar tus consultas, mutaciones, suscripciones y fragmentos.Las operaciones pueden ir en archivos
.graphqlo inline en tu código TypeScript. Codegen encuentra operaciones inline cuando están envueltas en una etiquetagqlo marcadas con un comentario/* GraphQL */:Para escanear ambos tipos de archivo, amplía el glob. Añade un patrón negado para que Codegen no escanee su propia salida:
Pon un nombre único a cada operación. Codegen construye los nombres de tipos a partir del nombre de la operación, así que
EnrollStudentse convierte enEnrollStudentMutationyEnrollStudentMutationVariables.Generates
La clave
generatesmapea rutas de salida con lo que irá en ellas. Puedes tener tantas salidas como necesites, cada una con sus plugins.Imagina que quieres los tipos de operaciones en un archivo y los tipos completos del esquema en otro:
El objeto
configdentro de una salida se aplica solo a ese archivo. Aquí,useTypeImportshace que el archivo generado useimport type, que algunos entornos necesitan. Si ponesconfigen la raíz de la config, se aplica a todas las salidas.Una ruta de salida también puede ser una carpeta que termine en barra, como
"src/gql/". Es el formato que usan los presets, ya que escriben más de un archivo.Plugins
Los plugins deciden qué se genera. Codegen carga el esquema y los documentos, y cada plugin los convierte en una parte de la salida.
Estos son los plugins que más verás en proyectos TypeScript:
typescript-operations: tipos para consultas, mutaciones, suscripciones y fragmentos, además de los enums e inputs que utilizantyped-document-node: objetos documento con los tipos de resultado y variables adjuntos, que la mayoría de clientes GraphQL entiendentypescript: tipos para cada objeto, enum e input del esquema, los use o no tu códigotypescript-resolvers: firmas de tipo para funciones resolver en el lado servidorUn preset es un paquete de plugins con una config sensata por defecto. El preset
clientde la sección Cómo funciona es el que The Guild recomienda para apps cliente. Se apoya en el typescript-operations mejorado, así que obtienes sus ventajas sin configuración extra.Cada plugin tiene sus propias opciones, y hay muchas. No necesitas aprendértelas de memoria. Empieza con los valores por defecto y busca una opción cuando la salida generada no encaje con lo que espera tu código.
¿Qué puede generar GraphQL Codegen?
Lo que obtienes de Codegen depende de los plugins que elijas.
Con el mismo esquema y operaciones puedes generar desde tipos de TypeScript planos hasta código listo para clientes específicos. Estos son los outputs más comunes.
Tipos de TypeScript
El plugin
typescriptgenera un tipo para cada objeto, enum e input del esquema. Para el catálogo de cursos, el tipoCoursese ve así:Estos tipos describen el esquema completo, lo que los hace útiles en el servidor, en datos de prueba y en utilidades que trabajan con objetos completos.
Pero no encajan bien en código cliente. Un tipo
Coursedice que todos los campos existen, incluso los que tu consulta no pidió.Tipos de operaciones
El plugin
typescript-operationsgenera dos tipos por operación: uno para el resultado y otro para las variables. Funciona igual para consultas y suscripciones.Esto es lo que genera para la mutación
EnrollStudent:El tipo de resultado refleja el selection set, campo a campo. El tipo de variables es
Exact, así que TypeScript rechaza variables extra o con errores tipográficos.La variable
courseIdaceptastringynumberporque el escalarIDde GraphQL acepta ambos como entrada. Desde la v6, el tipo por defecto esstring | number, que es lo correcto en clientes.Typed document nodes
Un
DocumentNodenormal es una consulta GraphQL parseada. Conoce la estructura de la consulta, pero no sabe qué devuelve ni qué variables acepta.Un typed document node lleva ambos tipos consigo. El plugin
typed-document-nodegenera uno por operación:Así, cualquier función que acepte un
TypedDocumentNodepuede inferir los tipos de resultado y variables a partir del propio documento. No pasas genéricos a mano y no puedes combinar una consulta con tipos incorrectos.La mayoría de clientes GraphQL modernos aceptan typed document nodes, incluidos Apollo Client, urql y graphql-request. Verás los tres en acción más adelante.
Integraciones específicas de cliente
Algunos plugins van más allá y generan código para un cliente o framework concreto. Por ejemplo:
typescript-react-apollo: genera hooks tipados de React para Apollo Clienttypescript-urql: genera hooks y componentes tipados para urqltypescript-react-query: genera hooks tipados para TanStack Querytypescript-graphql-request: genera un SDK tipado con una función por operaciónTodos estos son plugins de la comunidad. The Guild los trasladó a un repositorio comunitario, por lo que su cadencia de lanzamientos difiere de los plugins core.
Además, hoy en día los necesitas menos. Cuando un cliente acepta typed document nodes, los hooks generados no añaden mucha más seguridad de tipos. La propia documentación de Apollo, por ejemplo, recomienda usar el plugin
typescript-operations, que se centra en generar tipos y no incluye código de runtime adicional.En general, empieza con tipos de operaciones y typed document nodes. Luego añade un plugin específico de cliente solo si tu equipo quiere los hooks o funciones de SDK generados.
GraphQL Codegen con TypeScript
Los tipos generados solo importan si detectan errores, así que vamos a provocarlos.
Este ejemplo amplía el proyecto del catálogo con una segunda consulta, un pequeño helper que la envía a la API y el código que usa el resultado. Asume un servidor GraphQL que implementa el esquema en
http://localhost:4000/graphql.Esta es la parte del esquema que usa el ejemplo:
Aquí importan dos detalles. El campo
coursedevuelveCoursesin!, así que esnullcuando ningún curso coincide con el ID. Elbiodel instructor también puede ser nulo.Crea
src/operations/course.graphqlcon una consulta que trae un curso:Ejecuta
npm run codegende nuevo. Codegen añade dos tipos nuevos asrc/generated/graphql.ts:Contenido del archivo graphql.ts
La anulabilidad del esquema se mantiene.
coursepuede sernull,biopuede sernull, eides obligatorio porque la consulta lo declara comoID!.Ahora el código de aplicación. Crea
src/execute.tscon un helper que envía cualquier documento tipado a la API:El helper no sabe nada de cursos. Obtiene ambos tipos del documento que le pasas, y la función
print()convierte el documento de nuevo en una cadena de consulta para la petición.Después úsalo en
src/course-details.ts:La función
formatCourse()toma su tipo de parámetro del tipo de la consulta generada.NonNullableelimina el casonull, porque la función solo se ejecuta tras elif.El ejemplo usa
awaita nivel superior, así que pon"type": "module"enpackage.jsony ejecútalo connpx tsx src/course-details.ts:Llamada correcta a un servidor GraphQL simulado
Esto asume que tienes un servidor GraphQL ejecutándose. Aquí tienes uno simulado que utilicé:
Ahora intenta romperlo. Abre
src/course-details.tsy sustituye todo lo que hay debajo de la funciónformatCourse()por tres errores que los tipos escritos a mano suelen dejar pasar:Luego ejecuta la comprobación de tipos:
TypeScript detecta los tres errores antes de ejecutar el código:
Errores detectados por TypeScript
Así reduce Codegen los desajustes entre el frontend y la API. Los tipos vienen del mismo esquema que usa el servidor, así que no pueden describir campos que no existen ni pasar por alto nulls que el servidor podría devolver.
Y la protección no termina tras la primera ejecución. Imagina que el equipo de backend hace
durationHoursanulable. Regeneras, el tipo cambia anumber | null, y TypeScript te señala cada línea que asumía un número.GraphQL Codegen con clientes GraphQL
Codegen no envía peticiones. Eso le toca a tu cliente GraphQL.
Los typed document nodes generados son el punto de traspaso entre ambos. Se los pasas al cliente y el cliente infiere los tipos. Los ejemplos siguientes usan el mismo
src/generated/graphql.tsy la API simulada de la sección anterior, así que manténnpx tsx mock/server.tsejecutándose en otra terminal.GraphQL Codegen con Apollo
Instala Apollo Client y su dependencia peer
rxjs:El ejemplo también ejecuta la mutación
EnrollStudent. Guárdala comosrc/operations/enroll.graphql:La documentación de Apollo también recomienda dos opciones de config para Codegen, ya que Apollo Client siempre incluye los campos
__typenamepero no los añade a los tipos raíz. Añádelas al destino de salida encodegen.ts:Con estas opciones, cada objeto de los tipos de resultado generados lleva un campo
__typenameobligatorio, como__typename: 'Course'. Eso coincide con lo que devuelve la caché de Apollo.Ejecuta
npm run codegenotra vez para detectar la nueva mutación y configuración.Apollo Client acepta typed document nodes en
query()ymutate(). Guarda esto comosrc/apollo.ts:El objeto
dataestá tipado comoGetCoursesQuery | undefined, y TypeScript compruebavariablescontraGetCoursesQueryVariables. La mutación funciona igual conEnrollStudentMutationy sus variables.Ejecútalo con
npx tsx src/apollo.ts:Salida de Apollo
La primera línea viene de la consulta, ya que es el único curso para principiantes. La segunda viene de la mutación, que devuelve el título del curso en el que se ha matriculado el alumno.
Los hooks de React, como
useQuery()yuseMutation(), infieren los tipos a partir de typed document nodes del mismo modo.GraphQL Codegen con urql
Instala el paquete core de urql:
urql funciona con typed document nodes desde el primer momento. Pasa el documento como primer argumento a
query()ensrc/urql.ts:El segundo argumento está tipado como las variables de la consulta, y
result.dataestá tipado como el resultado de la consulta.Ejecútalo con
npx tsx src/urql.ts:Salida de urql
Las integraciones con frameworks, como
useQuery()en el paqueteurqlpara React, también aceptan typed document nodes.GraphQL Codegen con otros clientes
No necesitas un cliente con todas las funcionalidades para tener resultados tipados.
El cliente
graphql-requestes un cliente mínimo que envía una petición y devuelve los datos. Instálalo con el siguiente comando:Infiere tipos a partir de typed document nodes igual que Apollo y urql. Guarda esto como
src/graphql-request.ts:Ejecútalo con
npx tsx src/graphql-request.ts:Salida de graphql-request
La misma idea funciona con TanStack Query. No envía peticiones GraphQL por sí mismo, así que llamas a graphql-request o al helper
execute()anterior dentro de la función de consulta, y el tipo del resultado fluye hasta tu código.Y si tu cliente no soporta typed document nodes, aún puedes usar los tipos de operación planos. Importa
GetCourseQueryyGetCourseQueryVariablesy pásalos como genéricos. Es más manual, pero los tipos siguen viniendo del esquema.Cómo ejecutar GraphQL Codegen automáticamente
Los tipos generados solo ayudan si coinciden con el esquema y las operaciones actuales.
Si olvidas volver a ejecutar Codegen tras un cambio, los tipos describen un código que ya no existe. Es el mismo problema de deriva que con los tipos escritos a mano, solo que con pasos extra. La solución es eliminar el paso manual del flujo de trabajo.
Scripts de npm
Empieza con un par de scripts en
package.json, para que todo el equipo ejecute Codegen del mismo modo:El resto de la sección explica para qué sirve cada uno.
Modo watch
El modo watch vuelve a ejecutar Codegen cada vez que cambia un archivo vigilado. Necesita el paquete
@parcel/watcher, que Codegen no instala por ti:Si te saltas la instalación, Codegen se ejecuta una vez e imprime
Failed to import @parcel/watcheren lugar de quedarse observando.El modo watch vigila tanto tus operaciones como un archivo de esquema local. Si añades un campo a
course.graphql, el campo aparece enGetCourseQueryun segundo después. Si hacesdurationHoursanulable enschema.graphql, el tipo cambia anumber | null, y tu editor marca cada línea que asumía un número.Déjalo ejecutándose en una terminal junto a tu servidor de desarrollo.
Genera antes de compilar
npm ejecuta un script llamado
prebuildantes debuild. Con los scripts anteriores,npm run buildregenera los tipos primero y solo después ejecuta el compilador de TypeScript.Así, una build nunca se ejecuta con tipos desactualizados, incluso si alguien olvidó ejecutar Codegen tras hacer pull.
CI/CD
La bandera
--checkejecuta Codegen en modo dry-run. No escribe archivos, compara lo que generaría con lo que hay en disco y sale con código 1 si algo difiere.Este es un workflow mínimo de GitHub Actions que lo usa:
El paso
codegen:checksolo tiene sentido si haces commit de los archivos generados. Si no lo haces, elimina ese paso, ya quenpm run buildlo regenera todo mediante el hookprebuild.Regenera cuando cambie el esquema
Las operaciones cambian en tu repo, así que el modo watch y
prebuildlas cubren. Los cambios de esquema son más complicados porque suelen venir de otro equipo.Cómo gestionarlos depende de dónde esté el esquema:
codegen:checken CI falla en cuanto el esquema del servidor ya no coincide con tu salida en el repoLa opción de URL tiene una pega: el modo watch reacciona a cambios en archivos, así que no ve cuando cambia un esquema remoto. Solo verás esos cambios en la siguiente ejecución manual o en CI.
GraphQL Codegen vs tipos escritos a mano
Ambos enfoques te dan tipos de TypeScript para datos GraphQL, pero hay diferencias que debes conocer.
Tipos escritos a mano
Con tipos escritos a mano, lees el esquema y escribes tú mismo interfaces equivalentes.
Esto te da control total: puedes nombrar tipos como quieras, fusionar varias operaciones en un tipo compartido o añadir ayudas que el esquema no tiene.
Pero es trabajo manual. Cada campo nuevo o argumento renombrado implica buscar y actualizar a mano el tipo correspondiente. Y nada te avisa si te dejas alguno.
De ahí viene la deriva. La interfaz
Coursedel inicio seguía compilando tras renombrartitleen el backend, porque TypeScript solo comprueba tu código contra tus tipos, no contra la API.Tipos generados
Los tipos generados vienen del mismo esquema que usa el servidor, así que están sincronizados con tus definiciones GraphQL por diseño. Un cambio en el esquema más una ejecución de Codegen actualiza todos los tipos afectados a la vez.
También escribes mucho menos código. El proyecto del catálogo tiene tres operaciones y cero tipos escritos a mano para ellas.
Y prácticamente obtienes desarrollo guiado por esquema. Cambias el esquema o una operación, regeneras y el compilador te da la lista de todo lo que debes tocar.
Pero recuerda: Codegen solo refleja lo que le das.
Si el esquema marca todos los campos como anulables, tus tipos generados estarán llenos de
| null. Si una operación trae 40 campos cuando la página necesita cinco, el tipo generado tendrá 40 campos.Resumen rápido de diferencias:
Codegen frente a tipos escritos a mano
GraphQL Codegen vs. introspección de GraphQL
A menudo se confunden porque Codegen suele usar introspección. Aun así, resuelven problemas distintos.
La introspección es una característica del estándar GraphQL. Cualquier servidor GraphQL puede responder consultas sobre su propio esquema mediante campos especiales como
__schemay__type. El resultado es una descripción JSON de cada tipo, campo y argumento que expone la API.En palabras llanas, la introspección responde a la pregunta «¿Cómo es esta API?»
Codegen responde a «¿Qué código necesita mi aplicación?». Toma la información del esquema y tus operaciones, y escribe tipos de TypeScript y typed document nodes.
Cuando estableces
schemaa una URL encodegen.ts, Codegen envía una consulta de introspección a ese servidor para obtener el esquema. Con un archivo.graphqllocal, no hay introspección.Codegen también puede producir un resultado de introspección como salida. El plugin
@graphql-codegen/introspectionescribe el esquema en JSON de introspección, que algunas herramientas, como Graphcache de urql, usan para caché con conocimiento de esquema.Codegen frente a introspección
Problemas comunes con GraphQL Codegen
La mayoría de errores de Codegen se deben a uno de cuatro problemas.
Faltan tipos generados
Codegen se ejecuta sin errores, pero el tipo que esperas no aparece en el archivo de salida.
Comprueba estas tres cosas, en orden:
Esquema: si el tipo no existe en el esquema que carga Codegen, no puede generarlo, así que abre el archivo de esquema o lanza tú mismo la introspección y confirma que está
Documentos: los tipos de operación solo existen para operaciones que Codegen ha encontrado; si el archivo con tu consulta no lo encuentra el glob de
documents, faltarán sus tiposPlugins: desde la v6,
typescript-operationssolo genera enums e inputs que usan tus operaciones; si necesitas un tipo completo del esquema comoCourse, añade el plugintypescripta un archivo de salida aparteSi usas un plugin que no has instalado, Codegen falla con un mensaje claro:
Codegen no encuentra operaciones
Este error significa que el glob de
documentsno coincidió con ningún archivo que contenga una operación:Comprueba que la extensión del glob coincida con tus archivos. Un patrón
.gqlno encontrará archivos.graphql, y un patrónsrc/**/*.graphqlno encontrará operaciones inline en archivos.ts.Para operaciones inline, revisa también la etiqueta. Codegen solo encuentra literales de plantilla envueltos en
gqlo marcados con un comentario/* GraphQL */. Una template string normal con una consulta dentro es invisible para él.Si estableces
ignoreNoDocuments: true, Codegen no muestra este error y genera una salida sin tipos de operación. Esa opción es útil en un proyecto nuevo, pero puede ocultar un glob roto más adelante.Tipos generados desactualizados
Los tipos compilan, pero no reflejan el último cambio de una operación o del esquema.
Codegen no se ejecuta solo. Vuelve a ejecutarlo tras cada cambio en un archivo
.graphql, una operación inline, el esquema ocodegen.ts. Durante el desarrollo,npm run codegen:watchlo hace por ti.Si los tipos están obsoletos en CI, haz commit de los archivos regenerados o deja que el hook
prebuildlos regenere antes de compilar.Los tipos generados no coinciden con la API
Los tipos compilan, pero los datos del servidor tienen otra forma en tiempo de ejecución.
Casi siempre significa que Codegen y tu app hablan con esquemas distintos. Por ejemplo, Codegen lee un
schema.graphqllocal de hace una semana, mientras la app llama a una API de producción que ha cambiado desde entonces.Comprueba a dónde apunta la clave
schema. Si es un archivo, compáralo con la API que llama tu app y actualízalo. Si es una URL, asegúrate de que es el mismo entorno que usa tu app, no un staging con un esquema más nuevo o más viejo.Luego regenera y mira el diff. Si un archivo de operación cambió pero el generado no, probablemente la operación está fuera del glob de
documents.Buenas prácticas para GraphQL Codegen
Codegen no necesita mucha configuración para funcionar bien. Estas prácticas lo mantienen así a medida que el proyecto crece:
Mantén sincronizados el esquema y los archivos generados: ejecuta el modo watch en desarrollo y
prebuildantes de compilar, para que nadie trabaje con tipos de un esquema antiguoGenera tipos específicos por operación: usa
typescript-operationsen código cliente porque encajan exactamente con lo que trae cada consultaHaz commit de los archivos generados solo si tu flujo lo necesita: tenerlos en el repo permite revisar cambios de tipos en PRs y ejecutar
--checken CI; si tu equipo no lo necesita, añade la carpeta de salida a.gitignorey genera en cada buildMantén la config corta: un archivo de salida con dos plugins cubre la mayoría de proyectos cliente, y cada opción extra es algo que la siguiente persona debe entender antes de tocar nada
Ejecuta Codegen en CI en cada push: un paso
--checko un hookprebuilddetecta los cambios que alguien olvidó regenerar en localNo edites archivos generados a mano jamás: la próxima ejecución de Codegen sobrescribirá tus cambios; corrige el esquema, la operación o la config
Conclusión
GraphQL Codegen se encarga de la parte más repetitiva del desarrollo con GraphQL: convertir a mano esquemas y operaciones en tipos de TypeScript.
El flujo de trabajo se mantiene igual por grande que sea el proyecto. Defines el esquema y las operaciones, configuras Codegen, generas los tipos y los typed document nodes, y los importas en tu aplicación.
Lo mejor es que tus tipos siempre describen la API real a la que llamas, no el código que no tienes que escribir. Cuando cambie el esquema, el compilador te dirá si algo ha roto para que puedas detectar errores cuanto antes.
Si quieres aprender cómo se usa GraphQL en una base de datos NoSQL moderna, lee nuestro post MongoDB y GraphQL.