La sortie de la version 4 de gatsby-source-wordpress a surpris une partie des équipes qui avaient construit leurs projets sur l’ancienne version, basée sur l’API REST de WordPress. Le changement n’est pas cosmétique : cette réécriture complète du plugin source abandonne l’API REST au profit exclusif de WPGraphQL, qui devient une dépendance obligatoire plutôt qu’une alternative parmi d’autres.
Cet article détaille ce que ce changement implique concrètement pour un projet Gatsby-WordPress, sans reprendre les enseignements plus généraux tirés de notre propre retour d’expérience Gatsby publié en 2020, qui portait sur l’ancienne version REST du plugin.
Pourquoi ce changement de fondation
L’ancienne version de gatsby-source-wordpress, basée sur l’API REST, souffrait d’un problème structurel : chaque type de contenu, chaque champ personnalisé, chaque relation entre objets nécessitait une configuration manuelle côté plugin pour être correctement importé dans le graphe de données Gatsby. WPGraphQL, en exposant nativement un schéma GraphQL typé et introspectable, permet à la version 4 de découvrir automatiquement la structure des données WordPress, y compris les champs ajoutés par des extensions tierces compatibles WPGraphQL (comme WPGraphQL for ACF).
WPGraphQL, une dépendance non contournable
Le point le plus structurant pour les équipes en migration : sans l’extension WPGraphQL installée et activée côté WordPress, gatsby-source-wordpress v4 ne fonctionne tout simplement pas. Ce n’est plus une option de configuration comme c’était le cas dans certaines versions intermédiaires du plugin ; c’est un prérequis absolu du build.
// gatsby-config.js
module.exports = {
plugins: [
{
resolve: `gatsby-source-wordpress`,
options: {
url: `https://exemple.fr/graphql`,
schema: {
timeout: 30000,
perPage: 50,
},
},
},
],
};Notez que l’URL configurée pointe désormais vers l’endpoint GraphQL (/graphql), et non plus vers /wp-json comme avec l’ancienne version REST du plugin.
Builds incrémentaux basés sur le cache de nœuds
La version 4 introduit un système de cache persistant entre les builds, qui compare l’état du schéma WPGraphQL et des données récupérées avec le build précédent, pour ne retraiter que ce qui a réellement changé. Sur un site de plusieurs milliers de contenus, ce mécanisme réduit sensiblement le temps de build lors des mises à jour incrémentales, comparé à une réimportation complète à chaque build.
{
"resolve": "gatsby-source-wordpress",
"options": {
"url": "https://exemple.fr/graphql",
"schema": {
"requestConcurrency": 15,
"previewRequestConcurrency": 5
},
"type": {
"Post": {
"limit": process.env.NODE_ENV === "development" ? 50 : undefined
}
}
}
}Limiter le nombre d’articles importés en environnement de développement (via limit) reste une pratique utile pour accélérer les itérations locales, sans attendre l’import complet du catalogue à chaque redémarrage du serveur de développement.
Prévisualisation des brouillons repensée
La gestion de la prévisualisation change également de mécanisme : la version 4 s’appuie sur un système d’aperçu qui interroge WPGraphQL en temps réel pour un contenu spécifique, plutôt que de reconstruire l’ensemble du site à chaque modification de brouillon. Ce fonctionnement demande une configuration dédiée côté WordPress (webhook de prévisualisation) et côté Gatsby Cloud ou l’infrastructure de build utilisée, distincte du mécanisme de build incrémental standard.
Migration depuis l’ancienne version : les points de friction
| Élément | Version REST (v3 et antérieures) | Version 4 (WPGraphQL) |
|---|---|---|
| Champs personnalisés (ACF) | Configuration manuelle par champ | Découverte automatique via WPGraphQL for ACF |
| Requêtes GraphQL côté Gatsby | Noms de champs générés depuis les endpoints REST | Noms de champs directement issus du schéma WPGraphQL |
| Dépendances WordPress requises | API REST native uniquement | Extension WPGraphQL obligatoire |
La conséquence la plus concrète pour une équipe en migration : la quasi-totalité des requêtes GraphQL écrites dans les pages et composants Gatsby doivent être réécrites, les noms de champs et de types ayant changé avec la nouvelle source de schéma. Ce n’est pas une migration qui se fait en modifiant seulement la configuration du plugin.
Ce qu’il faut vérifier avant de migrer
- La compatibilité des extensions WPGraphQL tierces utilisées (WPGraphQL for ACF, WPGraphQL Yoast SEO) avec la version de WPGraphQL requise par le plugin source v4.
- Le temps de build réel sur un environnement représentatif du catalogue de production, avant de valider la migration en environnement critique.
- La configuration de la prévisualisation, à tester spécifiquement puisqu’elle repose sur un mécanisme distinct du reste de l’import.
Une migration vers
gatsby-source-wordpressv4 n’est pas une mise à jour mineure malgré le numéro de version qui pourrait le laisser penser : c’est un changement de fondation qui mérite d’être traité comme tel, avec un budget de test proportionné.
En résumé
La version 4 de gatsby-source-wordpress impose WPGraphQL comme unique source de données, en échange d’une découverte automatique du schéma, de builds incrémentaux plus efficaces et d’une prévisualisation repensée. Pour les projets existants sur l’ancienne version REST, la migration implique de réécrire l’essentiel des requêtes GraphQL et de vérifier la compatibilité des extensions tierces avant de s’engager.
