WordPress Headless consiste à utiliser WordPress uniquement comme back-end de gestion de contenu, en déléguant l'affichage à un framework JavaScript (Next.js, Nuxt, Astro). Le contenu est exposé via l'API REST ou WPGraphQL, et le front-end le consomme pour construire des pages rapides, flexibles et découplées du thème WordPress.

Ce guide couvre la mise en œuvre concrète d'une architecture headless : ce que WordPress expose nativement, ce qu'il faut configurer côté back-end, comment structurer le front-end, et les pièges que je rencontre régulièrement en production.

Je conçois des sites WordPress sur mesure, y compris en architecture headless. Si vous cherchez un accompagnement sur ce type de projet, je détaille mon approche sur ma page WordPress & Création web.

1. Ce qu'est réellement une architecture WordPress Headless

Dans une installation WordPress classique, le CMS gère à la fois le contenu (articles, pages, médias) et l'affichage (thème PHP, templates, boucle WordPress). Les deux sont couplés : chaque requête déclenche l'exécution de PHP côté serveur, qui génère le HTML envoyé au navigateur.

En headless, on coupe ce lien. WordPress ne sert plus de pages. Il devient une source de données accessible via une API. Un framework front-end (React, Vue, Svelte) se charge de récupérer ces données et de construire l'interface. Le navigateur ne parle plus à WordPress directement : il parle au front-end, qui lui-même interroge l'API WordPress.

Concrètement, ça signifie que :

  • Le thème WordPress n'est plus utilisé pour le rendu. Il peut être désactivé ou remplacé par un thème vide.
  • Le contenu est exposé en JSON via l'API REST (native depuis WordPress 4.7) ou via WPGraphQL (plugin).
  • Le front-end est un projet séparé, hébergé indépendamment (Vercel, Netlify, Cloudflare Pages, ou votre propre serveur).
  • Les mises à jour de contenu se font toujours dans l'admin WordPress. Les rédacteurs ne changent pas leurs habitudes.

2. Pourquoi passer en headless (et pourquoi ne pas le faire)

Le headless n'est pas une amélioration universelle. C'est un choix d'architecture qui apporte des avantages réels mais introduit aussi de la complexité. Voici ce que j'observe en pratique.

Ce que le headless apporte

  • Performance : le front-end peut être généré en statique (SSG) ou en rendu côté serveur (SSR), avec des temps de chargement nettement inférieurs à un WordPress classique. Plus de requêtes PHP à chaque page vue, plus de plugins qui ralentissent le rendu.
  • Liberté de design : vous n'êtes plus limité par les thèmes WordPress, les page builders ou les contraintes de Gutenberg. Le front-end est un projet React, Vue ou Astro : vous contrôlez chaque pixel.
  • Sécurité : WordPress n'est plus exposé au public. L'admin est accessible uniquement en interne ou via VPN. La surface d'attaque est considérablement réduite puisque le front-end ne contient ni PHP ni base de données.
  • Multi-canal : le même contenu WordPress peut alimenter un site web, une application mobile, un kiosque interactif ou un assistant vocal. L'API est le point d'accès unique.
  • Scalabilité : le front-end statique se distribue via CDN sans effort. WordPress gère uniquement les requêtes d'API, pas le trafic utilisateur direct.

Ce que le headless coûte

  • Complexité technique : vous maintenez deux projets (WordPress + front-end) au lieu d'un. Il faut des compétences en JavaScript moderne, en déploiement CI/CD, et en gestion d'API.
  • Perte de l'écosystème plugins front-end : les plugins WordPress qui agissent sur le rendu (builders, sliders, formulaires de contact natifs, SEO côté thème) ne fonctionnent plus. Tout doit être reconstruit côté front-end.
  • Prévisualisation du contenu : en headless, le bouton "Prévisualiser" de WordPress ne montre plus le résultat final. Il faut mettre en place un système de preview qui appelle le front-end avec les données de brouillon. C'est faisable mais ça demande du travail.
  • Coût d'hébergement double : un serveur pour WordPress, un hébergement pour le front-end (même si Vercel et Netlify offrent des plans gratuits généreux).

Mon avis : le headless vaut le coup si vous avez des exigences fortes en performance, en design sur mesure, ou en diffusion multi-canal. Pour un site vitrine de 10 pages avec un blog, un WordPress classique bien optimisé reste souvent le choix le plus pragmatique.

3. Configurer WordPress comme back-end headless

L'installation de WordPress reste standard. La différence se situe dans la configuration : on prépare WordPress à servir du contenu via API, pas des pages HTML.

L'API REST native

Depuis WordPress 4.7, l'API REST est activée par défaut. Aucun plugin nécessaire pour exposer les articles, pages, catégories, tags et médias. Les endpoints de base sont accessibles sur votresite.com/wp-json/wp/v2/.

