Headless CMS: La dura verità che nessuno vi racconta mentre siete sotto deploy

Mettiamoci comodi. Anzi no, perché probabilmente state leggendo questo pezzo alle due di notte, con il cliente che vi alita sul collo e un deploy che sta andando a gambe all'aria. Parliamo di Headless CMS. Non come ne parlano i commerciali in giacca e cravatta, ma come ne parliamo noi, in trincea, tra un caffè e una riga di codice che non funziona.

L'idea di base è quasi poetica: separare la testa (il frontend, quello che vede l'utente) dal corpo (il backend, dove i poveri cristi del marketing buttano dentro i contenuti). In teoria, una meraviglia. Sviluppatori liberi di usare i loro giocattoli preferiti—React, Next.js, quello che vi pare—e content manager che finalmente la smettono di chiederci di "spostare un bottone".

Questo disaccoppiamento, in un mondo perfetto, significa che il marketing può vomitare articoli, landing page e schede prodotto senza che il team di sviluppo debba mettere mano al codice per ogni virgola. Il contenuto viene servito tramite API, e il frontend se lo prende e lo mostra come gli pare.

Sembra la soluzione definitiva, vero? Il marketing è felice, gli sviluppatori sono felici, tutti cantano kumbaya attorno a un falò di JSON. Peccato che la realtà, come al solito, sia una discreta carogna.

Strapi: l'amico che ti pugnala alle spalle con un sorriso

L'altro giorno in agenzia a Rosignano, ci casca un progetto che sembrava un cioccolatino. Un piccolo e-commerce su Jamstack, con Next.js per il frontend e Strapi come headless CMS. Sulla carta, una passeggiata. Strapi è open-source, basato su Node.js, super flessibile, con una dashboard che anche un criceto ammaestrato potrebbe usare. Figata, no?

La prima settimana è tutta rose e fiori. Tiri su i content type in un attimo, definisci le relazioni, e la API REST o GraphQL è praticamente pronta. I nostri ragazzi a Kampala stavano già festeggiando. Poi, iniziano i dolori. Quelli veri.

Il primo pugno nel ventre arriva con le migrazioni. Devi spostare i content type da locale a staging, e poi in produzione. E scopri che non esiste un sistema di migrazione dello schema degno di questo nome. Certo, puoi fare il giro del fumo esportando e importando JSON, ma è un accrocchio fragile che puzza di "speriamo bene" lontano un miglio. Se due persone del team modificano lo schema contemporaneamente, preparati a passare la notte a risolvere conflitti a mano, imprecando in dialetti che non sapevi di conoscere.

Poi c'è la questione delle performance. Strapi, con tanti contenuti e relazioni complesse, inizia a rantolare. Le query diventano lente, la dashboard arranca. E tu sei lì, a spiegare al cliente perché il sito che doveva essere "velocissimo grazie al Jamstack" ci mette dieci secondi a caricare la home page.

E non fatemi iniziare a parlare dei plugin. La community è grande e bella, ma tanti plugin sono aggiornati quando Giove si allinea con Marte. Trovi il plugin perfetto per le tue esigenze, lo installi e scopri che non è compatibile con la tua versione di Strapi. E lì parte la caccia alla versione giusta, alle dipendenze, e finisci per manutenere un pezzo di codice che non hai scritto tu, solo per far funzionare una feature che doveva essere "pronta all'uso".

Onestamente? Strapi è un ottimo strumento per partire veloci, per i progetti piccoli, per le demo da mostrare al cliente. Ma quando il gioco si fa duro e il database si popola, mostra tutti i suoi limiti. È come costruire una casa con fondamenta di cartone: finché c'è il sole va tutto bene, ma alla prima pioggia... si affloscia tutto.

Directus: l'alternativa per masochisti con un database esistente

E allora dici: basta, proviamo altro. E spunta Directus. Si presenta come una "piattaforma dati open source", non solo un CMS. La sua grande promessa è che non gestisce il database, ma ci si appoggia sopra. Hai già un database SQL incasinato da dieci anni di gestionale? Nessun problema, Directus ci si collega e ti tira fuori una dashboard e delle API per gestirlo.

Una manna dal cielo, sulla carta. Immagina di poter dare al reparto commerciale un'interfaccia pulita per modificare i dati di un database che fino a ieri era accessibile solo con query SQL scritte su un tovagliolo. A Rosignano abbiamo visto clienti con le lacrime agli occhi.

