Se ti occupi di sviluppo frontend, prima o poi ti sei imbattuto nel classico dilemma: "Come gestiamo i contenuti?".
Puoi scrivere tutto hardcoded nel codice (funziona, finché il progetto è tuo e tuo soltanto), oppure affidarti a CMS tradizionali come WordPress. In alternativa, ci sono soluzioni più moderne, tipo Contentful, Strapi, Prismic e compagnia. Ma se ti interessa avere il massimo controllo, senza perdere in flessibilità, Sanity è una delle opzioni più solide e complete in circolazione.
Negli ultimi anni ha conquistato una fetta importante del mercato headless, e non solo perché è veloce e ben documentato. Sanity ha qualcosa in più: ti permette di modellare i contenuti come se stessi scrivendo componenti frontend. Se vieni dal mondo JavaScript o React, l'approccio ti sarà immediatamente familiare.
Un altro punto a favore: lo Studio, cioè l'interfaccia admin per gestire i contenuti, non è un pannello preconfezionato. È un'app React. Letteralmente. Puoi customizzarla, estenderla, modificarla e persino riscriverne i componenti. Questo significa che l’esperienza del content editor può essere perfettamente allineata alle esigenze del tuo progetto, senza compromessi.
In questa guida ci concentriamo su un problema specifico ma comune: come separare ambiente di sviluppo e ambiente di produzione, in modo da avere due versioni indipendenti del progetto – una per testare e fare modifiche, l’altra per servire contenuti pubblici.
Ma prima, chiariamo bene cosa offre Sanity e perché è diverso da altri CMS.
Sanity è un Headless CMS, il che significa che non genera HTML o pagine web direttamente: fornisce contenuti tramite API, e sei tu a decidere come e dove mostrarli, nel frontend che preferisci (Next.js, Astro, Angular, React Native, ecc.).
A differenza di molti altri CMS headless, però, Sanity mette a disposizione anche uno strumento potente lato sviluppo: Sanity Studio.
Vediamolo meglio, partendo dai tre blocchi fondamentali del sistema:
Con Sanity non definisci i tuoi content type cliccando su un'interfaccia visuale: li scrivi in JavaScript o TypeScript (possibilmente usa TS!). E questo è un vantaggio enorme se sei uno sviluppatore:
Un file di schema definisce esattamente cosa sono i tuoi documenti (es. Article, Product, Page) e quali campi hanno, come relazionarsi tra loro, se devono essere unici, opzionali, ordinabili, validati, ecc.
Lo Studio è un’interfaccia admin basata su React. È configurabile, estendibile e completamente personalizzabile. Vuoi un nuovo input per una gallery drag & drop? Puoi scriverlo come componente React. Vuoi cambiare il layout o i tab di editing? Si può fare.
E soprattutto: lo Studio fa parte del progetto. Lo puoi hostare tu, versionare, distribuire su ambienti diversi. Non sei vincolato a una UI centralizzata in cloud.
Sanity supporta editing in tempo reale, versioning dei documenti, permessi granulari, cronologia delle modifiche e preview in live mode. Il sistema è pensato non solo per il singolo sviluppatore, ma anche per team misti (dev + editori), con la possibilità di lavorare contemporaneamente senza conflitti.
L’obiettivo è semplice: configurare due ambienti distinti in un progetto Sanity – uno per lo sviluppo (development), l’altro per la produzione (production).
Perché? Perché prima o poi vorrai testare uno schema nuovo, mostrare una bozza a un cliente o fare debug su contenuti reali senza rischiare di far crollare la home del sito in diretta.
Ti guiderò passo dopo passo, ma senza perdere tempo su concetti troppo basilari: ci rivolgiamo a chi già sviluppa con strumenti moderni e ha familiarità con ambienti, variabili, deploy e frontend modulare.
Pronti? Iniziamo.
Per iniziare, creiamo il nostro progetto Sanity:
npm create sanity@latest
# oppure
yarn create sanity
Ti verrà chiesto di:
Il risultato sarà una cartella con lo Studio (l’interfaccia admin) e tutto il necessario per iniziare.
Lancia il progetto:
npm run dev
L’interfaccia sarà disponibile su http://localhost:3333.
Abbiamo ora creato il nostro progetto con Sanity, e come puoi facilmente notare è un’app React personalizzabile in tutto e per tutto.
Ed eccoci al cuore della nostra guida,se hai iniziato a usare Sanity per un progetto serio (e se sei arrivato fin qui, lo è), probabilmente ti stai chiedendo:
“Ma come separo il contenuto reale da quello che sto sperimentando in locale?”
Spoiler: usare un solo ambiente (production) per tutto non è sostenibile. Né per chi sviluppa, né per chi scrive contenuti. Prima o poi qualcuno pubblicherà un titolo tipo “TEST LOREM XYZ” sulla home del sito. Meglio pensarci prima.
Il modo più semplice (e ufficiale) per gestire ambienti separati su Sanity è creare due dataset distinti:
Se conosci già un minimo di Sanity, sai che un dataset è un contenitore isolato di contenuti. Ne puoi creare quanti vuoi (finché stai nel piano), e ogni dataset può avere anche permessi e token separati.
Apri il terminale nella root del progetto e digita:
sanity dataset create development
Ti verrà chiesto se vuoi copiare i dati da un altro dataset (scegli production se vuoi clonare la struttura e iniziare con una base reale). In pochi secondi hai due ambienti separati.
Invece di toccare a mano il nome del dataset nel file di configurazione ogni volta, conviene usare due file .env diversi:
.env.development:
SANITY_STUDIO_API_DATASET=development
.env.production:
SANITY_STUDIO_API_DATASET=production
Nel file sanity.config.ts:
dataset: process.env.SANITY_STUDIO_API_DATASET || 'production',
Così, quando lanci npm run dev, lavori sul dataset development. Quando deployi, puoi decidere su quale ambiente farlo, senza confusione o rischi.
Se vuoi tenere tutto ancora più ordinato, puoi deployare due versioni del tuo Sanity Studio:
Ecco come:
# Deploy dell’ambiente di produzione
SANITY_STUDIO_API_DATASET=production sanity deploy
# Deploy dell’ambiente di sviluppo
SANITY_STUDIO_API_DATASET=development sanity deploy
Non è obbligatorio, ma rende la vita più semplice se lavorano più persone sul progetto (developer e content editor inclusi).
Dal pannello Sanity Manage, puoi creare due token API con permessi mirati:
Questo approccio è utile anche in CI/CD, per evitare che uno script di deploy modifichi dati in produzione per errore.
Nel frontend, puoi decidere quale dataset usare in base all’ambiente. Ecco un esempio semplice semplice con Next.js:
const dataset = process.env.NODE_ENV === 'production' ? 'production' : 'development';
const client = createClient({
projectId: process.env.SANITY_PROJECT_ID,
dataset,
apiVersion: '2023-01-01',
useCdn: true,
});
Questo ti permette di fare tutto quello che serve:
Capita spesso: vuoi partire da un clone dei dati di produzione per testare qualcosa in sviluppo. Lo puoi fare in due righe con la CLI:
# Esporta i dati da production
sanity dataset export production backup.tar.gz
# Importali in development
sanity dataset import backup.tar.gz development
Questo è anche un buon sistema di “backup manuale” prima di cambiare qualcosa di grosso nello schema.
Qualche scenario concreto:
Sanity ti permette di lavorare come in un progetto software vero e proprio: ambienti separati, deploy controllati, contenuti isolati. È una struttura che rispecchia il modo moderno (e sano) di sviluppare e gestire contenuti: quello dove il codice, i dati e i ruoli delle persone sono tenuti separati, ma comunicano bene tra loro.
Configurare due ambienti distinti con dataset diversi richiede pochissimo: in meno di 10 minuti hai una base solida per gestire sviluppo e produzione in modo indipendente, e già questo ti salva da tutta una serie di problemi tipici dei CMS “monolitici”.
Ma il vero valore arriva nel tempo. Separare development da production significa:
In pratica, si lavora meglio. Con più ordine, più controllo e meno rischi.
E questo vale sia se stai sviluppando un blog statico da solo, sia se stai lavorando su un portale multi-lingua con team distribuiti.
Inoltre, il sistema è flessibile: puoi partire con due ambienti, ma scalarlo facilmente se serve. Aggiungere un dataset per il QA? Fattibile. Creare un ambiente staging con contenuti e schema separati? Anche. Automatizzare tutto da CI? Idem.
Insomma: Sanity ti dà gli strumenti per lavorare come un team moderno, anche quando il team è una sola persona. Conviene approfittarne fin da subito!
