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

Upgrade auf EmDash 1.0

Auf dieser Seite

EmDash 1.0 entfernt APIs, die während 0.x als veraltet markiert wurden, und verschiebt die Einstiegspunkte, die nur EmDash selbst lädt, unter emdash/internal/. Dieser Leitfaden listet jede Breaking Change auf und erklärt, was Sie in Ihrer Website anpassen müssen.

Abhängigkeiten aktualisieren

Aktualisieren Sie emdash und alle anderen EmDash-Pakete, die Ihre Website verwendet, auf die neuesten Versionen und bauen Sie anschließend neu. Das folgende Beispiel aktualisiert eine Cloudflare-Website:

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

Wenn Ihre Bereitstellung emdash migrate ausführt, führen Sie den Befehl mit der Datei .emdash/migrations.json aus, die ein nach dem Upgrade erstellter Build erzeugt hat. Der Befehl lehnt ein Manifest ab, das von einer früheren EmDash-Version geschrieben wurde.

Nach dem Upgrade lässt sich Ihre Website möglicherweise ohne weitere Änderungen bauen und ausführen. Wenn der Build fehlschlägt oder EmDash beim Start einen Fehler meldet, arbeiten Sie die folgenden Breaking Changes durch.

Die vollständige Liste der Änderungen in jedem Paket finden Sie in dessen Eintrag auf der Releases-Seite.

Breaking Changes

Entfernt: cloudflareCache()

In früheren Versionen stellte cloudflareCache() aus @emdash-cms/cloudflare einen Route-Cache-Provider bereit, der zwischengespeicherte Seiten über die Cloudflare-REST-API invalidierte.

cloudflareCache() und seine Einstiegspunkte @emdash-cms/cloudflare/cache und @emdash-cms/cloudflare/cache/config sind entfernt. Eine Website, die ihn importiert, lässt sich nicht mehr bauen.

Was soll ich tun?

Ersetzen Sie ihn durch den Provider cacheCloudflare() des Astro-Cloudflare-Adapters, der Workers Cache verwendet. Der Adapter aktiviert Workers Cache in der generierten Bereitstellungskonfiguration, wenn dieser Provider gesetzt ist.

Das folgende Beispiel zeigt die Änderung 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 invalidiert mit cache.purge() aus cloudflare:workers, sodass Sie die Secrets CF_ZONE_ID und CF_CACHE_PURGE_TOKEN aus Ihrem Worker löschen können. Der KV-Objekt-Cache (kvCache()) bleibt unverändert.

Entfernt: Comments und CommentForm aus emdash/ui

In früheren Versionen wurden die Komponenten Comments und CommentForm sowohl aus emdash/ui als auch aus emdash/ui/comments exportiert.

Sie werden nur noch aus emdash/ui/comments exportiert. Eine Website, die eine der beiden Komponenten aus emdash/ui importiert, lässt sich nicht mehr bauen.

Was soll ich tun?

Aktualisieren Sie den Import. Die Komponenten selbst bleiben unverändert.

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

Entfernt: emdash dev und emdash auth secret

In früheren Versionen startete emdash dev einen Entwicklungsserver auf Basis einer lokalen ./data.db, und emdash auth secret erzeugte einen Wert für EMDASH_AUTH_SECRET.

Beide Befehle sind entfernt. Wenn Sie einen davon ausführen, endet er mit Unknown command.

Was soll ich tun?

Ersetzen Sie emdash dev durch das eigene Dev-Skript Ihrer Website, etwa pnpm dev, oder führen Sie astro dev aus. Die Website verwendet dann den Datenbank-Adapter aus ihrer Konfiguration.

Wenn Ihre package.json unter emdash einen Schlüssel url enthält, löschen Sie ihn. Um Typen von einer entfernten Website zu generieren, führen Sie emdash types --url <site-url> aus oder setzen Sie EMDASH_URL.

Entfernen Sie emdash auth secret aus Ihren Skripten. Wenn für Ihre Website bereits EMDASH_AUTH_SECRET gesetzt ist, behalten Sie es: EmDash liest es weiterhin, damit gespeicherte IP-Hashes von Kommentierenden stabil bleiben. Um Plugin-Secrets im Ruhezustand zu verschlüsseln, erzeugen Sie mit emdash secrets generate einen Verschlüsselungsschlüssel.

Entfernt: experimental.registry

In früheren Versionen konnten Sie die Plugin-Registry mit experimental.registry in den Optionen von emdash() konfigurieren.

Die Option ist entfernt, ebenso die Option experimental selbst. Eine Website, die experimental.registry weiterhin setzt, schlägt beim Start mit einem Fehler fehl, der die Option registry auf oberster Ebene nennt.

Was soll ich tun?

Verschieben Sie den Wert unverändert in die Option registry auf oberster Ebene. Sie akzeptiert dieselbe URL-Zeichenfolge oder dasselbe Konfigurationsobjekt.

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

Wenn ein leerer Block experimental: {} übrig bleibt, löschen Sie ihn. TypeScript-Konfigurationen melden ihn als Fehler.

Geändert: interne Einstiegspunkte nach emdash/internal/ verschoben

In früheren Versionen stellte emdash Einstiegspunkte wie emdash/routes/*, emdash/middleware/*, emdash/db/sqlite-migrations und emdash/plugin-test-runtime bereit, die nur EmDash selbst lädt.

Diese Einstiegspunkte liegen unter emdash/internal/. Dasselbe gilt für die D1- und Hyperdrive-Migrations-Executors in @emdash-cms/cloudflare, die unter @emdash-cms/cloudflare/internal/db/ liegen. Sie sind keine öffentliche API, und ihre Exporte können sich in jedem Release ändern. Websites, die EmDash über emdash() in astro.config.mjs konfigurieren, sind nicht betroffen.

Was soll ich tun?

Wenn Ihr Projekt einen dieser Pfade direkt importiert, ersetzen Sie den Import durch die öffentliche API:

  • Um eine Datenbank, einen Objekt-Cache oder einen Medien-Provider zu konfigurieren, verwenden Sie sqlite(), libsql() oder postgres() aus emdash/db, memoryCache() aus emdash/astro oder localMedia() aus emdash/media.
  • Um ein Plugin zu testen, verwenden Sie @emdash-cms/plugin-test statt emdash/plugin-test-runtime.
  • Um eigene Middleware vor der von EmDash auszuführen, setzen Sie die Option middleware.outer von emdash().

Für die interne Middleware für Authentifizierung, Einrichtung, Weiterleitungen und Request-Kontext gibt es keinen öffentlichen Ersatz.

Veraltete Funktionen

Veraltet: frühere Plugin-Capability-Namen

In früheren Versionen konnten Plugins Capabilities unter Namen wie read:content, network:fetch und page:inject ohne jede Warnung deklarieren.

EmDash protokolliert beim Start für jedes Plugin, das einen dieser veralteten Namen deklariert, eine Warnung und nennt dabei jeweils den aktuellen Ersatz (zum Beispiel read:content → content:read). Die veralteten Namen funktionieren während der gesamten 1.x-Reihe weiter.

Was soll ich tun?

Wenn ein von Ihnen verwendetes Plugin die Warnung auslöst, aktualisieren Sie es auf eine Version, die die aktuellen Namen verwendet, oder bitten Sie den Autor, eine solche zu veröffentlichen. Wenn Sie das Plugin selbst pflegen, benennen Sie die Capabilities in seinem Manifest um. Die aktuellen Namen finden Sie unter Capabilities & Sicherheit.