Evolvere un sito distribuito | EmDash CMS Everything

EmDash memorizza collezioni, campi e tassonomie nel database, accanto al contenuto stesso. Il deploy di nuovo codice non li modifica: un deploy sostituisce il codice del Worker (o server), mentre lo schema e il contenuto nel database rimangono invariati. Questa pagina spiega come modificare il modello di contenuto di un sito già distribuito, usando Cloudflare D1 come esempio. Gli stessi workflow si applicano alle altre opzioni di database.

Cosa modifica cosa

Un sito attraversa quattro workflow distinti. Ciascuno tocca un livello diverso:

Workflow	Cosa cambia	Come
Modifica contenuto	Voci, media, impostazioni	Pannello di amministrazione o API contenuto
Deploy del codice	Template, config, versione EmDash	`wrangler deploy` — lascia schema e contenuto inalterati
Bootstrap iniziale	Tutto, da vuoto	Migrazioni + file seed + assistente di configurazione, automatico al primo avvio
Evoluzione dello schema	Collezioni, campi, tassonomie	Pannello di amministrazione o `emdash schema` contro il sito live (questa pagina)

Il file seed partecipa solo alla terza riga. Viene applicato una sola volta, quando il database è vuoto e l’assistente di configurazione non è stato completato. Distribuire un file seed modificato contro un database esistente non fa nulla — l’evoluzione dello schema di un sito live avviene sempre tramite il pannello di amministrazione o l’API.

Modificare lo schema nel pannello di amministrazione

Il pannello di amministrazione è il modo principale per far evolvere un sito distribuito. Apri Content Types nell’admin e aggiungi, modifica o rimuovi collezioni e campi. Le modifiche hanno effetto immediato — l’API contenuto, il loader e l’interfaccia di modifica leggono tutti lo schema dal database a runtime.

Vedi Collezioni & Campi per i tipi di campo disponibili, le regole di validazione e le opzioni widget.

Dopo aver modificato lo schema, rigenera i tipi TypeScript usati dai tuoi template. Il comando emdash types legge lo schema da un’istanza in esecuzione, quindi può puntare direttamente al sito distribuito:

npx emdash types --url https://example.com

Modificare lo schema dalla CLI

I comandi emdash schema comunicano con un’istanza in esecuzione tramite la sua API REST, quindi funzionano contro un sito distribuito allo stesso modo del dev locale. Autenticati una volta con il flusso del dispositivo:

npx emdash login --url https://example.com

In alternativa, crea un token API nell’admin sotto Settings → API Tokens e passalo con --token o la variabile d’ambiente EMDASH_TOKEN — utile per la CI.

Poi evolvi lo schema con gli stessi comandi che useresti localmente:

npx emdash schema add-field posts subtitle --type string --label "Subtitle" --url https://example.com
npx emdash schema remove-field posts legacy_field --url https://example.com
npx emdash schema create projects --label Projects --url https://example.com

Poiché questi comandi sono semplici chiamate CLI, possono essere scriptati: una “migrazione” ripetibile per il tuo modello di contenuto è uno script shell di chiamate emdash schema, registrato nel tuo repository e eseguito contro ogni ambiente in successione.

Vedi il riferimento CLI per la lista completa dei comandi.

Mantenere il file seed sincronizzato

Il file seed incorporato nel tuo build determina con cosa si inizializza un database nuovo: un nuovo ambiente di anteprima, una ricostruzione di disaster recovery, o un secondo deployment dello stesso sito. Se il seed descrive ancora il blog iniziale mentre la produzione si è evoluta in qualcos’altro, ogni ambiente nuovo parte con il modello sbagliato.

Il build incorpora il primo file seed trovato in .emdash/seed.json, il percorso in package.json#emdash.seed, o seed/seed.json. Se nessuno è presente, viene incorporato un seed predefinito (il modello del blog iniziale), e astro dev registra un avviso.

Dopo aver fatto evolvere lo schema di un sito distribuito, esporta il modello live nel tuo repository. emdash export-seed legge un file SQLite locale, e wrangler d1 export ne produce uno dal database D1 distribuito:

npx wrangler d1 export emdash-db --remote --output=./prod.sql
sqlite3 prod.db < prod.sql
npx emdash export-seed --database prod.db > .emdash/seed.json

Il seed esportato contiene le impostazioni, collezioni, tassonomie, menu e aree widget del sito live. Aggiungi --with-content per includere le voci. Fai commit del .emdash/seed.json aggiornato insieme al codice che dipende dal nuovo schema, così un ambiente nuovo parte sempre con un modello che il codice comprende.

Provare le modifiche su un ambiente di anteprima

Una modifica allo schema distruttiva (rimuovere un campo, ristrutturare una collezione) è più sicura se provata contro una copia usa e getta della produzione.

Aggiungi un ambiente di anteprima con il suo database D1 a wrangler.jsonc:

{
  "env": {
    "preview": {
      "d1_databases": [{ "binding": "DB", "database_name": "emdash-db-preview" }],
    },
  },
}

Copia la produzione al suo interno:

npx wrangler d1 export emdash-db --remote --output=./prod.sql
npx wrangler d1 execute emdash-db-preview --remote --file=./prod.sql

Distribuisci e esegui la modifica allo schema contro l’URL di anteprima:

npx wrangler deploy --env preview
npx emdash schema remove-field posts legacy_field --url https://preview.example.com

Verifica che il sito si renderizzi e l’admin si comporti come previsto, poi esegui gli stessi comandi contro la produzione.

Recuperare da un errore

Un campo è stato rimosso per errore. La colonna e i suoi dati sono scomparsi dal database live. Ripristina da un backup point-in-time Time Travel di D1, o riaggiungi il campo e ripristina i suoi valori da un precedente wrangler d1 export.
Un ambiente nuovo è partito con il modello sbagliato. Il seed incorporato era obsoleto o mancante. Aggiorna .emdash/seed.json (vedi Mantenere il file seed sincronizzato), ricompila e punta il deploy a un database vuoto per ripartire.
Lo schema e i template non concordano. I deploy e le modifiche allo schema sono indipendenti, quindi ordinali deliberatamente: le modifiche allo schema additive (nuova collezione, nuovo campo opzionale) vanno prima, poi il codice che le usa. Per le rimozioni, distribuisci prima il codice che smette di usare il campo, poi rimuovi il campo.