Headless Starter Kit — Guida completa

Questa guida copre l’installazione, la configurazione e l’utilizzo completo di Headless Starter Kit — il plugin WordPress che trasforma il tuo negozio WooCommerce in un commercio headless, accompagnato da uno starter Next.js 15 chiavi in mano.

Panoramica

Headless Starter Kit si presenta come due consegne in un unico acquisto:

1. Il plugin WordPress (ZIP caricato via /wp-admin/plugins.php) che espone sul backend: autenticazione JWT, API carrello, ponte di checkout, endpoint di configurazione pubblico, webhook ISR e CORS rigoroso.
2. Lo starter Next.js 15 (ZIP scaricabile dall’admin WordPress una volta attivato e configurato il plugin) che contiene un progetto Next.js completo con pagine home, listing, scheda prodotto ISR, carrello, checkout, login, registrazione e area cliente — variabili d’ambiente già precompilate con i tuoi URL e segreti.

L’architettura è volutamente semplice: il tuo WooCommerce resta la fonte di verità (prodotti, ordini, magazzino, pagamenti), e Next.js consuma l’API REST tramite route proxy sicure. Nessuna duplicazione di database, nessuna replica da gestire.

Requisiti

Lato WordPress

• WordPress 6.4 o superiore
• WooCommerce 8.0 o superiore (testato fino a 9.5)
• PHP 8.1 o superiore
• Permalink impostati su Nome articolo (non su Semplice)
• HTTPS attivo (indispensabile per i cookie httpOnly e l’autenticazione in produzione)
• Una coppia di chiavi WooCommerce REST in lettura-scrittura (generate in WooCommerce → Impostazioni → Avanzate → API REST)

Lato frontend Next.js

• Node.js 20 o superiore (consigliato: gestire le versioni con nvm)
• Hosting compatibile con Node: Vercel, Hetzner VPS, Netlify, Railway o qualsiasi server in grado di eseguire Node 20+

Installazione del plugin WordPress

1. Dal back-office WordPress, vai in Plugin → Aggiungi nuovo → Carica plugin.
2. Seleziona il file dfheadlessstarterkit.zip, poi clicca su Installa ora.
3. Clicca su Attiva plugin.
4. Appare un nuovo menu Headless Kit nella barra laterale sinistra, con tre schede: Impostazioni, Diagnostica, Scarica starter.

All’attivazione, il plugin genera automaticamente un segreto JWT e un token di rivalidazione casuali. Puoi rigenerarli in qualsiasi momento dalle impostazioni.

Configurazione

Apri Headless Kit → Impostazioni. Ogni sezione è indipendente e può essere modificata senza riavviare nulla.

URL del frontend

Inserisci l’URL pubblico completo della tua applicazione Next.js, senza slash finale. Esempio:

https://shop.esempio.it

Questo URL serve a tre cose: costruire i webhook ISR, alimentare la variabile NEXT_PUBLIC_SITE_URL dello starter consegnato e validare l’origine CORS predefinita.

Segreto JWT e token di rivalidazione

Vengono utilizzati due segreti:

• Segreto JWT — firma i token di accesso e refresh. Almeno 32 caratteri. Non condividerlo mai.
• Token di rivalidazione — inviato nell’header Authorization: Bearer … dei webhook ISR. Deve essere identico alla variabile REVALIDATE_TOKEN lato Next.js.

Un pulsante Rigenera accanto a ogni campo produce un segreto casuale crittograficamente robusto tramite crypto.getRandomValues.

Modalità carrello: JWT o server?

La scelta si fa tramite un pulsante radio nelle impostazioni.

Modalità JWT (predefinita, consigliata)

Il carrello completo viene serializzato in un token firmato HS256 e restituito tramite l’header X-DFHSK-Cart. Nessun dato viene memorizzato lato WordPress. Ideale per:

• Distribuzioni su Vercel edge, Cloudflare o multi-istanza
• Negozi con molto traffico dove evitare il database a ogni chiamata è un guadagno netto
• Setup dove WordPress è puramente API e non ha bisogno di sessioni

Modalità server (WC_Session)

Il carrello vive nella tabella WC_Session nativa di WooCommerce. Da preferire se:

• Usi estensioni WooCommerce che si agganciano al carrello (WooCommerce Subscriptions, Dynamic Pricing, plugin YITH, ecc.)
• Vuoi conservare la logica di sessione nativa di WooCommerce (recuperi nativi di carrelli abbandonati, cross-sell lato server, ecc.)

Origini CORS

