# HTMX et WordPress : un entre-deux entre thème classique et front découplé
> Exploration d'une architecture où HTMX consomme des fragments HTML générés par WordPress via des endpoints REST dédiés, sans framework JavaScript côté client.
- Auteur : Clément Hadrot
- Publié le : 2025-10-23
- Mis à jour le : 2025-10-23
- Catégorie : Headless & API
- URL : https://wpmoderne.dev.wordpress-developpement.fr/headless/htmx-wordpress-entre-deux-theme-classique-front-decouple/
## L’essentiel
- HTMX interroge des endpoints REST WordPress qui renvoient du HTML déjà formaté plutôt que du JSON
- Cette approche évite l'écriture d'un client JavaScript de rendu, sans renoncer à des interactions dynamiques
- Elle convient surtout à des interactions ponctuelles, pas à un front applicatif complexe
La question posée par le client, une chambre consulaire régionale gérant un annuaire d'entreprises adhérentes, était inhabituelle pour une agence habituée aux projets React ou Vue : « avons-nous vraiment besoin d'un framework JavaScript pour ce site ? ». Le besoin réel se limitait à quelques interactions dynamiques précises : un filtre d'annuaire sans rechargement de page, un formulaire de contact avec validation en direct, et un système de favoris pour les visiteurs identifiés. Rien qui ressemble à une application complexe.
HTMX, une bibliothèque légère permettant de déclencher des requêtes HTTP directement depuis des attributs HTML et de remplacer des fragments de page avec la réponse reçue, a été retenue pour un prototype, avec WordPress comme fournisseur de ces fragments HTML via des endpoints REST personnalisés.
## Le principe : WordPress renvoie du HTML, pas du JSON
La différence fondamentale avec une architecture headless classique tient là : au lieu d'exposer des données structurées en JSON consommées et transformées en HTML côté client par React ou Vue, les endpoints REST personnalisés de ce projet renvoient directement du HTML déjà formaté, prêt à être injecté tel quel dans la page.
```
add_action('rest_api_init', function () {
register_rest_route('annuaire/v1', '/filtrer', [
'methods' => 'GET',
'callback' => 'annuaire_filtrer_fragment',
'permission_callback' => '__return_true',
]);
});
function annuaire_filtrer_fragment(WP_REST_Request $req) {
$secteur = sanitize_text_field($req->get_param('secteur'));
$entreprises = new WP_Query([
'post_type' => 'entreprise',
'meta_key' => 'secteur',
'meta_value' => $secteur,
]);
ob_start();
while ($entreprises->have_posts()) {
$entreprises->the_post();
get_template_part('fragments/carte-entreprise');
}
wp_reset_postdata();
$html = ob_get_clean();
return new WP_REST_Response($html, 200, ['Content-Type' => 'text/html']);
}
```
Côté page, le déclenchement de cette requête ne demande aucune ligne de JavaScript personnalisé, uniquement des attributs HTML lus par HTMX :
```
```
> L'essentiel à retenir : HTMX interroge des endpoints REST WordPress qui renvoient du HTML déjà formaté plutôt que du JSON ; Cette approche évite l'écriture d'un client JavaScript de rendu, sans renoncer à des interactions dynamiques ; Elle convient surtout à des interactions ponctuelles, pas à un front applicatif complexe
## Ce que cette approche a fait gagner
Le gain le plus net a été la disparition complète de la couche de transformation de données côté client : aucun composant de rendu à écrire en JavaScript, aucun état à synchroniser entre une réponse API et une structure de composants. Le template PHP utilisé pour générer la carte d'une entreprise dans le fragment renvoyé par l'API est littéralement le même fichier `get_template_part` que celui utilisé ailleurs sur le site pour un rendu classique non dynamique, ce qui évite toute duplication de logique d'affichage entre deux systèmes de rendu distincts.
Le poids total de JavaScript chargé par la page reste à 14 Ko pour l'intégralité de la bibliothèque HTMX, contre plusieurs centaines de kilo-octets pour un bundle React ou Vue classique avec ses dépendances, un écart qui a nettement amélioré les métriques de performance mobile mesurées sur ce site à trafic majoritairement mobile.
### Ce que cette approche ne permet pas
Le système de favoris, initialement pensé pour utiliser la même logique HTMX, a rapidement montré une limite : la persistance d'un état complexe côté client (la liste des favoris, potentiellement modifiée sur plusieurs pages successives sans rechargement complet à chaque fois) devenait plus naturelle à gérer avec un minimum d'état JavaScript local, HTMX n'étant pas conçu pour remplacer un gestionnaire d'état applicatif. La solution finale a mélangé HTMX pour l'affichage des fragments et une poignée de lignes de JavaScript natif, sans framework, pour synchroniser l'état des favoris avec le stockage local du navigateur.
## Les limites structurelles de cette approche pour un projet headless
- Le rendu HTML reste couplé au thème PHP WordPress : ce n'est donc pas un headless au sens strict du terme, mais un entre-deux qui garde WordPress comme moteur de rendu partiel, ce qui suppose de garder le thème PHP maintenu et à jour.
- Toute logique d'interface plus riche qu'un remplacement de fragment (animations complexes, composants avec un état interne profond) reste hors du champ d'application naturel de HTMX.
- La séparation classique entre équipe front et équipe back, courante sur les projets React ou Vue consommant une API, s'estompe : les fragments HTML sont écrits en PHP, ce qui redonne une place centrale aux développeurs WordPress traditionnels sur ce type de projet.
> HTMX ne remplace pas un front headless complet ; il propose une troisième voie pour les projets dont les besoins d'interactivité restent ponctuels et ne justifient pas le coût d'un framework JavaScript complet.
## Notre verdict
Pour ce projet précis, à la portée fonctionnelle volontairement limitée, l'approche HTMX a rempli son rôle sans le coût habituel d'une architecture headless complète. Elle ne se substitue pas à React ou Vue sur des projets aux besoins d'interface plus ambitieux, mais elle mérite d'être considérée sérieusement chaque fois qu'un client demande « avons-nous vraiment besoin d'un framework JavaScript pour ça », une question plus souvent pertinente qu'on ne le pense dans l'écosystème WordPress.