Payload CMS 3 — Implémenter votre CMS Headless TypeScript-native

#Payload CMS 3 — L'alternative open-source à Contentful et Sanity

Payload CMS est un CMS headless open-source né en 2021, passé en version 3.0 en novembre 2024 avec une réécriture majeure qui en fait aujourd'hui l'un des CMS headless les plus intéressants pour les équipes TypeScript. Voyons précisément ce que chaque concurrent propose — et où Payload se distingue.

Contentful est 100 % SaaS hébergé, sans option d'auto-hébergement. Son modèle freemium devient rapidement coûteux dès que vous dépassez les limites du plan gratuit (nombre de types de contenu, d'entrées, d'assets, d'utilisateurs). Le principal grief des équipes techniques : les schémas sont définis dans l'interface graphique, pas en code — ce qui complique le versionning et la reproductibilité des environnements. L'API de livraison de contenu est puissante, mais vous payez chaque requête au-delà d'un certain quota.

Sanity propose un modèle hybride avec des datasets hébergés sur leur infrastructure (même en plan payant, les données ne sont pas chez vous) et une tarification qui évolue avec le volume d'utilisation et les collaborateurs. Son point fort réel : GROQ (leur langage de requête) et l'expérience d'édition (Portable Text + Studio). Son point faible pour les équipes soucieuses de souveraineté : dépendance stricte à l'API Sanity, pas d'option self-hosted.

Strapi est open-source Node.js, ce qui le rapproche de Payload sur le papier. Mais Strapi reste majoritairement JavaScript avec un TypeScript partiel moins rigoureux, et la v5 (2024) a souffert d'une adoption plus lente que prévue. Les schémas sont hybrides (code + GUI), et l'architecture plugin est moins cohérente qu'avec Payload. Strapi Cloud existe mais reste optionnel.

Payload CMS 3, lui, est TypeScript-first par design : chaque collection, chaque champ, chaque hook est un module TypeScript avec des types stricts. L'interface d'administration est une application Next.js App Router — elle tourne dans la même instance Next.js que votre front-end, ce qui simplifie drastiquement l'infrastructure. Les schémas sont définis exclusivement en code, versionnable en git comme n'importe quel module. Pas de pricing par siège, pas de limite d'API, vos données dans votre propre Postgres ou MongoDB.

Quand choisir Payload plutôt que les alternatives ? Quatre signaux forts : (1) votre équipe technique est à l'aise avec TypeScript et préfère définir les schémas en code plutôt que dans une GUI, (2) vous avez des exigences de souveraineté des données (RGPD strict, données en France, pas de dépendance à des API SaaS US pour l'accès à votre contenu), (3) vos besoins en types de contenu ou en volumétrie rendraient Contentful ou Sanity coûteux sur 3 ans, (4) vous construisez une application Next.js 15 et voulez une intégration CMS sans overhead architectural.

Quand Payload n'est pas le bon choix : si votre équipe de contenu est non technique et que vous avez besoin d'une expérience d'édition clé-en-main très poussée sans configuration, si vous avez besoin d'un CDN de contenu global avec edge caching intégré (Contentful et Sanity excellent ici), ou si vous devez démarrer en moins d'une semaine sans phase de setup.

#Architecture Payload CMS 3 — Collections, Globals, Rich Text

#Collections

Une Collection est le concept central de Payload : c'est un type de contenu répétable, chaque instance étant un document stocké dans la base de données. Chaque Collection mappe directement à une table Postgres ou une collection MongoDB. Exemples typiques : Posts, CaseStudies, Products, Pages, MediaLibrary, Users. Chaque Collection génère automatiquement des routes d'API REST (GET /api/posts, POST /api/posts, PATCH /api/posts/:id, DELETE /api/posts/:id) et les équivalents GraphQL. La configuration d'une Collection est un objet TypeScript pur — ce qui signifie que vos types sont disponibles dans tout votre projet via l'auto-génération de types Payload.

#Champs (Fields)