Endpoints les plus utilisés :

  • /wp-json/wp/v2/posts : articles
  • /wp-json/wp/v2/pages : pages
  • /wp-json/wp/v2/categories : catégories
  • /wp-json/wp/v2/media : médias
  • /wp-json/wp/v2/users : auteurs

Chaque endpoint accepte des paramètres de filtrage (?per_page=, ?categories=, ?slug=, ?_fields=). Le paramètre _fields est particulièrement important : il permet de ne récupérer que les champs nécessaires, ce qui réduit le poids des réponses et améliore les temps de chargement.

WPGraphQL comme alternative

L'API REST retourne des réponses avec une structure fixe. Si vous avez besoin de récupérer un article avec ses catégories, son image à la une et les champs ACF en une seule requête, il faut soit faire plusieurs appels, soit enrichir les endpoints.

WPGraphQL résout ce problème. Avec GraphQL, vous décrivez exactement les données dont vous avez besoin dans votre requête, et l'API retourne uniquement ça. Une seule requête peut récupérer un article, son auteur, ses catégories et ses champs personnalisés.

Mon choix par défaut : WPGraphQL pour les projets avec des modèles de données riches (ACF, CPT, taxonomies imbriquées). L'API REST pour les projets simples (blog, pages statiques) où les endpoints natifs suffisent.

Exposer les champs personnalisés et les CPT

Par défaut, les Custom Post Types (CPT) et les champs ACF ne sont pas exposés dans l'API. Il faut le configurer explicitement.

Pour les CPT, ajoutez 'show_in_rest' => true dans votre appel à register_post_type(). Sans ça, le CPT n'apparaît tout simplement pas dans l'API REST.

Pour ACF avec l'API REST, le plugin ACF to REST API ajoute automatiquement les champs ACF aux réponses. Avec WPGraphQL, utilisez le plugin compagnon WPGraphQL for ACF qui expose vos groupes de champs dans le schéma GraphQL.

Piège fréquent : les champs de type "relation" ou "post object" dans ACF retournent des IDs par défaut, pas des objets complets. Il faut soit configurer le format de retour dans ACF, soit résoudre les relations côté front-end avec des requêtes supplémentaires. Avec WPGraphQL, ces relations sont résolues nativement dans la requête GraphQL.

Sécuriser l'instance WordPress

En headless, WordPress n'a plus besoin d'être accessible au public. Les bonnes pratiques que j'applique :

  • Restreindre l'accès à l'admin : accès uniquement via VPN ou IP whitelist. Le /wp-admin n'a aucune raison d'être accessible publiquement.
  • Limiter les endpoints API : désactivez les endpoints que vous n'utilisez pas. L'endpoint /wp-json/wp/v2/users expose par défaut la liste des auteurs avec leurs slugs, ce qui peut être un vecteur d'attaque.
  • Désactiver le rendu front-end WordPress : redirigez toutes les URLs publiques WordPress (sauf /wp-json/ et /wp-admin/) vers votre front-end. Un simple filtre template_redirect suffit.
  • Authentification pour les écritures : si votre front-end envoie des données vers WordPress (formulaires, commentaires), utilisez des JWT (JSON Web Tokens) ou l'authentification par clé d'application. Ne laissez jamais les endpoints POST ouverts sans authentification.

4. Choisir son stack front-end

Le choix du framework front-end détermine l'architecture, les performances et la maintenabilité du projet. Voici les options que je rencontre le plus souvent, avec leurs forces réelles.

Next.js (React)

C'est le framework le plus utilisé dans l'écosystème headless WordPress. Il supporte le SSR (Server Side Rendering), le SSG (Static Site Generation) et l'ISR (Incremental Static Regeneration). L'ISR est particulièrement intéressant : les pages sont générées en statique au build, puis regénérées en arrière-plan quand le contenu change dans WordPress, sans rebuild complet.

Quand l'utiliser : projets avec beaucoup de contenu dynamique, besoin de SEO solide, et équipe à l'aise avec React.

Nuxt (Vue.js)

L'équivalent de Next.js dans l'écosystème Vue. Supporte SSR, SSG et le rendu hybride. La courbe d'apprentissage de Vue est souvent perçue comme plus douce que celle de React, ce qui peut être un critère si votre équipe est junior.

Quand l'utiliser : mêmes cas que Next.js, avec une préférence pour Vue.js dans l'équipe.

Astro

Astro génère des pages statiques par défaut et n'envoie du JavaScript au navigateur que quand c'est nécessaire ("Islands Architecture"). Le résultat : des pages extrêmement légères. Astro supporte React, Vue, Svelte et d'autres frameworks comme composants à l'intérieur d'une même page.

