E EmDash CMS Everything Guides, use cases, plugins, templates
Italiano

Passare a EmDash 1.0

In questa pagina

EmDash 1.0 rimuove le API rese obsolete durante la serie 0.x e sposta sotto emdash/internal/ i punti di ingresso che carica solo EmDash stesso. Questa guida elenca ogni modifica incompatibile e che cosa aggiornare nel tuo sito.

Aggiorna le dipendenze

Aggiorna emdash e gli altri pacchetti EmDash usati dal tuo sito alle versioni più recenti, poi ricompila. L’esempio seguente aggiorna un sito Cloudflare:

pnpm up --latest emdash @emdash-cms/cloudflare
pnpm build

Se la tua distribuzione esegue emdash migrate, eseguilo con il file .emdash/migrations.json prodotto da una build effettuata dopo l’aggiornamento. Il comando rifiuta un manifest scritto da una versione precedente di EmDash.

Dopo l’aggiornamento, il tuo sito potrebbe compilare ed essere eseguito senza altre modifiche. Se la build fallisce o EmDash segnala un errore all’avvio, passa in rassegna le modifiche incompatibili qui sotto.

Per l’elenco completo delle modifiche di ciascun pacchetto, consulta la sua voce nella pagina delle release.

Modifiche incompatibili

Rimosso: cloudflareCache()

Nelle versioni precedenti, cloudflareCache() di @emdash-cms/cloudflare forniva un provider di cache delle route che svuotava le pagine in cache tramite l’API REST di Cloudflare.

cloudflareCache() e i suoi punti di ingresso @emdash-cms/cloudflare/cache e @emdash-cms/cloudflare/cache/config sono stati rimossi. Un sito che lo importa non compila.

Cosa devo fare?

Sostituiscilo con il provider cacheCloudflare() dell’adattatore Astro per Cloudflare, che usa Workers Cache. L’adattatore abilita Workers Cache nella configurazione di distribuzione generata quando questo provider è impostato.

L’esempio seguente mostra la modifica in astro.config.mjs:

import { cloudflareCache } from "@emdash-cms/cloudflare";
import { cacheCloudflare } from "@astrojs/cloudflare/cache";

export default defineConfig({
	cache: {
		provider: cloudflareCache(),
		provider: cacheCloudflare(),
	},
});

Workers Cache svuota la cache con cache.purge() di cloudflare:workers, quindi puoi eliminare i secret CF_ZONE_ID e CF_CACHE_PURGE_TOKEN dal tuo Worker. La cache degli oggetti KV (kvCache()) non cambia.

Rimosso: Comments e CommentForm da emdash/ui

Nelle versioni precedenti, i componenti Comments e CommentForm erano esportati sia da emdash/ui sia da emdash/ui/comments.

Ora sono esportati solo da emdash/ui/comments. Un sito che importa uno dei due componenti da emdash/ui non compila.

Cosa devo fare?

Aggiorna l’import. I componenti in sé non cambiano.

---
import { Comments, CommentForm } from "emdash/ui";
import { Comments, CommentForm } from "emdash/ui/comments";
---

Rimosso: emdash dev e emdash auth secret

Nelle versioni precedenti, emdash dev avviava un server di sviluppo basato su un ./data.db locale, e emdash auth secret generava un valore per EMDASH_AUTH_SECRET.

Entrambi i comandi sono stati rimossi. Eseguirne uno termina con Unknown command.

Cosa devo fare?

Sostituisci emdash dev con lo script di sviluppo del tuo sito, come pnpm dev, oppure esegui astro dev. Il sito userà quindi l’adattatore del database della sua configurazione.

Se il tuo package.json ha una chiave url sotto emdash, eliminala. Per generare i tipi da un sito remoto, esegui emdash types --url <site-url> oppure imposta EMDASH_URL.

Rimuovi emdash auth secret dai tuoi script. Se il tuo sito ha già EMDASH_AUTH_SECRET impostato, conservalo: EmDash lo legge ancora in modo che gli hash IP memorizzati di chi commenta restino stabili. Per cifrare a riposo i secret dei plugin, genera una chiave di cifratura con emdash secrets generate.

Rimosso: experimental.registry

Nelle versioni precedenti, potevi configurare il registro dei plugin con experimental.registry nelle opzioni di emdash().

L’opzione è stata rimossa, insieme all’opzione experimental stessa. Un sito che imposta ancora experimental.registry fallisce all’avvio con un errore che nomina l’opzione registry di primo livello.

Cosa devo fare?

Sposta il valore, invariato, nell’opzione registry di primo livello. Accetta la stessa stringa URL o lo stesso oggetto di configurazione.

emdash({
	experimental: {
		registry: {
			aggregatorUrl: "https://registry.example.com",
			policy: { minimumReleaseAge: "48h" },
		},
	},
	registry: {
		aggregatorUrl: "https://registry.example.com",
		policy: { minimumReleaseAge: "48h" },
	},
});

Se ti resta un blocco experimental: {} vuoto, eliminalo. Le configurazioni TypeScript lo segnalano come errore.

Modificato: i punti di ingresso interni spostati in emdash/internal/

Nelle versioni precedenti, emdash esponeva punti di ingresso come emdash/routes/*, emdash/middleware/*, emdash/db/sqlite-migrations e emdash/plugin-test-runtime che carica solo EmDash stesso.

Questi punti di ingresso si trovano sotto emdash/internal/. Lo stesso vale per gli esecutori di migrazioni D1 e Hyperdrive in @emdash-cms/cloudflare, che si trovano sotto @emdash-cms/cloudflare/internal/db/. Non fanno parte dell’API pubblica e le loro esportazioni possono cambiare in qualsiasi release. I siti che configurano EmDash tramite emdash() in astro.config.mjs non sono interessati.

Cosa devo fare?

Se il tuo progetto importa direttamente uno di questi percorsi, sostituisci l’import con l’API pubblica:

  • Per configurare un database, una cache degli oggetti o un provider multimediale, usa sqlite(), libsql() o postgres() da emdash/db, memoryCache() da emdash/astro oppure localMedia() da emdash/media.
  • Per testare un plugin, usa @emdash-cms/plugin-test invece di emdash/plugin-test-runtime.
  • Per eseguire il tuo middleware prima di quello di EmDash, imposta l’opzione middleware.outer di emdash().

I middleware interni di autenticazione, configurazione iniziale, reindirizzamento e contesto della richiesta non hanno un sostituto pubblico.

Deprecazioni

Deprecato: nomi precedenti delle capability dei plugin

Nelle versioni precedenti, i plugin potevano dichiarare capability con nomi come read:content, network:fetch e page:inject senza alcun avviso.

EmDash registra un avviso all’avvio per ogni plugin che dichiara uno di questi nomi deprecati, indicando la sostituzione attuale per ciascuno (ad esempio read:content → content:read). I nomi deprecati continuano a funzionare per tutta la serie 1.x.

Cosa devo fare?

Se un plugin che usi genera l’avviso, aggiornalo a una versione che usa i nomi attuali oppure chiedi al suo autore di pubblicarne una. Se mantieni il plugin, rinomina le capability nel suo manifest. Consulta Capability e sicurezza per i nomi attuali.