Payload propose un système de champs exhaustif, tous typés TypeScript. Les champs de base : text, textarea, number, email, date, checkbox, select, radio. Les champs relationnels : relationship (un-à-un, un-à-plusieurs, polymorphe), upload (assets media). Les champs composites : array (liste répétable de sous-champs), blocks (liste de blocs hétérogènes, chacun ayant son propre schéma), group (regroupement de champs sans répétition), tabs (interface tabulée côté admin), row (disposition en ligne). Les champs avancés : richText (Lexical editor ou Slate selon version), code (éditeur de code avec highlighting), json (stockage JSON arbitraire). Chaque champ accepte une logique validate TypeScript custom, une configuration access par opération (create, read, update), et des hooks beforeChange / afterChange.

#Globals

Un Global est un document singleton — il n'en existe qu'un seul en base. Usage typique : configuration globale du site (SiteSettings), navigation principale (MainNavigation), footer (Footer), bannière de cookies, configuration des emails transactionnels. Un Global génère une API REST (GET /api/globals/site-settings, POST /api/globals/site-settings) et son équivalent GraphQL. Particularité importante : les Globals sont stockés en cache dans Payload, ce qui les rend très performants pour les composants Layout qui les consomment à chaque requête.

#Rich Text Lexical

Payload 3 utilise Lexical (l'éditeur de Meta, qui propulse aussi l'éditeur Facebook) comme éditeur rich text par défaut, avec un système de blocs custom. Chaque bloc Lexical est défini comme une Collection Payload (avec ses propres champs TypeScript), et correspond côté front-end à un composant React Server Component. Exemples de blocs custom typiques : HeroBlock, CTABlock, TestimonialsBlock, CodeSnippetBlock, ImageGalleryBlock, EmbedVideoBlock. Cette architecture donne aux éditeurs une flexibilité maximale pour construire des pages complexes, tout en maintenant des contraintes de structure côté développeur. Le rendu côté Next.js est typé : le type du contenu rich text est auto-généré depuis la configuration Lexical, ce qui élimine les any et les erreurs runtime au moment du rendu.

#Access Control

Payload implémente un RBAC (Role-Based Access Control) granulaire défini en TypeScript. Le contrôle d'accès peut être défini à trois niveaux : Collection (qui peut créer, lire, modifier, supprimer les documents de cette Collection), Document (contrôle par document individuel, par exemple "un auteur ne peut modifier que ses propres articles"), Field (contrôle par champ, par exemple "seul un admin peut modifier le champ publishedAt"). Chaque fonction d'access control reçoit le contexte complet (user, doc, req) et retourne un boolean ou un objet de filtre Payload — ce qui permet des logiques complexes (par exemple, un client B2B ne voit que les documents appartenant à son organisation).

#Hooks

Les Hooks Payload sont des fonctions TypeScript exécutées à des points précis du cycle de vie d'un document : beforeOperation, beforeValidate, beforeChange, afterChange, beforeRead, afterRead, beforeDelete, afterDelete. Usages typiques : générer un slug depuis le titre (beforeChange), invalider le cache Next.js après modification d'un article (afterChange), envoyer une notification Slack ou un email transactionnel (afterChange), peupler des champs calculés (beforeRead), synchroniser avec un système tiers (PIM, ERP) sur les modifications.

#Plugins

L'écosystème de plugins officiels Payload inclut : @payloadcms/plugin-form-builder (formulaires de contact et landing pages configurables côté admin), @payloadcms/plugin-nested-docs (arborescence de pages avec slugs imbriqués, indispensable pour les sites multi-niveaux), @payloadcms/plugin-seo (champs SEO meta title/description/og par document, avec scoring automatique), @payloadcms/plugin-redirects (gestion des redirections 301/302 depuis l'admin sans redéploiement), @payloadcms/plugin-search (indexation full-text Postgres ou Algolia depuis les documents Payload).

#Intégration Next.js 15 — App Router et React Server Components