Quand l'utiliser : sites orientés contenu (blogs, sites vitrine, documentation) où la performance est prioritaire et où l'interactivité côté client est limitée.

Gatsby

Gatsby est un générateur de site statique basé sur React qui récupère les données au moment du build. Il a été très populaire entre 2019 et 2022 pour le headless WordPress. Depuis, Next.js et Astro l'ont largement rattrapé en flexibilité. Les temps de build peuvent devenir problématiques sur des sites avec beaucoup de contenu (des milliers d'articles).

Mon avis : pour un nouveau projet en 2025/2026, je recommande Next.js ou Astro plutôt que Gatsby. Si vous avez un projet Gatsby existant qui fonctionne, pas de raison urgente de migrer.

5. Structurer le contenu dans WordPress pour le headless

La qualité de votre architecture headless dépend directement de la façon dont vous structurez le contenu dans WordPress. Un modèle de données mal pensé se paie cher côté front-end.

Custom Post Types et taxonomies

Définissez un CPT pour chaque type de contenu distinct. Par exemple : article (natif), projet, service, temoignage, evenement. Chaque CPT a ses propres champs ACF et ses taxonomies associées.

Convention de nommage que j'utilise :

  • CPT : singulier, en minuscule, sans accent (projet, service, temoignage)
  • Taxonomies : préfixe du CPT + nom (projet_categorie, service_type)
  • Champs ACF : préfixe du contexte + nom descriptif (projet_client, projet_url_live, service_tarif)

Cette discipline évite les collisions de noms et rend le schéma de données lisible quand le projet grossit.

Gestion des blocs Gutenberg en headless

C'est l'un des sujets les plus sous-estimés du headless. Le contenu Gutenberg est stocké en HTML avec des commentaires de blocs (<!-- wp:paragraph -->). Côté front-end, vous avez deux options :

  1. Rendre le HTML brut : vous récupérez le champ content.rendered et l'injectez dans votre page. Simple mais vous perdez le contrôle du style et vous importez potentiellement du HTML non sanitisé.
  2. Parser les blocs : vous utilisez l'API de parsing de blocs (via un endpoint REST custom ou WPGraphQL Gutenberg) pour récupérer chaque bloc avec ses attributs, puis vous mappez chaque type de bloc à un composant front-end dédié. Plus de travail initial, mais un contrôle total sur le rendu.

Mon approche : je parse les blocs pour les contenus structurés (pages de service, landing pages) et je rends le HTML brut pour les contenus éditoriaux simples (articles de blog) en appliquant des styles via des sélecteurs CSS sur les classes Gutenberg natives.

Gestion des médias et images

L'API WordPress retourne les URLs complètes des images hébergées sur votre serveur WordPress. En headless, ça pose deux problèmes :

  • Domaine différent : vos images pointent vers wp.votresite.com alors que votre front est sur votresite.com. Il faut soit configurer un reverse proxy, soit réécrire les URLs côté front.
  • Optimisation : WordPress génère des tailles d'image, mais elles ne sont pas forcément adaptées au responsive design de votre front-end. Je recommande d'utiliser un service d'optimisation d'images (Cloudflare Image Resizing, imgix, ou le composant next/image de Next.js) pour servir les bonnes dimensions automatiquement.

6. SEO en architecture headless

C'est le point qui inquiète le plus, à juste titre. En headless, WordPress ne génère plus les balises meta, les sitemaps, ni le balisage structuré. Tout doit être géré côté front-end, en récupérant les données SEO depuis WordPress.

Récupérer les données SEO de WordPress

Installez Yoast SEO ou Rank Math côté WordPress. Ces plugins ajoutent des champs SEO (title, meta description, canonical, Open Graph) à chaque contenu. Ces données sont ensuite exposées via l'API REST (Yoast ajoute un objet yoast_head_json aux réponses) ou via WPGraphQL avec les extensions appropriées (WPGraphQL Yoast SEO ou WPGraphQL Rank Math).

Côté front-end, vous récupérez ces données et les injectez dans le <head> de chaque page. Avec Next.js, c'est le composant Metadata ou generateMetadata(). Avec Nuxt, c'est useHead().

Sitemap et robots.txt

Le sitemap généré par Yoast ou Rank Math pointe vers les URLs WordPress, pas vers votre front-end. Il faut donc générer un sitemap côté front-end. Next.js et Nuxt proposent des modules de génération de sitemap qui interrogent l'API WordPress au moment du build.

Le robots.txt doit être hébergé côté front-end, pas côté WordPress. Assurez-vous qu'il référence le bon sitemap et qu'il ne bloque pas les crawlers sur votre front-end.

SSR obligatoire pour le SEO

