Saltar al contenido principal

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.
· 12 min leer

Explora con IA

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.

¿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:

  • 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

Diagrama del flujo de trabajo de GraphQL Codegen

La idea general es esta:

  1. Proporciona un esquema: señala a Codegen un archivo .graphql local o un endpoint GraphQL en ejecución, que Codegen lee mediante introspección

  2. Indica a Codegen tus operaciones: usa patrones glob como src/**/*.ts para que Codegen encuentre consultas, mutaciones y fragmentos en tu código

  3. Configura plugins y destinos de salida: dile a Codegen qué archivos escribir y qué plugins generan cada uno

  4. Ejecuta Codegen: ejecuta npx graphql-codegen para cargar el esquema, validar tus operaciones y escribir la salida

  5. 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:

import type { 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" },
  },
};

export default config;

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:

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

Codegen necesita varios paquetes. Dos van en dependencias normales y el resto como dependencias de desarrollo, porque solo se usan durante el desarrollo:

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

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:

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

const config: CodegenConfig = {};

export default config;

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!
}

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
    }
  }
}

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"],
};

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": {},
  },
};

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:

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

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

export default config;

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:

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

Y ejecútalo:

npm run codegen

Codegen carga el esquema, valida la consulta contra él y escribe la salida:

Resultados de la generación con Codegen

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",

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} },
    },
  },
],

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
      }
    }
  }
;

Para escanear ambos tipos de archivo, amplía el glob. Añade un patrón negado para que Codegen no escanee su propia salida:

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

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"],
  },
},

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í:

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

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:

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

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

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:

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

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
}

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
    }
  }
}

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";
import type { TypedDocumentNode } from "@graphql-typed-document-node/core";

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

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

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, type GetCourseQuery } from "./generated/graphql";

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

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

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

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

Llamada correcta a un servidor GraphQL simulado

Esto asume que tienes un servidor GraphQL ejecutándose. Aquí tienes uno simulado que utilicé:

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

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

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

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

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

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 obligatoria
await execute(GetCourseDocument, {});

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

// Leer un campo que la consulta no pide
console.log(course?.level);

// Olvidar que course puede ser null
console.log(course.title);

Luego ejecuta la comprobación de tipos:

npx tsc -p .

TypeScript detecta los tres errores antes de ejecutar el código:

Errores detectados por TypeScript

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.

GraphQL Codegen con Apollo

Instala Apollo Client y su dependencia peer rxjs:

npm install @apollo/client rxjs

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
    }
  }
}

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 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 = new ApolloClient({
  link: new HttpLink({ uri: "http://localhost:4000/graphql" }),
  cache: new InMemoryCache(),
});

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

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

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

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

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

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.

GraphQL Codegen con urql

Instala el paquete core de urql:

npm install @urql/core

urql funciona con typed document nodes desde el primer momento. Pasa el documento como primer argumento a query() en src/urql.ts:

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

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

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

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

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

El segundo argumento está tipado como las variables de la consulta, y result.data está tipado como el resultado de la consulta.

Ejecútalo con npx tsx src/urql.ts:

Salida de urql

Salida de urql

Las integraciones con frameworks, como useQuery() en el paquete urql para 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-request es un cliente mínimo que envía una petición y devuelve los datos. Instálalo con el siguiente comando:

npm install graphql-request

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 } = await request(
  "http://localhost:4000/graphql",
  GetCourseDocument,
  { id: "c2" },
);

console.log(course?.title);

Ejecútalo con npx tsx src/graphql-request.ts:

Salida de graphql-request

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 ."
  }
}

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:

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

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 build

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 manoTipos generados
MantenimientoManual en cada cambio de esquemaUn comando tras cada cambio
Deriva del esquemaPosible y silenciosaSe detecta al generar o compilar
BoilerplateAumenta con cada operaciónNinguno a mano
Control sobre tipos a medidaTotalLimitado a las opciones de los plugins
Desarrollo guiado por esquemaComprobación manualEl 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ónGraphQL Codegen
Qué esSistema de consultas integrado en GraphQLHerramienta de línea de comandos y plugins
EntradaUna consulta a un servidor en ejecuciónUn esquema y tus operaciones
SalidaDescripción JSON del esquemaTipos, document nodes, código de cliente
Cuándo se ejecutaSiempre que un cliente se lo pida al servidorDurante 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-apollo

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/**/*.gql

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.

Dario Radečić

Autor

Dario Radečić

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.