Projet Niveau 4 — HeadlessShelf : front Next.js sur WordPress

⏱️ TL;DR — Le projet signature de votre profil : brancher un front Next.js 15 (App Router) sur votre WordPress wpr-books en headless. Liste des livres en SSG, fiche livre en ISR, prévisualisation des brouillons via Draft Mode, WordPress réduit à une source de données. C’est la compétence rare et premium de la Partie 9 et de la Partie 13 — vous en faites une démo réelle et déployable.

🎯 Niveau & objectifs

Niveau : 4 (expert). Prérequis : Niveau 3 (endpoint wpr/v1/books en place) ; maîtrise Next.js App Router.
Durée indicative : 10–16 h.
Vous allez pratiquer : consommation REST/WPGraphQL, fetch + revalidate, generateStaticParams, ISR, Draft Mode (previews), Application Passwords, CORS, découplage front/back.

📋 Cahier des charges

Contexte — La librairie veut un site ultra-rapide et moderne côté visiteur, tout en gardant WordPress comme back-office éditorial. Vous livrez HeadlessShelf, le front Next.js.

Objectif — Un front Next.js autonome qui consomme le catalogue WordPress, statique par défaut, avec revalidation et prévisualisation des brouillons.

Périmètre inclus

Un projet Next.js 15 séparé (App Router, TypeScript).
Page catalogue /livres : liste SSG depuis GET /wp-json/wpr/v1/books, avec filtrage par genre.
Page livre /livres/[slug] : ISR (generateStaticParams + revalidate), affichage titre/genre/ISBN/prix/résumé.
Draft Mode : une route de preview qui, avec un secret, bascule en rendu dynamique et affiche les brouillons (auth via Application Password).
Revalidation : ISR temporel ou revalidation à la demande déclenchée par un webhook save_post (au choix, documenté).
Gestion d’erreurs : 404 propre pour un slug inconnu, états de chargement.
Un sitemap.xml généré, et les métadonnées SEO par livre (generateMetadata).

Périmètre exclu — Pas de panier / paiement (c’est le territoire WooCommerce, Niveau 5), pas d’authentification visiteur, pas d’écriture depuis le front.

Contraintes

WordPress reste inchangé côté contenu : le front ne fait que lire (sauf revalidation).
Les secrets (Application Password, secret de preview) en variables d’environnement, jamais commités.
CORS correctement configuré si les domaines diffèrent.

Livrables

Le dépôt Next.js (HeadlessShelf), déployable (Vercel ou équivalent).
Un README d’architecture : schéma back↔front, stratégie de cache, comment lancer une preview.

✅ Critères de réussite

/livres s’affiche en statique (vérifiable : build génère les pages) et liste le catalogue.
/livres/[slug] est pré-rendu pour les livres existants et se revalide.
Un livre publié après le build finit par apparaître (ISR/revalidation) — vous savez expliquer le délai.
Un brouillon est visible uniquement via l’URL de preview signée, pas en public.
Un slug inexistant renvoie un 404 Next.js propre.
Les secrets ne sont pas dans le code ; le front ne casse pas si WordPress est momentanément lent (gestion d’erreur).

🗺️ Endroits à visiter

Endroit	Où	Pourquoi y aller
`/wp-json/wpr/v1/books`	navigateur	Votre contrat de données ; testez les paramètres
`/wp-json/wp/v2/` & schémas	navigateur	Comprendre pagination (`X-WP-TotalPages`), champs
Application Passwords	Comptes → profil	Auth machine-to-machine pour lire les brouillons
WPGraphQL (si installé) → IDE	wp-admin	Alternative typée au REST ; comparez les deux approches
Next.js : `fetch` cache/revalidate	nextjs.org/docs	`force-cache`, `revalidate`, `no-store` : la clé de l’ISR
Next.js : Draft Mode	nextjs.org/docs	Le mécanisme officiel de preview
`generateStaticParams` / `generateMetadata`	nextjs.org/docs	Pré-génération des routes + SEO

💡 Pour un dev React — Ici WordPress n’est plus qu’un CMS headless : votre fetch vers /wp-json/wpr/v1/books est identique à un appel vers n’importe quelle API. Toute votre expertise Next.js (SSG/ISR, streaming, cache) s’applique directement. Le seul « accent » WordPress à connaître : la pagination par headers (X-WP-TotalPages) et l’auth par Application Password pour les brouillons. C’est exactement la mission que vous facturez le plus cher en freelance (Partie 13).

⚠️ Piège — L’invalidation de cache est le vrai sujet du headless. Un éditeur qui publie et « ne voit rien changer » sur le front croit que c’est cassé. Décidez tôt : ISR temporel (simple, délai) ou revalidation à la demande via webhook (frais, plus de plomberie) — et documentez le comportement attendu.

🚀 Étapes suggérées

create-next-app ; variable WP_API_URL.
/livres en SSG : fetch liste, rendu de cartes.
/livres/[slug] : generateStaticParams + fetch détail + ISR.
generateMetadata + sitemap.ts.
Draft Mode : route d’activation signée + fetch authentifié des brouillons.
Revalidation : choisir ISR temporel ou webhook save_post → route /api/revalidate.
Gestion 404 / erreurs / états de chargement.
Déployer ; documenter l’archi.

🎁 Bonus

Ajoutez WPGraphQL et proposez une variante GraphQL typée du fetch.
Implémentez la revalidation à la demande complète (hook save_post → fetch signé vers /api/revalidate).
Ajoutez une recherche côté front (params REST search).

🔗 Chapitres du cours liés

Partie 9 — REST API & WordPress headless (Next.js)

Projet suivant : Niveau 5 — wpr-books Pro, produit freemium.