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 modifica quel modello di contenuto, ma una nuova versione di EmDash può migrare le tabelle di database gestite da EmDash alla prima richiesta. 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 cambia cosa

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

Workflow	Cosa cambia	Come
Editing dei contenuti	Voci, media, impostazioni	Pannello admin o API dei contenuti
Deploy del codice	Template, config, versione EmDash	`wrangler deploy` — può migrare tabelle gestite da EmDash
Bootstrap iniziale	Tutto, da vuoto	Migrazioni + file seed + wizard di setup, automatico al primo avvio
Evoluzione dello schema	Collezioni, campi, tassonomie	Pannello admin o `emdash schema` contro il sito in produzione (questa pagina)

Il file seed partecipa solo alla terza riga. Viene applicato una volta, quando il database è vuoto e il wizard di setup non è stato completato. Il deploy di un file seed modificato contro un database esistente non fa nulla — l’evoluzione dello schema di un sito in produzione avviene sempre tramite il pannello admin o l’API.

Modificare lo schema nel pannello admin

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

Vedi Collezioni e campi per i tipi di campo disponibili, le regole di validazione e le opzioni dei 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 nello stesso modo in cui funzionano contro il dev locale. Autenticati una volta con il flusso dispositivo:

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

In alternativa, crea un token API nell’admin sotto Impostazioni → Token API e passalo con --token o la variabile d’ambiente EMDASH_TOKEN — utile per 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, committato nel tuo repository ed eseguito contro ogni ambiente a turno.

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 fresco: un nuovo ambiente di preview, una ricostruzione per disaster recovery o un secondo deployment dello stesso sito. Se il seed descrive ancora il blog di partenza mentre la produzione si è evoluta in qualcos’altro, ogni ambiente fresco si bootstrap 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 integrato (il modello del blog di partenza) e astro dev registra un avvertimento.

Dopo aver evoluto lo schema di un sito distribuito, esporta il modello in produzione 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 in produzione. Aggiungi --with-content per includere le voci. Committa il .emdash/seed.json aggiornato insieme al codice che dipende dal nuovo schema, così un ambiente fresco si bootstrap sempre con un modello che il codice comprende.

Provare le modifiche su un ambiente di preview

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

Aggiungi un ambiente di preview con il proprio 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 ed esegui la modifica dello schema contro l’URL di preview:

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 che l’admin si comporti come previsto, poi esegui gli stessi comandi contro la produzione.

Recupero da un errore

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