Ma anche qui, l'entusiasmo dura poco. L'approccio "database-first" è un'arma a doppio taglio. Se da un lato ti dà una libertà immensa, dall'altro ti lega le mani. Non puoi definire la struttura dati dal codice, come faresti con Strapi. Ogni modifica la devi fare direttamente sul database, e poi sperare che a Directus vada bene. Questo significa che la "source of truth" non è più il tuo codice versionato su Git, ma un database che può essere modificato da chiunque abbia gli accessi. Un incubo per chiunque cerchi di mantenere un minimo di ordine e coerenza tra gli ambienti di sviluppo.

In più, sebbene la gestione dei permessi sia incredibilmente granulare (puoi definire chi può vedere cosa a livello di singola cella), configurarla è un labirinto. Finisci per passare giorni a creare ruoli e permessi, testando ogni singolo caso d'uso, solo per scoprire che l'utente "Marketing Stagista" riesce comunque a cancellare l'intera tabella dei prodotti. E la colpa, ovviamente, è tua.

Directus è potente, non c'è dubbio. Ma è uno strumento per chi ha un problema molto specifico: un database SQL esistente da esporre via API. Provare a usarlo per un progetto nuovo, un "greenfield project", è come usare un lanciafiamme per accendere una sigaretta. Funziona, ma forse è un tantino esagerato e rischi di bruciarti le sopracciglia.

Next.js e il Jamstack: la cura è peggio della malattia?

E poi c'è lui, il frontend. Il motivo per cui ci siamo imbarcati in questa odissea. Next.js, il framework React che promette il meglio dei due mondi: Server-Side Rendering (SSR) e Static Site Generation (SSG). Pagine statiche velocissime, ma con la possibilità di avere parti dinamiche. Il sogno di ogni sviluppatore web.

L'accoppiata Next.js + Headless CMS è il cuore pulsante del Jamstack. L'idea è: al momento della build, Next.js chiama le API del nostro CMS (Strapi, Directus o chi per loro), pre-renderizza tutte le pagine in HTML statico e le sbatte su una CDN. Risultato? Un sito che si carica all'istante, sicuro perché non c'è un server da bucare, e infinitamente scalabile.

Bellissimo. Se non fosse per un piccolo, insignificante dettaglio: la build. Avete mai provato a fare la build di un sito Next.js con diecimila pagine? No? Ve lo racconto io. Dura. Dura tanto. A volte, dura così tanto che nel frattempo il cliente ha già cambiato idea sul colore del footer. E se durante la build una chiamata API fallisce? Tutta la build va a gambe all'aria. E tu sei lì, alle tre di notte, a riavviare una pipeline che ci metterà un'altra ora, sperando che stavolta l'API del CMS non faccia i capricci.

"Ma c'è l'Incremental Static Regeneration (ISR)!" direte voi. Certo. L'ISR permette di rigenerare le pagine in background, senza rifare tutta la build. Un'idea geniale. Peccato che sia complessa da gestire, difficile da debuggare e ti fa consumare tutte le risorse del server di build se non stai attento. È una di quelle feature che sulla documentazione sembra magica, ma sul campo ti fa sudare sette camicie.

Quindi, qual è il punto? Che l'architettura headless non è la pallottola d'argento che vi hanno venduto. È un'architettura complessa, con tanti punti di rottura, che sposta il problema dal monolite a un ecosistema distribuito. E gestire un ecosistema distribuito è, per definizione, più difficile.

Non sto dicendo che sia da buttare. Anzi. Per i nostri progetti a Kampala, dove la connettività è un terno al lotto, avere un sito statico leggerissimo è una manna dal cielo. Per l'e-commerce di Rosignano, dove il catalogo cambia ogni ora, la flessibilità di Next.js è impagabile.

Ma bisogna essere onesti. Bisogna smetterla di parlare di queste tecnologie come se fossero la soluzione a tutti i mali. Richiedono competenza, pianificazione e una buona dose di cinismo. Bisogna scegliere lo strumento giusto per il lavoro giusto, conoscendone i difetti, i costi nascosti e le notti insonni che ti farà passare. Perché alla fine, nessun framework o CMS potrà mai sostituire la cosa più importante: un team di sviluppo che sa dove mettere le mani, che ha già sbattuto la testa su questi problemi e che, nonostante tutto, ha ancora la voglia di tirare su un accrocchio che funzioni. E che, magari, riesca anche a spaccare tutto.