WordPress Headless con Next.js 15: Architettura Completa per Agenzie

WordPress Headless con Next.js 15: L’Architettura che Usiamo in Produzione

WordPress come backend CMS. Next.js 15 come frontend. Il meglio di due mondi: l’editor e l’ecosistema plugin di WordPress, le performance e la DX di React/Next.js.

Questo non è un tutorial “Hello World”. È l’architettura che usiamo per AgencyPilot: WordPress come content API, Next.js per il rendering, deploy su Vercel.

L’Architettura

WordPress (CMS) ──REST API──> Next.js 15 (Frontend) ──> Utente
     │                              │
  wp-admin                     App Router
  Plugin                       Server Components
  Media Library                ISR/SSG
  Custom Post Types            Edge Runtime

Perché Headless

Setup Base

# Crea il progetto Next.js 15
npx create-next-app@latest my-wp-frontend --typescript --app --tailwind

# Installa il client WordPress
npm install @wordpress/api-fetch

Fetch dei post da WordPress

// app/blog/page.tsx
async function getPosts() {
  const res = await fetch('https://tuosito.com/wp-json/wp/v2/posts?per_page=10', {
    next: { revalidate: 3600 } // ISR: rigenera ogni ora
  });
  return res.json();
}

export default async function BlogPage() {
  const posts = await getPosts();
  return (
    <main>
      <h1>Blog</h1>
      {posts.map((post: any) => (
        <article key={post.id}>
          <h2><a href={`/blog/${post.slug}`}>{post.title.rendered}</a></h2>
          <div dangerouslySetInnerHTML={{ __html: post.excerpt.rendered }} />
        </article>
      ))}
    </main>
  );
}

ISR: Il Meglio di SSG e SSR

Incremental Static Regeneration è la killer feature per WordPress headless. Le pagine sono pre-generate (veloci come SSG) ma si aggiornano automaticamente quando il contenuto cambia (flessibili come SSR).

// revalidate: 3600 → la pagina si rigenera al massimo ogni ora
// revalidate: 0 → SSR (ogni richiesta)
// No revalidate → SSG puro (build time only)

Webhook per Revalidation On-Demand

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

export async function POST(request: NextRequest) {
  const secret = request.headers.get('x-revalidation-secret');
  if (secret !== process.env.REVALIDATION_SECRET) {
    return Response.json({ error: 'Invalid secret' }, { status: 401 });
  }
  
  const { slug } = await request.json();
  revalidatePath(`/blog/${slug}`);
  return Response.json({ revalidated: true });
}

Poi su WordPress, un webhook su publish_post che chiama questo endpoint. Risultato: pubblichi su WordPress, il frontend si aggiorna in secondi.

FAQ

Perdo i plugin SEO (Yoast/Rank Math)?

Parzialmente. Yoast e Rank Math espongono i meta via REST API. Puoi leggere title, description, OG tags dall’API e renderizzarli in Next.js con next/head. Le funzionalità avanzate (sitemap, schema) le ricostruisci lato Next.js.

WordPress headless è più veloce?

Il frontend sì (React + edge rendering). Ma il backend WordPress è lo stesso (PHP, MySQL). Il guadagno è nel rendering: il frontend Next.js servito da Vercel/Cloudflare è più veloce di PHP che renderizza HTML su ogni richiesta.