L'intégration de Payload CMS 3 avec Next.js 15 est qualitativement différente de ce que proposent Contentful ou Sanity. Payload et Next.js tournent dans la même application Node.js — l'admin Payload est une route /admin dans votre application Next.js App Router, pas un service séparé. Ce choix architectural a des implications pratiques importantes.

Première implication : les appels de données depuis les pages Next.js vers Payload sont des appels de fonction directs (payload.find({ collection: 'posts', where: { ... } })), pas des appels HTTP. Sur une page qui consomme plusieurs collections Payload, cela élimine la latence réseau et simplifie drastiquement la gestion des erreurs. Pas de client REST ni de client GraphQL à configurer pour le front-end interne.

Deuxième implication : les types TypeScript des collections Payload sont disponibles directement dans vos composants. Payload génère automatiquement le fichier payload-types.ts depuis vos configurations de collections — vos Props React sont typées avec les mêmes types que vos documents CMS, sans couche de mapping manuelle.

Troisième implication : la revalidation du cache Next.js est native. Payload déclenche la revalidation On-Demand via les Hooks afterChange : quand un éditeur publie un article, le hook appelle revalidatePath('/blog/' + doc.slug) ou revalidateTag('posts') — le cache Next.js est invalidé immédiatement, sans redéploiement. Ce pattern est bien plus précis et performant que les stratégies de TTL court ou de revalidation complète du site.

Côté ISR (Incremental Static Regeneration) : les pages de contenu Next.js utilisent generateStaticParams pour pré-générer les pages les plus consultées au build, avec fallback blocking pour le reste. La revalidation on-demand via Payload hooks s'intègre parfaitement dans ce pattern.

Pour les projets où Payload est utilisé comme CMS headless pur (API seulement, front-end Next.js séparé ou mobile), les API REST et GraphQL auto-générées restent disponibles. Les réponses REST respectent la pagination Payload standard, le filtrage par champs, la profondeur de population des relations (paramètre depth). Les réponses GraphQL sont entièrement typées via le schema auto-généré.

#Base de données — Postgres vs MongoDB pour Payload 3

