La preview WordPress qui ne fonctionnait pas en headless : notre déconvenue

C’était l’un des tout premiers projets headless de l’agence, avant même que ce mot ne revienne dans toutes nos réunions commerciales. Un site vitrine consommait l’API REST de WordPress depuis un front React fait maison, sans framework de génération statique, avec un rendu côté serveur artisanal. Tout fonctionnait bien, jusqu’au jour où la rédactrice du client a cliqué sur le bouton « Aperçu » d’un article en cours de modification, pour voir apparaître… la version déjà publiée, sans aucune de ses retouches.

Ce récit ne traite pas du piège plus général de la prévisualisation en headless, un sujet que nous avons largement développé depuis dans un autre article de ce blog. Il raconte simplement cette découverte précise, sur ce projet précis, et l’oubli tout bête qui en était la cause.

Le symptôme, tel qu’il nous a été rapporté

La rédactrice modifiait un article déjà publié, cliquait sur « Aperçu » depuis l’éditeur classique de WordPress, et se retrouvait sur l’URL du front générée par WordPress lui-même, du type https://exemple.fr/mon-article/?preview=true&preview_id=142. Le front React affichait bien une page, mais son contenu correspondait à la version publiée en base de données, pas aux modifications en cours d’écriture, pourtant visibles dans l’éditeur au moment du clic.

Ce que nous avons d’abord soupçonné, à tort

Notre premier réflexe a été de chercher du côté du cache : peut-être qu’une couche de cache HTTP retenait une ancienne version de la page. Nous avons vidé tous les caches possibles, côté serveur et côté CDN, sans aucun changement de comportement. Le problème n’était pas un cache obsolète : la donnée fraîchement demandée à l’API REST était, elle-même, la version publiée, pas le brouillon.

Le vrai coupable : un appel API qui ignorait le contexte de prévisualisation

En reprenant le code du front, la cause est apparue avec évidence. L’appel à l’API REST pour récupérer un article se contentait de lire le slug présent dans l’URL, sans jamais regarder les paramètres preview et preview_id pourtant transmis par WordPress lui-même dans le lien d’aperçu :

// Ce que faisait le front, à tort :
fetch(`/wp-json/wp/v2/posts?slug=${slug}`)

// Ce qu'il fallait faire pour honorer un aperçu :
const params = new URLSearchParams(window.location.search)
const isPreview = params.get('preview') === 'true'
const previewId = params.get('preview_id')

const url = isPreview
  ? `/wp-json/wp/v2/posts/${previewId}?context=edit`
  : `/wp-json/wp/v2/posts?slug=${slug}`

fetch(url, {
  headers: isPreview
    ? { Authorization: `Bearer ${tokenAuthentifie}` }
    : {}
})

Deux éléments manquaient à la fois : la lecture du paramètre preview_id pour cibler le bon article, et le passage en context=edit avec une authentification valide, seul moyen pour l’API REST d’accepter de renvoyer le contenu d’une révision non publiée à quelqu’un.

Pourquoi ce détail nous avait échappé au départ

Sur nos premiers projets headless de l’époque, l’essentiel de nos efforts portait sur le rendu du contenu publié, le référencement et la performance. La prévisualisation d’un brouillon nous semblait un cas secondaire, presque annexe, alors qu’elle conditionne directement le confort quotidien d’une équipe éditoriale. Cette expérience nous a appris à tester systématiquement le parcours de prévisualisation dès la recette d’un projet headless, au même titre que la publication elle-même.

Un projet headless qui casse la prévisualisation n’est pas un détail technique mineur pour un client : c’est, à ses yeux, un site qui ne fonctionne pas, quelle que soit la qualité du reste.

Ce que nous avons changé depuis, sur ce projet et les suivants

• Toute page de front doit lire explicitement les paramètres preview et preview_id transmis par WordPress avant de décider quel appel API effectuer.
• Le passage en context=edit exige une authentification, ce qui impose de générer un jeton ou un mot de passe d’application dédié à cet usage précis.
• La recette d’un projet inclut désormais systématiquement un scénario « modifier un article publié, cliquer sur Aperçu, vérifier que les modifications apparaissent ».

En résumé

Ce n’était pas un bug caché dans les entrailles de WordPress, ni un problème de cache mal configuré : c’était simplement un front qui ne regardait pas les bons paramètres d’URL. La leçon la plus utile de cette mésaventure n’est pas technique, elle est méthodologique : sur un projet headless, la prévisualisation mérite un test dédié dès les premières livraisons, avant qu’une rédactrice ne le découvre à votre place, un jour où ça compte.