Déployer un site headless avec Vercel et Next.js

Vue d'ensemble du déploiement headless

En architecture headless, le frontend Next.js et le backend WordPress sont hébergés séparément. Le frontend est déployé sur une plateforme optimisée pour les applications JavaScript (Vercel, Netlify, AWS Amplify), tandis que WordPress reste sur un hébergement PHP classique ou managé.

Pourquoi Vercel pour un frontend Next.js

Vercel est la plateforme créée par l'équipe qui développe Next.js. Elle offre une intégration native avec toutes les fonctionnalités du framework.

Connecter le dépôt Git

Variables d'environnement

Les variables d'environnement sont configurées dans le tableau de bord Vercel (Settings > Environment Variables). Elles peuvent être définies par environnement : Production, Preview et Development.

# Variables nécessaires pour un frontend headless
WORDPRESS_API_URL=https://admin.votre-site.fr/wp-json
WORDPRESS_AUTH_TOKEN=token_secret_pour_endpoints_protégés
REVALIDATION_SECRET=secret_partagé_pour_webhooks_isr

# Variables optionnelles
NEXT_PUBLIC_SITE_URL=https://www.votre-site.fr
NEXT_PUBLIC_GA_ID=G-XXXXXXXXXX

Paramètres de build

Vercel détecte automatiquement un projet Next.js et applique les paramètres suivants :

| Paramètre | Valeur par défaut | Personnalisation | |---|---|---| | Framework Preset | Next.js | Automatique | | Build Command | next build | Modifiable (npm run build) | | Output Directory | .next | Automatique | | Install Command | npm install | Modifiable (pnpm install, yarn) | | Node.js Version | 18.x | Configurable (18.x, 20.x) |

Preview Deployments

Chaque pull request ou push sur une branche non-production génère automatiquement un "Preview Deployment" avec une URL unique. Cette fonctionnalité permet de vérifier visuellement les modifications avant de les fusionner.

# Exemple d'URL de preview
https://votre-projet-git-branch-name-votre-equipe.vercel.app

Les preview deployments utilisent les variables d'environnement de l'environnement "Preview", ce qui permet de pointer vers un serveur WordPress de staging si nécessaire.

Domaine personnalisé

La configuration du domaine personnalisé s'effectue dans Settings > Domains :

1. Ajoutez votre domaine (par exemple www.votre-site.fr)
2. Configurez les enregistrements DNS chez votre registrar :
   • CNAME : www vers cname.vercel-dns.com
   • A : @ vers 76.76.21.21 (pour le domaine apex sans www)
3. Vercel génère et renouvelle automatiquement le certificat SSL

Hébergement WordPress : les options

Le backend WordPress nécessite un hébergement PHP avec MySQL. Plusieurs options existent selon les besoins de performance et de budget.

En mode headless, les performances du serveur WordPress ont moins d'impact sur l'expérience utilisateur car les pages sont pré-générées (SSG) ou mises en cache (ISR). Le serveur WordPress est sollicité principalement au moment du build et lors des revalidations.

Pipeline CI/CD : déploiement automatique

Le pipeline CI/CD avec Vercel fonctionne automatiquement :

1. Push sur main : déclenche un déploiement en production
2. Push sur une branche : déclenche un preview deployment
3. Pull request : crée un preview deployment et ajoute un commentaire avec l'URL

Aucune configuration CI/CD supplémentaire n'est nécessaire. Pour des besoins avancés (tests avant déploiement, linting), ajoutez des GitHub Actions en complément.

# .github/workflows/ci.yml — tests avant déploiement
name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm run lint
      - run: npm run test

Revalidation à la demande (On-Demand ISR)

L'ISR (Incremental Static Regeneration) permet de mettre à jour les pages statiques sans redéployer l'ensemble du site. Un webhook WordPress déclenche la revalidation lorsqu'un contenu est modifié.

// app/api/revalidate/route.ts
import { revalidatePath } from 'next/cache';
import { NextRequest, NextResponse } from 'next/server';

export async function POST(request: NextRequest) {
  const body = await request.json();
  const secret = request.headers.get('x-revalidation-secret');

  if (secret !== process.env.REVALIDATION_SECRET) {
    return NextResponse.json({ message: 'Invalid secret' }, { status: 401 });
  }

  const { post_type, slug } = body;

  if (post_type === 'post') {
    revalidatePath(`/articles/${slug}`);
    revalidatePath('/articles');
  } else if (post_type === 'page') {
    revalidatePath(`/${slug}`);
  }

  revalidatePath('/'); // Revalider la page d'accueil

  return NextResponse.json({ revalidated: true });
}

Côté WordPress, un hook envoie la requête de revalidation lors de la publication ou de la mise à jour d'un contenu :

// functions.php — webhook de revalidation ISR
add_action('save_post', function ($post_id) {
  if (wp_is_post_revision($post_id) || wp_is_post_autosave($post_id)) return;

  $post = get_post($post_id);
  if ($post->post_status !== 'publish') return;

  wp_remote_post('https://www.votre-site.fr/api/revalidate', [
    'headers' => [
      'Content-Type' => 'application/json',
      'x-revalidation-secret' => REVALIDATION_SECRET,
    ],
    'body' => json_encode([
      'post_type' => $post->post_type,
      'slug' => $post->post_name,
    ]),
  ]);
}, 10, 1);

Monitoring et analytics

Vercel fournit des outils de suivi intégrés :

• Analytics : trafic, pages vues, visiteurs uniques
• Speed Insights : Core Web Vitals mesurés sur les données terrain (LCP, CLS, FID)
• Logs : logs des fonctions serverless et des erreurs de build
• Usage : consommation de bande passante, invocations serverless, temps d'exécution

Plateformes alternatives