Payload 3 supporte officiellement deux bases de données : Postgres (via l'adaptateur Drizzle ORM) et MongoDB (via Mongoose). Le choix n'est pas anodin.

Postgres est l'option par défaut recommandée par Nehos pour la grande majorité des projets. Avantages : modèle relationnel adapté aux contenus structurés avec relations inter-collections (articles liés à des auteurs, produits liés à des catégories), indexation performante sur les champs texte et JSON, requêtes complexes (filtres combinés, tris, agrégations), support natif sur tous les hébergeurs managés majeurs (OVHcloud Managed Databases PostgreSQL, Neon, Supabase, Render). Postgres 16 est le choix Nehos standard : JSONB pour les champs riches, full-text search via tsvector, extensions pgvector si vous combinez Payload avec un layer RAG pour des fonctionnalités de recherche sémantique.

MongoDB reste pertinent dans deux cas spécifiques : le contenu est fortement imbriqué avec une structure variable (documents dont le schéma évolue fréquemment, comme des données de configuration complexes), ou le projet utilise déjà une infrastructure MongoDB Atlas existante qu'il n'est pas souhaitable de migrer. MongoDB offre aussi une flexibilité de schéma plus grande pendant les phases de prototypage rapide. Limitation pratique : les requêtes relationnelles complexes sont moins performantes en MongoDB qu'en Postgres, et MongoDB Atlas a un coût de scaling moins prévisible.

Recommandation Nehos pour les ETI françaises : Postgres 16 sur OVHcloud Managed Databases (France, option fr-1 ou fr-2, ISO 27001, SecNumCloud en cours de qualification). Avantages : souveraineté des données garantie contractuellement en France, pricing prévisible, sauvegardes automatiques, réplication, logs d'accès — tous les éléments nécessaires à une conformité RGPD documentée.

#Migration depuis WordPress / Contentful / Strapi vers Payload

La migration vers Payload est l'une des missions les plus fréquentes dans nos projets development. Le processus suit cinq étapes structurées.

Étape 1 — Mapping de schéma. On cartographie les types de contenu de l'existant vers les collections Payload. WordPress Post Types → Collections Payload, WP ACF fields → Payload Fields (avec correspondance type par type : text_field → text, wysiwyg → richText Lexical, image → upload, relationship → relationship, repeater → array ou blocks). Pour Contentful : Content Types → Collections, Fields → Fields. Pour Strapi : Content Types → Collections, Components → Blocks ou Groups. Cette phase produit un document de mapping validé avec l'équipe client avant tout développement.

Étape 2 — Export et transformation du contenu. WordPress : export via WP REST API (endpoint /wp-json/wp/v2/posts?per_page=100&page=X avec pagination) ou export XML natif WP, puis transformation via scripts TypeScript. Contentful : contentful export --space-id XXXXX produit un JSON exhaustif. Strapi : export via CLI Strapi ou API REST. Dans tous les cas, un script de transformation TypeScript mappe les données source vers le format d'import Payload (qui accepte les createMany via script Node.js direct sur la connexion Payload + Postgres).

Étape 3 — Migration des médias. Les assets (images, fichiers) sont récupérés depuis l'existant (WP uploads, Contentful CDN, Strapi uploads) et importés dans la Collection media Payload. Nehos configure systématiquement le storage Payload sur S3-compatible (OVHcloud Object Storage pour les projets souverains, ou AWS S3 selon contexte) avec génération automatique des tailles d'image via Sharp (intégré dans Payload). Les URLs des médias dans le contenu rich text sont mises à jour post-migration.

Étape 4 — Continuité des URLs. Les anciennes URLs sont mappées vers les nouvelles via le plugin @payloadcms/plugin-redirects pour les changements structurels de slug, complété par des redirections Next.js dans next.config.js pour les patterns plus complexes (ex. /category/slug → /blog/slug). On génère et on valide un fichier de mapping de redirections avant le basculement.

Étape 5 — Migration des utilisateurs admin. Les comptes utilisateurs WP, Contentful ou Strapi sont recréés dans la Collection users Payload avec les rôles appropriés. Pour les migrations depuis WordPress avec de nombreux auteurs, on automatise la création via script avec invitation par email (reset de mot de passe forcé à la première connexion).

#Déploiement self-hosted vs Vercel — Souveraineté et performance

Payload CMS 3 supporte nativement deux modèles de déploiement principaux, avec des implications différentes sur la souveraineté, les coûts et la complexité opérationnelle.

Self-hosted sur OVHcloud : l'application Payload + Next.js est déployée dans un conteneur Docker (ou Kubernetes pour les charges importantes) sur un VPS ou serveur dédié OVHcloud. Avantages majeurs pour les ETI françaises : données exclusivement hébergées en France (ISO 27001, conformité RGPD documentable contractuellement), coût prévisible à la capacité (pas de surprise de facturation liée au traffic), pas de limites imposées par un hébergeur SaaS. Complexité additionnelle : gestion du CI/CD (GitHub Actions + Docker Hub ou OVHcloud Registry), configuration du reverse proxy (Nginx ou Traefik), monitoring et alerting (Grafana + Prometheus ou Uptime Robot selon niveau de criticité), gestion des certificats TLS (Let's Encrypt via Certbot ou Traefik ACME).

Vercel : déploiement simplifié via vercel deploy ou intégration GitHub native. Preview deployments automatiques sur chaque PR — très utile pendant la phase de développement et de recette. CDN global Edge de Vercel inclus (Vercel Edge Network, 40+ régions). Limites : les données Postgres sont toujours dans la base que vous avez configurée (OVHcloud ou Neon), mais les logs d'accès, les métriques, les analytics et les fonctions serverless passent par l'infrastructure Vercel (US majority). Pour les projets sans exigence de souveraineté stricte, Vercel reste une excellente option de mise en production rapide.

