Un WordPress « headless » garde ce que WordPress fait bien, l'écriture et la gestion des contenus, et confie l'affichage du site à un autre outil. Les visiteurs ne voient plus les pages générées par le thème WordPress : ils voient un site construit par un framework comme Astro, alimenté par l'API de WordPress.

C'est une architecture puissante, mais pas une mode à suivre par principe. Ce guide couvre les choix à faire, du branchement de l'API à la mise en ligne.

Ce que le headless change concrètement

Dans un WordPress classique, le même serveur stocke les contenus, exécute le thème et les extensions, puis renvoie chaque page au visiteur. En headless, les rôles se séparent :

  • WordPress devient un back-office : on y écrit, on y range, on y gère les médias.
  • Le front, par exemple un site Astro, récupère les contenus par API et produit des pages HTML.
  • L'hébergement du front sert ces pages depuis un CDN, au plus près des visiteurs.

Les bénéfices : des pages très rapides, un site public qui n'expose plus WordPress aux attaques, une liberté totale sur le design et l'intégration d'autres sources de données.

Quand c'est une bonne idée, et quand ça ne l'est pas

Le headless se justifie quand :

  • la performance pèse sur le business (SEO, conversion, trafic mobile) ;
  • le site agrège plusieurs sources : WordPress pour les articles, un CRM, un outil de réservation, un catalogue ;
  • l'équipe éditoriale tient à WordPress, mais le site doit sortir des limites d'un thème.

Il est moins pertinent quand :

  • le site repose sur des extensions qui produisent du front : constructeur de pages, boutique WooCommerce complète, formulaires complexes, espace membres ;
  • il n'y a personne pour maintenir deux briques : WordPress d'un côté, le front et son déploiement de l'autre ;
  • l'équipe a besoin de voir la page finale en éditant, à la manière d'un constructeur visuel.

L'architecture type

  1. WordPress sur un hébergement modeste, idéalement sur un sous-domaine dédié (admin.mondomaine.fr), avec un accès restreint.
  2. Le front Astro dans un dépôt Git, qui lit l'API WordPress au moment de la construction du site.
  3. Un hébergement statique ou edge (Cloudflare, Netlify, Vercel) qui reconstruit et publie le site à chaque modification.
  4. Un déclencheur : à chaque publication dans WordPress, un appel relance la construction du front.

Récupérer le contenu : API REST ou GraphQL

WordPress embarque une API REST depuis longtemps, sans extension. Les articles publiés sont disponibles à l'adresse /wp-json/wp/v2/posts.

const res = await fetch(
  'https://admin.mondomaine.fr/wp-json/wp/v2/posts?per_page=100&_embed'
);
const posts = await res.json();
const totalPages = Number(res.headers.get('X-WP-TotalPages'));

Trois détails à connaître :

  • le paramètre _embed ajoute l'image mise en avant, l'auteur et les catégories dans la même réponse ;
  • l'API renvoie 100 éléments au maximum par requête : au-delà, il faut paginer avec page=2, page=3, en s'appuyant sur l'en-tête X-WP-TotalPages ;
  • les champs SEO de Yoast sont exposés dans yoast_head_json, ce qui évite de ressaisir les titres et descriptions.

L'alternative est WPGraphQL, une extension qui expose un schéma GraphQL. Elle permet de demander exactement les champs voulus en une requête, ce qui devient intéressant avec des champs personnalisés (ACF) ou des relations complexes. Pour un blog et quelques pages, l'API REST suffit largement.

Brancher Astro sur WordPress

Astro sait charger des contenus externes dans ses collections. Un chargeur minimal ressemble à ceci :

// src/content.config.ts
import { defineCollection } from 'astro:content';
import { z } from 'astro/zod';

const posts = defineCollection({
  loader: async () => {
    const res = await fetch(`${import.meta.env.WP_URL}/wp-json/wp/v2/posts?per_page=100&_embed`);
    const data = await res.json();
    return data.map((post) => ({
      id: post.slug,
      title: post.title.rendered,
      html: post.content.rendered,
      date: post.date,
    }));
  },
  schema: z.object({ title: z.string(), html: z.string(), date: z.coerce.date() }),
});

export const collections = { posts };

Les pages du blog se construisent ensuite comme avec n'importe quelle collection Astro. Le HTML vient de WordPress : prévoyez une feuille de style pour les blocs de l'éditeur (titres, citations, galeries, tableaux).

Publier sans reconstruire à la main

Le site étant construit à l'avance, chaque publication doit relancer une construction. La plupart des hébergeurs fournissent une URL de déclenchement (deploy hook). Côté WordPress, quelques lignes dans une extension maison suffisent :

add_action('transition_post_status', function ($new, $old, $post) {
    if ($new === 'publish' || $old === 'publish') {
        wp_remote_post(DEPLOY_HOOK_URL, ['blocking' => false]);
    }
}, 10, 3);

La constante DEPLOY_HOOK_URL se déclare dans wp-config.php, jamais dans le code versionné. Comptez une à deux minutes entre la publication et la mise en ligne.

Les aperçus de brouillons

C'est le point le plus souvent oublié. Un brouillon n'est pas visible par l'API publique : il faut une route d'aperçu sur le front, rendue à la demande, qui interroge l'API avec une authentification. Les mots de passe d'application de WordPress (Profil, puis Mots de passe d'application) permettent cette authentification sans exposer le mot de passe principal. La route d'aperçu ne doit être ni indexée, ni accessible sans jeton.

Le SEO : ne rien perdre en route

  • Titres, descriptions et balises Open Graph : reprenez-les depuis yoast_head_json ou les champs de votre extension SEO.
  • Le plan du site est désormais produit par le front, pas par WordPress.
  • Les URL doivent rester identiques à l'ancien site, ou être redirigées en 301.
  • Les liens internes écrits dans les contenus pointent parfois vers le domaine du back-office : réécrivez-les au moment de la construction.
  • Les images doivent garder leurs textes alternatifs et passer par l'optimisation du front.

La sécurité

Le site public n'exécute plus WordPress, mais le back-office existe toujours :

  • restreignez l'accès à l'administration (protection par IP, accès Cloudflare, ou au minimum double authentification) ;
  • désactivez XML-RPC et masquez l'énumération des utilisateurs (/wp-json/wp/v2/users) ;
  • empêchez l'indexation du domaine du back-office ;
  • continuez les mises à jour du cœur et des extensions : headless ne veut pas dire sans maintenance.

Le déploiement

Le front construit est un ensemble de fichiers HTML, CSS et d'images : il se déploie sur un CDN à coût très faible, souvent gratuit pour un site vitrine. WordPress, déchargé du trafic public, se contente d'un petit hébergement. Le dépôt Git du front, relié à l'hébergeur, déploie automatiquement à chaque modification du code.

La checklist avant de se lancer

  1. Lister les extensions qui produisent du front et leur trouver un remplaçant.
  2. Choisir entre API REST et WPGraphQL selon la complexité des contenus.
  3. Prévoir les aperçus de brouillons dès le départ.
  4. Reporter tous les éléments SEO et les redirections.
  5. Sécuriser et isoler le back-office.
  6. Automatiser la reconstruction à chaque publication.

Vous hésitez entre un WordPress classique et une architecture headless ? Découvrez mon accompagnement en création de site WordPress ou parlons de votre projet.