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

> Écrire des requêtes GraphQL sans typage, c'est se priver de l'autocomplétion et découvrir les erreurs en production. GraphQL Code Generator corrige ça.

- Auteur : Clément Hadrot
- Publié le : 2022-05-05
- Mis à jour le : 2022-05-05
- Catégorie : Headless & API
- URL : https://wpmoderne.dev.wordpress-developpement.fr/headless/types-typescript-schema-wpgraphql-codegen/

## L’essentiel

- Les types sont générés directement depuis le schéma introspecté
- Autocomplétion fiable sur les champs réellement disponibles
- Intégration au build pour détecter les régressions de schéma

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

> L'essentiel à retenir : Les types sont générés directement depuis le schéma introspecté ; Autocomplétion fiable sur les champs réellement disponibles ; Intégration au build pour détecter les régressions de schéma

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.