Una lista bianca rigorosa di origini autorizzate a chiamare l’API. Un’origine per riga, formato completo https://…. I caratteri jolly di sottodominio sono supportati:

https://shop.esempio.it
https://preview.esempio.it
https://*.previews.esempio.it
http://localhost:3000

Eventi ISR

Cinque caselle indicano quali eventi WordPress attivano un webhook ISR verso Next.js:

• Prodotti — save_post_product, woocommerce_update_product
• Categorie — creazione, aggiornamento, eliminazione di termini della tassonomia product_cat
• Ordini — cambiamenti di stato (utile per aggiornare la pagina account)
• Pagine — save_post_page
• Coupon — creazione e aggiornamento di codici promozionali

Un textarea Percorsi da rivalidare ti permette di definire con precisione quali percorsi Next.js sono rivalidati per ogni evento (per impostazione predefinita, il plugin deduce intelligentemente i percorsi interessati).

Diagnostica

Headless Kit → Diagnostica. Undici controlli automatici vengono eseguiti a ogni visualizzazione della pagina:

1. WooCommerce attivo — la classe WooCommerce è disponibile
2. Permalink corretti — la struttura non è Semplice
3. REST API raggiungibile — /wp-json/ risponde 200
4. HTTPS attivo — is_ssl() restituisce true
5. WPGraphQL rilevato — solo informativo, non bloccante
6. Segreto JWT definito — almeno 32 caratteri
7. URL del frontend configurato — non vuoto e formato URL valido
8. Origini CORS impostate — almeno un’origine
9. Token di rivalidazione definito — almeno 24 caratteri
10. Chiavi WooCommerce REST — il plugin rileva una coppia consumer_key/consumer_secret attiva
11. Modalità carrello leggibile — l’archiviazione scelta funziona

Ogni controllo mostra verde (OK), arancione (avvertimento, non bloccante) o rosso (bloccante). Risolvi tutto ciò che è rosso prima di andare in produzione.

Scaricare e avviare lo starter Next.js

Una volta compilate le impostazioni e la diagnostica al verde, apri Headless Kit → Scarica starter. Clicca sul grande pulsante Scarica starter Next.js.

Lo ZIP consegnato è un progetto Next.js 15 completo, generato al volo con i tuoi URL e segreti già iniettati. Placeholder sostituiti alla generazione:

• {{SITE_URL}} → URL del tuo WordPress
• {{FRONTEND_URL}} → URL del front configurato
• {{REVALIDATE_TOKEN}} → il tuo token di rivalidazione
• {{CURRENCY}} → valuta WooCommerce
• {{SITE_NAME}} → titolo del sito
• {{LOCALE}} → locale WordPress (it, en, fr, ecc.)

Il file .envtmpl viene rinominato in .env.example alla generazione.

Variabili d’ambiente da compilare manualmente

Alcuni valori non possono essere recuperati automaticamente — devi aggiungerli al file .env (creato da .env.example):

WOO_REST_CONSUMER_KEY=ck_xxxxxxxxxxxxxx
WOO_REST_CONSUMER_SECRET=cs_xxxxxxxxxxxxxx
SESSION_PASSWORD=tua-password-di-almeno-32-caratteri

Genera una SESSION_PASSWORD solida:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Sviluppo locale

npm install
cp .env.example .env
# Modifica .env con i tuoi segreti mancanti
npm run dev

Il front è disponibile su http://localhost:3000. Aggiungi questo URL alle origini CORS lato WordPress durante lo sviluppo.

Distribuzione su Vercel

npx vercel link
npx vercel env pull .env.production
npx vercel deploy --prod