Un site headless construit en SPA (Single Page Application) pure, sans rendu côté serveur, pose des problèmes d'indexation. Google peut interpréter le JavaScript, mais avec des délais et des limites. Pour un bon SEO, le SSR ou le SSG est indispensable. C'est une des raisons pour lesquelles Next.js et Nuxt sont les choix dominants : ils gèrent le rendu serveur nativement.

7. Prévisualisation et workflow éditorial

En headless, le bouton "Prévisualiser" de WordPress affiche la page dans le thème WordPress (qui n'existe plus ou qui est vide). Il faut recâbler la prévisualisation vers votre front-end.

Le mécanisme que je mets en place :

  1. Un filtre preview_post_link dans WordPress qui redirige vers une URL de preview côté front-end (par exemple votresite.com/api/preview?secret=xxx&id=123).
  2. Un endpoint API côté front-end qui reçoit la requête, vérifie le secret, récupère le brouillon via l'API WordPress (avec authentification), et affiche la page avec les données de brouillon.
  3. Next.js propose un "Draft Mode" natif pour ce cas d'usage. Nuxt et Astro nécessitent une implémentation custom mais le principe reste le même.

Point important : la prévisualisation nécessite que le front-end puisse accéder aux brouillons WordPress. Ça implique une authentification API (JWT ou Application Passwords) et une gestion des droits. Ne négligez pas cette étape : sans prévisualisation fonctionnelle, les rédacteurs perdent confiance dans le workflow éditorial.

8. Déploiement et hébergement

En headless, vous avez deux éléments à héberger séparément.

WordPress (back-end)

Hébergement classique sur un serveur PHP/MySQL. Puisque WordPress ne sert plus de pages au public, les exigences de performance sont moindres. Un hébergement mutualisé correct suffit souvent. L'important est la fiabilité et la rapidité des réponses API.

Je recommande d'activer un cache objet (Redis ou Memcached) pour accélérer les réponses API, et un plugin de cache REST comme WP REST Cache pour mettre en cache les réponses JSON.

Front-end

Les plateformes les plus utilisées pour héberger un front-end headless :

  • Vercel : intégration native avec Next.js, déploiement automatique via Git, edge functions. C'est mon choix par défaut pour les projets Next.js.
  • Netlify : excellent pour les sites statiques (Astro, Hugo, Gatsby), avec des fonctions serverless et un CDN global.
  • Cloudflare Pages : performant et généreux en plan gratuit. Supporte les frameworks SSR via Workers.
  • Hébergement propre : un VPS avec Node.js pour les projets qui nécessitent un contrôle total sur l'infrastructure.

Webhooks pour le rebuild automatique

Si vous utilisez le SSG, il faut déclencher un rebuild du front-end quand le contenu change dans WordPress. La solution : un webhook envoyé par WordPress à chaque publication ou mise à jour de contenu. Les plugins comme WP Webhooks ou un simple hook save_post custom peuvent appeler l'URL de rebuild de Vercel ou Netlify.

Avec l'ISR de Next.js, le rebuild complet n'est pas nécessaire : les pages se regénèrent individuellement en arrière-plan. C'est un des avantages majeurs de Next.js pour les sites headless à fort volume de contenu.

9. Checklist de mise en production

  1. WordPress installé avec l'API REST active (ou WPGraphQL configuré). CPT et champs ACF exposés dans l'API.
  2. Endpoints inutiles désactivés. Endpoint /users restreint. Accès admin limité par IP ou VPN.
  3. Front-end déployé sur Vercel, Netlify ou Cloudflare Pages avec SSR ou SSG activé.
  4. SEO opérationnel : données Yoast/Rank Math récupérées et injectées dans le <head>. Sitemap généré côté front. robots.txt en place.
  5. Prévisualisation fonctionnelle : les rédacteurs peuvent prévisualiser un brouillon sur le front-end avant publication.
  6. Webhook de rebuild configuré (SSG) ou ISR activé (Next.js) pour que les mises à jour de contenu se propagent automatiquement.
  7. Images optimisées : service d'image resizing en place, URLs réécrites si nécessaire.
  8. Performance testée : Lighthouse score > 90, TTFB < 200ms sur les pages principales.

Conclusion

WordPress Headless n'est pas une tendance : c'est une architecture qui répond à des besoins concrets de performance, de flexibilité et de sécurité. Mais c'est aussi un choix qui engage. Il demande des compétences JavaScript solides, une réflexion sur le modèle de données, et une infrastructure de déploiement maîtrisée.

Le point de départ est toujours le même : un WordPress bien structuré (CPT, ACF, convention de nommage) avec une API propre. Le front-end vient ensuite consommer ces données. Si vous débutez, commencez par un projet simple (blog en Next.js + API REST) pour valider la mécanique avant de scaler.

Si vous envisagez une architecture headless pour votre projet ou si vous avez besoin d'un accompagnement pour structurer votre WordPress comme back-end d'API, je détaille mes services WordPress ici.