# Headless Starter Kit — Guida completa

> Guida completa di installazione, configurazione e distribuzione di Headless Starter Kit: il plugin WordPress che trasforma il tuo negozio WooCommerce in commercio headless, con starter Next.js 15 chiavi in mano preconfigurato.

- Pagina: <https://www.datafirefly.com/it/documentation/headless-starter-kit/>
- Lingua: it
- Aggiornato il: 2026-07-01
- Altre lingue: [fr](https://www.datafirefly.com/documentation/headless-starter-kit/index.md), [en](https://www.datafirefly.com/en/documentation/headless-starter-kit/index.md), [es](https://www.datafirefly.com/es/documentation/headless-starter-kit/index.md), [de](https://www.datafirefly.com/de/documentation/headless-starter-kit/index.md), [pl](https://www.datafirefly.com/pl/documentation/headless-starter-kit/index.md), [nl](https://www.datafirefly.com/nl/documentation/headless-starter-kit/index.md), [pt](https://www.datafirefly.com/pt/documentation/headless-starter-kit/index.md)
- Indice: <https://www.datafirefly.com/it/documentation/llms.txt>

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.

**A chi è rivolta questa guida.** Sviluppatori, agenzie o commercianti tecnici che vogliono passare un WooCommerce esistente a headless senza reinventare autenticazione, carrello e checkout. Devi essere a tuo agio con la riga di comando, Node.js e un po' di configurazione server se scegli Hetzner.

## 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+

**L'hosting condiviso classico (o2switch, OVH condiviso, ecc.) non è adatto** per ospitare il frontend Next.js, che richiede un runtime Node persistente. Il plugin WordPress, invece, funziona su qualsiasi hosting compatibile con WP.

## 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`.

**Dopo la rigenerazione del segreto JWT, tutti i token di accesso e refresh esistenti diventano invalidi.** Gli utenti dovranno riconnettersi. Avvisali o fallo fuori dagli orari di punta.

### 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
```

Aggiungi `http://localhost:3000` durante lo sviluppo, poi rimuovilo in produzione.

### 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`)

Per aggiungere una nuova pagina che elenchi ad esempio i prodotti di un brand, duplica `src/app/(shop)/products/page.tsx` e adatta la query WooCommerce REST. La funzione `wooRest()` gestisce l'autenticazione Basic automaticamente.

## 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.