Poi configura tutte le variabili d’ambiente nella dashboard Vercel (Project → Settings → Environment Variables). Il file vercel.json consegnato fissa la regione su cdg1 (Parigi) e disabilita la cache sulle route /api/*.

Distribuzione su Hetzner (o qualsiasi VPS Ubuntu/Debian)

# Sul server, come root o con sudo
git clone tuo-repo.git storefront && cd storefront
cp .env.example .env
nano .env                       # Compila tutte le variabili
bash deploy/hetzner.sh

Lo script installa Docker se necessario, costruisce l’immagine, avvia il container ed espone il servizio su 127.0.0.1:3000. Aggiungi Caddy o nginx come reverse-proxy per il TLS. Esempio di Caddyfile minimo:

shop.esempio.it {
  encode zstd gzip
  reverse_proxy 127.0.0.1:3000
}

Endpoint REST esposti

Tutti gli endpoint del plugin vivono sotto il namespace dfhsk/v1. URL completo: https://esempio.it/wp-json/dfhsk/v1/…

Autenticazione

• POST /auth/login — body: { username, password } → restituisce { token, refresh_token, user }
• POST /auth/refresh — body: { refresh_token } → restituisce un nuovo token
• GET /auth/me — header: Authorization: Bearer … → restituisce l’utente corrente
• POST /auth/register — body: { email, password, first_name, last_name }
• POST /auth/logout — invalida il refresh token

Carrello

Ogni chiamata trasmette il token di carrello tramite l’header X-DFHSK-Cart. Il server restituisce un nuovo token nello stesso header a ogni risposta.

• GET /cart — snapshot completo (articoli, totali, tasse, spedizione)
• POST /cart/add — body: { product_id, quantity, variation? }
• POST /cart/update — body: { key, quantity }
• POST /cart/remove — body: { key }
• POST /cart/coupon — body: { code }
• DELETE /cart/coupon/{code}
• POST /cart/shipping — body: { country, postcode } → restituisce le tariffe applicabili
• POST /cart/clear

Checkout

• POST /checkout/create-order — body: { payment_method, billing, shipping? } → restituisce { order_id, order_key, redirect }. Il redirect è l’URL verso il gateway di pagamento (Stripe, PayPal, ecc.).
• GET /checkout/order/{id} — header Authorization: Bearer … richiesto

Configurazione pubblica

• GET /config — accessibile senza autenticazione. Restituisce { currency, base_country, countries, payment_methods, tax_settings }. Lo starter Next.js usa questo endpoint per idratare i moduli di checkout.

Webhook ISR (lato Next.js)

Il plugin invia richieste POST a {FRONTEND_URL}/api/revalidate con l’header Authorization: Bearer {REVALIDATE_TOKEN}. Il corpo è JSON:

{
  "paths": ["/products/giacca-lino", "/products"],
  "tags": ["product:giacca-lino"],
  "reason": "wc_update_product"
}

La route /api/revalidate consegnata nello starter valida il token e poi chiama revalidatePath e revalidateTag per ogni voce.

Personalizzare lo starter

Il codice consegnato è sotto licenza GPL v2 — puoi modificare, estendere, ridistribuire senza restrizioni. Punti di ingresso comuni:

• Palette di colori: tailwind.config.ts, palette brand (arancione per impostazione predefinita)
• Componenti negozio: src/components/shop/ (Header, Footer, ProductCard, CartProvider)
• Pagine pubbliche: src/app/(shop)/
• Pagine account cliente: src/app/(auth)/
• Formato prezzi e date: src/lib/format.ts
• Tipi TypeScript: src/types/woo.ts
• Helper chiamata API: src/lib/woo-rest.ts (funzioni wooRest e dfhskFetch)

Risoluzione dei problemi

Errore CORS nella console del browser

L’origine del front non è nella lista bianca. Aggiungila in Impostazioni → Origini CORS, una per riga, senza slash finale.

I webhook ISR rispondono 401

Il REVALIDATE_TOKEN lato Next.js non corrisponde al token configurato lato WordPress. Copia il valore esatto dalle impostazioni WP nel .env Next.js, poi ridistribuisci.

Login restituisce 403 nonostante credenziali corrette

Verifica che l’account utente abbia una password impostata (non solo login social), che HTTPS sia attivo in produzione e che il segreto JWT sia di almeno 32 caratteri. Consulta la scheda Diagnostica.

Il carrello si svuota tra due pagine

In modalità JWT, verifica che lo starter legga e scriva correttamente il token in localStorage (chiave dfhsk_cart_token). Apri l’ispettore del browser → scheda Application → Local Storage.

Un ordine creato in WooCommerce non appare in Next.js

Verifica che l’evento Ordini sia spuntato negli eventi ISR e che il webhook parta senza errore (attiva WP_DEBUG_LOG).

Andare oltre

Lo starter è un punto di partenza, non un prodotto finito. A seconda del tuo progetto, considera di aggiungere:

• Un motore di ricerca istantaneo (Algolia, Meilisearch, Typesense) alimentato dagli stessi webhook ISR
• Un CMS di contenuti editoriali lato WordPress con il plugin ACF o simile, e una pagina Next.js dedicata
• Una PWA con service worker per la modalità offline (vedi anche il nostro modulo dfpwa)
• Personalizzazione IA in tempo reale (vedi dfsmartcontent)

Per qualsiasi domanda tecnica, contatta il supporto DataFirefly con i tuoi log e i risultati della scheda Diagnostica.