Recommandation Nehos selon le profil client : pour les ETI françaises avec des données sensibles (BtoB, données personnelles clients, contenu interne) — OVHcloud self-hosted pour la production, Vercel pour les environnements de staging et de recette (compromis pragmatique entre simplicité de démo et souveraineté de la data live). Pour les scale-ups SaaS sans contrainte RGPD stricte sur le CMS — Vercel en production avec Neon (Postgres serverless) ou Supabase est une option valide et rapide à opérer.

#5 cas d'usage Payload CMS les plus performants

#1. Site marketing SaaS avec blog + case studies + documentation

Le cas d'usage le plus courant et le plus adapté à Payload. Collections typiques : Pages (pages marketing avec blocs Lexical), Posts (blog), CaseStudies (cas clients), Docs (documentation produit hiérarchique), Authors, Tags, Categories. Globals : SiteNavigation, Footer, SiteSettings, SEODefaults. L'avantage Payload vs WordPress ici est triple : TypeScript de bout en bout (zéro Any dans les composants qui consomment le CMS), performances Next.js ISR nativement compatibles, et coût total de possession inférieur dès que vous dépassez 10-20 pages marketing actives (pas de plugin payant, pas de limite API).

#2. Portail documentation technique ETI

Un Payload avec une Collection Documentation hiérarchique (via @payloadcms/plugin-nested-docs), des Globals de navigation latérale générée automatiquement depuis la structure, un système de versioning de documents (champ version + collection DocumentVersions liée), et un RBAC per-équipe (8 équipes = 8 rôles Payload avec accès limité à leurs sous-arborescences). Recherche full-text via Postgres tsvector ou intégration Algolia via @payloadcms/plugin-search. Multilingue FR/EN/DE via le plugin de localisation Payload (chaque Collection a des champs localized: true).

#3. Site multi-marques groupe ETI

Un seul Payload CMS central, N applications Next.js front-end distinctes (une par marque ou par filiale), chacune consommant Payload via API REST ou via appels directs si elles partagent la même instance Node.js. Les collections partagées (auteurs, assets media globaux) sont accessibles depuis toutes les marques, les collections spécifiques (articles marque A, produits marque B) sont filtrées par access control Payload via le champ brand: relationship. Avantage décisif vs une instance CMS par marque : cohérence des schemas, une seule source de vérité pour les assets partagés, un seul back-office pour les équipes éditoriales transverses.

#4. CMS pour application mobile React Native

Payload utilisé comme BaaS (Backend as a Service) léger : l'application mobile React Native consomme les endpoints REST Payload pour récupérer du contenu (actualités, promotions, tutoriels, notifications in-app) sans passer par une API custom à maintenir. L'Access Control Payload contrôle quelles collections sont publiques (lecture sans authentification) et lesquelles nécessitent un JWT (contenu premium). Les Hooks afterChange déclenchent des push notifications (Firebase FCM ou Expo Push) lors de la publication de nouveau contenu.

#5. CMS e-commerce contenu complémentaire à Medusa ou Shopify Hydrogen

Payload ne remplace pas un moteur e-commerce — il le complète. Sur un projet Medusa (headless commerce open-source) ou Shopify Hydrogen, Payload gère le contenu éditorial riche qui n'a pas sa place dans le catalogue produit : pages marque, guides d'achat, lookbooks, témoignages clients, contenu de catégories enrichi (SEO long-form), pages de campagnes saisonnières. Les deux systèmes coexistent dans la même application Next.js : Medusa/Shopify pour le panier et la transaction, Payload pour tout le contenu marketing et éditorial.

#Méthodologie de déploiement

Phase 1 — Sprint de design de schéma (1-2 semaines). Ateliers de travail avec les équipes métier et technique pour cartographier l'ensemble des types de contenu, identifier les relations inter-collections, définir les champs et leur typage, spécifier le RBAC (qui crée, qui édite, qui publie pour chaque collection). Output : schéma Payload complet en TypeScript reviewé et validé, maquette de l'interface d'administration.

