Générer des types TypeScript depuis le schéma WPGraphQL avec codegen

Sur un projet TypeScript consommant WPGraphQL, un développeur de l’équipe avait écrit une requête référençant un champ excerp au lieu de excerpt, une simple faute de frappe. Sans typage généré depuis le schéma réel, l’erreur n’a été détectée qu’en production, la requête GraphQL renvoyant silencieusement null pour ce champ inexistant plutôt qu’une erreur de compilation. GraphQL Code Generator résout précisément ce type de problème, en générant des types TypeScript directement depuis le schéma introspecté du serveur.

Cet article couvre la configuration de GraphQL Code Generator pour un projet WPGraphQL, la génération de types pour les requêtes existantes, et son intégration au processus de build. Il ne traite pas l’écriture des mutations elles-mêmes, un sujet distinct qui mérite son propre article.

Installation et configuration de base

npm install -D @graphql-codegen/cli @graphql-codegen/typescript @graphql-codegen/typescript-operations

Le fichier de configuration codegen.yml déclare le point d’entrée du schéma (l’URL de l’endpoint GraphQL de WordPress), les fichiers contenant les requêtes à typer, et les plugins de génération à appliquer :

schema: 'https://exemple.fr/graphql'
documents: 'src/**/*.graphql'
generates:
  src/types/wpgraphql.ts:
    plugins:
      - typescript
      - typescript-operations

Le plugin typescript génère les types correspondant à l’ensemble du schéma (tous les types GraphQL exposés par WPGraphQL, y compris ceux ajoutés par des extensions comme WPGraphQL for ACF si elles sont actives). Le plugin typescript-operations génère, lui, des types précis pour chaque requête ou mutation effectivement écrite dans le projet, limités aux champs réellement demandés.

Écrire une requête typée

Les requêtes GraphQL sont écrites dans des fichiers .graphql séparés, plutôt qu’en chaînes de caractères dans le code TypeScript, ce qui permet à codegen de les analyser statiquement :

// src/queries/article.graphql
query RecupererArticle($slug: ID!) {
  post(id: $slug, idType: SLUG) {
    title
    excerpt
    date
    featuredImage {
      node {
        sourceUrl
        altText
      }
    }
  }
}

Après exécution de la commande de génération, un type RecupererArticleQuery devient disponible, correspondant exactement à la forme de la réponse pour cette requête précise :

npx graphql-codegen

import type { RecupererArticleQuery } from '../types/wpgraphql';

async function chargerArticle(slug: string): Promise<RecupererArticleQuery> {
  const reponse = await fetch('https://exemple.fr/graphql', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      query: REQUETE_ARTICLE,
      variables: { slug },
    }),
  });

  const { data } = await reponse.json();
  return data;
}

Autocomplétion fiable dans l’éditeur

Avec l’extension GraphQL pour l’éditeur (disponible pour VS Code notamment), l’autocomplétion propose désormais uniquement les champs réellement disponibles sur le type en cours, en tenant compte des extensions activées côté WordPress. Ce point change concrètement le confort d’écriture des requêtes : plus besoin de garder un onglet ouvert sur l’explorateur GraphiQL de WPGraphQL pour vérifier le nom exact d’un champ.

Générer des hooks React typés

Pour un projet React consommant les requêtes via un client comme graphql-request ou urql, un plugin supplémentaire génère directement des hooks typés, évitant d’écrire manuellement l’appel réseau pour chaque requête :

npm install -D @graphql-codegen/typescript-react-query

generates:
  src/types/wpgraphql.ts:
    plugins:
      - typescript
      - typescript-operations
      - typescript-react-query
    config:
      fetcher:
        endpoint: 'https://exemple.fr/graphql'

import { useRecupererArticleQuery } from '../types/wpgraphql';

function PageArticle({ slug }) {
  const { data, isLoading, error } = useRecupererArticleQuery({ slug });
  // data est déjà typé comme RecupererArticleQuery
}

Intégrer la génération au build

Régénérer les types manuellement à chaque changement de schéma est facile à oublier. Je recommande d’ajouter la commande au script de build, et idéalement une vérification en CI qui échoue si les types générés diffèrent de ceux commités (signe qu’un développeur a modifié une requête sans régénérer) :

{
  "scripts": {
    "codegen": "graphql-codegen",
    "codegen:check": "graphql-codegen --check",
    "prebuild": "npm run codegen"
  }
}

Un point d’attention : le schéma en environnement de développement

La génération interroge le schéma en direct sur l’URL configurée, ce qui suppose que l’environnement WordPress cible soit accessible au moment de lancer la commande, y compris en intégration continue. Sur un projet où l’environnement de développement local n’était pas accessible depuis le serveur CI, j’ai dû mettre en place un export statique du schéma (fichier .graphql ou .json introspecté), régénéré et commité périodiquement, plutôt qu’une interrogation en direct à chaque build.

Le typage généré ne remplace pas les tests, mais il élimine une catégorie entière de bugs — le champ mal orthographié, la propriété qui n’existe plus après une montée de version d’une extension — avant même d’exécuter le code une seule fois.

En résumé

GraphQL Code Generator transforme le schéma WPGraphQL en types TypeScript précis, alignés sur les requêtes réellement écrites dans le projet plutôt que sur l’ensemble du schéma. Son intégration au build, couplée à une vérification en intégration continue, évite qu’une requête désynchronisée du schéma ne passe inaperçue jusqu’en production.