Phase 2 — Build CMS (2-4 semaines). Configuration des Collections et Globals, implémentation des champs complexes (blocs Lexical custom, champs relationnels polymorphes), mise en place des Access Control et Hooks, configuration des plugins retenus (SEO, nested-docs, form-builder, redirects selon besoins), configuration du storage media, mise en place de l'environnement de staging (Vercel preview ou VPS OVHcloud dédié). Démo de l'admin en fin de phase avec les éditeurs.

Phase 3 — Intégration front-end Next.js (1-3 semaines). Développement des composants React Server Components consommant Payload, implémentation des stratégies de rendu (SSG + ISR pour le contenu public, SSR ou client-side pour les pages personnalisées), mise en place de la revalidation on-demand via Payload Hooks, optimisation des images (Next.js <Image> + Sharp Payload), intégration des métadonnées SEO depuis Payload (via generateMetadata Next.js).

Phase 4 — Migration de contenu et mise en production. Scripts de migration TypeScript, validation des données importées, tests de charge, configuration production OVHcloud (Docker Compose ou Kubernetes), mise en place du monitoring, basculement DNS avec plan de rollback documenté.

#ROI mesurable — Cas SaaS B2B migration Contentful → Payload

Cas client référence : scale-up SaaS B2B (outil de pilotage commercial, 80 utilisateurs internes éditeurs de contenu à partir de 4,8 k€ ARR). Contexte : coût abonnement Contentful Team atteignant48 000 €/an après croissance du volume de contenu et du nombre de collaborateurs éditeurs, limitations des API Contentful perturbant les temps de chargement aux heures de pic de trafic, dette technique accumulée sur les types TypeScript (générés via des tooling tiers non maintenus).

Mission Nehos sur 8 semaines : migration complète vers Payload CMS 3 sur OVHcloud (Postgres 16, Docker Compose, 2 VPS en haute disponibilité), refonte des schémas en TypeScript strict (0 any, 0 unknown non justifié), intégration Next.js 15 avec revalidation on-demand, migration de 1 200 documents de contenu depuis Contentful, formation des équipes éditoriales (8 sessions de 2h sur l'interface Payload).

Résultats à 12 mois : économie abonnement SaaS CMS de 48 000 €/an dès la première année, 0 API rate limit (les pics de trafic n'affectent plus les performances du CMS), TypeScript strict mode 100 % sur le périmètre CMS (réduction des erreurs runtime en production de 73 % sur ce périmètre), temps de déploiement d'un nouveau type de contenu réduit de 3 jours (cycle Contentful avec review et déploiement) à 4 heures (schéma TypeScript + review + merge + CI/CD). Investissement total mission Nehos :50 15 872 € HT. ROI de l'opération positif en moins de 14 mois en comptant uniquement l'économie d'abonnement.

#Tarification — 1,5 k€ HT

Trois fourchettes selon la complexité du projet. Site marketing SaaS standard (5-15 collections, blocs Lexical custom, intégration Next.js 15, sans migration de contenu existant, déploiement Vercel) : 1,5 k€ HT sur 6-10 semaines. Site marketing avec migration depuis WordPress ou Contentful (même périmètre plus scripts de migration, redirection 301, formation éditeurs) : 35 à 511 k€ HT sur 8-14 semaines. Portail documentaire ou site multi-marques complexe (RBAC multi-équipes, multi-locale, nombreuses collections, déploiement self-hosted OVHcloud haute disponibilité, support MCO post-launch) : 13,5 k€ HT sur 12-20 semaines.

Forait MCO mensuel optionnel après la mise en production : à partir de 825 € HT/mois selon le niveau de SLA (99,5 % ou 99,9 % uptime), la fréquence des mises à jour de dépendances (Payload major releases, Next.js updates), et le volume de demandes d'évolution mineures. Cadrage précis en 30 minutes : [RDV Payload CMS](https://calendly.com/raphael-poirier_/decouverte15min-nehos-groupe