EmDash aktualisieren: So kommt deine Site sicher auf die neue Version

Getestet mit einem Update von EmDash 1.0.1 auf 1.1.0, mit npm und der Blog-Vorlage auf Cloudflare. Überarbeitet für EmDash 1.2.0 am 7. Oktober 2026: Das Update von 1.1.0 auf 1.2.0 habe ich lokal nachgeprüft. Was sich geändert hat, steht am Ende des Artikels.

Bei WordPress klickst du im Dashboard auf „Jetzt aktualisieren“, und ein paar Sekunden später läuft die neue Version. Bei EmDash suchst du diesen Knopf vergeblich. Das ist Absicht: EmDash ist Code in deinem Projekt, und ein Update ist ein Deployment wie jede andere Änderung am Code auch.

Damit ich dir nicht nur erzähle, wie das gehen sollte, habe ich eine frische Site mit EmDash 1.0.1 auf Cloudflare gestellt, sie auf 1.1.0 aktualisiert und danach wieder zurückgesetzt. Hier sind die Schritte, die Zeiten und das, was dabei mit deiner Datenbank passiert. Falls du noch gar keine EmDash-Site hast, fang mit dem Einstieg in EmDash an.

Woran du merkst, dass es ein Update gibt

Der Admin sagt es dir. Auf dem Dashboard erscheint oben ein Hinweis mit der neuen Version und der, die du gerade verwendest. Unten links in der Navigation steht immer die Version, die läuft.

Zwei Dinge sind dabei gut zu wissen. Der Hinweis erscheint erst, wenn eine Version mindestens 24 Stunden öffentlich ist, und EmDash fragt höchstens einmal am Tag bei npm nach. Am Release-Tag selbst siehst du ihn also womöglich noch nicht. Und der Knopf „Release Notes“ führt zu den Releases von EmDash auf GitHub. Lies dort die Änderungen der neuen Version vor dem Update, denn da steht, was du allenfalls anpassen musst. Auf dieser Site fassen wir jede Version zusätzlich in der Rubrik Changelog zusammen.

Bevor du anfängst

Drei Dinge solltest du klären, bevor du etwas anfasst:

• Wie kommt deine Site online? Hast du sie mit npm run deploy von deinem Rechner aus hochgeladen, machst du das beim Update genauso. Ist dein Projekt mit Git verbunden, etwa über Workers Builds bei Cloudflare, stellt ein Push die neue Version online. Dann gilt alles hier, nur dass du am Ende committest und pushst, statt deploy aufzurufen.
• Ist dein Projekt in Git? Dann ist der Weg zurück für den Code ein einziger Befehl. Wenn nicht, ist jetzt ein guter Moment dafür.
• Wo liegen deine Daten? Inhalte, Benutzer und Einstellungen liegen in der Datenbank, auf Cloudflare in D1. Das Update ändert den Code, und beim ersten Aufruf passt EmDash die Datenbank an. Dazu weiter unten mehr.

Schritt 1: Einen Sicherungspunkt merken

D1 sichert deine Datenbank laufend selbst. Cloudflare nennt das Time Travel: Du kannst eine Datenbank auf jede Minute der letzten 30 Tage zurücksetzen, im kostenlosen Workers-Plan auf die letzten 7 Tage (Doku zu Time Travel). Einschalten musst du nichts.

Praktisch ist trotzdem, sich den Stand direkt vor dem Update zu notieren. Dafür gibt es einen Befehl, der dir den aktuellen Sicherungspunkt ausgibt, ein sogenanntes Bookmark. Den Namen deiner Datenbank findest du in wrangler.jsonc unter database_name:

npx wrangler d1 time-travel info DEINE-DATENBANK

Kopier dir die Zeile mit time-travel restore in deine Notizen. Mit ihr kommst du im Notfall genau auf diesen Stand zurück.

Welche anderen Sicherungen es bei EmDash gibt und was jede davon abdeckt, liest du im Artikel über Backups bei EmDash.

Schritt 2: Die Pakete anheben

EmDash besteht aus mehreren Paketen. Bei einer Site aus der Cloudflare-Vorlage sind es zwei: emdash selbst und @emdash-cms/cloudflare. Hebe sie immer zusammen an:

npm install emdash@latest @emdash-cms/cloudflare@latest

Mit pnpm heisst der Befehl pnpm add, der Rest ist gleich. Nutzt du weitere Pakete, deren Name mit @emdash-cms/ beginnt, etwa Plugins, nimm sie in denselben Befehl auf.

Bei mir dauerte das 20 Sekunden. In package.json haben sich genau zwei Zeilen geändert, dazu die Datei package-lock.json, in der npm die genauen Versionen festhält.

Warum beide Pakete? In einem früheren Test habe ich absichtlich nur emdash angehoben und @emdash-cms/cloudflare auf der alten Version gelassen. Die Site liess sich ohne Fehler bauen, und nichts hat vor dem Unterschied gewarnt. Genau deshalb solltest du dich nicht darauf verlassen, dass dir ein Werkzeug eine vergessene Hälfte meldet.

Ein Detail am Rande: Die Vorlage schreibt die Version mit einem Zirkumflex in package.json, etwa ^1.0.1. Das heisst „1.0.1 oder neuer, aber noch 1.x“. Ein frisch angelegtes Projekt bekommt deshalb sofort die neueste 1.x-Version. Bei mir landete sogar create-emdash@1.0.1 direkt auf EmDash 1.1.0.

Neu: alles mit einem Befehl. Seit Oktober gibt es npx upgrade-emdash@latest (#3804). Der Befehl findet alle Pakete von EmDash im Projekt selbst und hebt sie zusammen an. Die vergessene Hälfte von oben kann dir damit nicht passieren. Dazu schreibt er in .emdash/UPGRADE.md, was sich zwischen deiner und der neuen Version geändert hat und ob eine Migration dazukommt. Mit --dry-run zeigt er vorher nur den Plan, auf dieser Site waren das zwei Pakete von 1.1.0 auf 1.2.0 und 67 Changelog-Einträge. Code, Datenbank und Deployment fasst er nicht an, die Schritte 3 bis 5 bleiben also gleich. Voraussetzung ist EmDash 0.35.0 oder neuer.

Schritt 3: Lokal ausprobieren

Bevor die neue Version live geht, starte sie einmal auf deinem Rechner:

npm run dev

Öffne die Website und den Admin unter http://localhost:4321/_emdash/admin und klick dich durch die Seiten, die dir wichtig sind. Hast du eigene Vorlagen oder Plugins, sind das die Stellen, an denen ein Update am ehesten etwas verändert. Steht in den Release Notes, dass du etwas anpassen musst, ist jetzt der Moment dafür.

Schritt 4: Neu deployen

Wenn lokal alles passt, stellst du die neue Version online:

npm run deploy

Ist dein Projekt mit Git verbunden, committest du stattdessen package.json und package-lock.json und pushst. Den Rest erledigt der Build bei Cloudflare.

Bei mir dauerte das Deployment 37 Sekunden. Am Ende nennt Wrangler die ID der neuen Version. Die brauchst du, falls du zurück willst.

Schritt 5: Der erste Aufruf und die Migrationen

Jetzt passiert der Teil, den man nicht sieht. Neue EmDash-Versionen bringen manchmal Änderungen an der Datenbank mit, zum Beispiel eine neue Tabelle für ein neues Feature. Diese Änderungen heissen Migrationen. EmDash führt sie standardmässig beim ersten Aufruf der Site nach dem Deployment selbst aus.

In meinem Test hatte die Datenbank vor dem Update 88 Migrationen hinter sich, danach 90. Die beiden neuen gehören zu den Weiterleitungen. Alle acht Beiträge der Vorlage waren danach noch da. Den Unterschied merkst du nur an der Zeit: Der erste Aufruf der Startseite dauerte 5,4 Sekunden, die nächsten Seiten kamen in 1,2 bis 1,6 Sekunden. Beim Update von 1.1.0 auf 1.2.0 kam keine neue Migration dazu, die Datenbank blieb bei 90, und alle acht Beiträge waren wieder da.

Ruf deshalb nach dem Deployment selbst einmal die Startseite auf, bevor es deine Besucher tun. Dann schau in den Admin.

Der Hinweis ist weg, unten links steht die neue Version, und in meinem Fall war mit „Kalender“ ein neuer Eintrag in der Navigation dazugekommen.

Für Teams, die Änderungen an der Datenbank lieber selbst steuern, gibt es die Einstellung migrations in astro.config.mjs. Mit runtime: "check" führt EmDash Migrationen nicht selbst aus, sondern antwortet mit einem Fehler 503, bis sie erledigt sind. Mit runtime: "manual" prüft es gar nichts. Ausführen kannst du sie dann mit npx emdash migrate, zum Beispiel als Schritt in deinem Deployment (Doku zur Konfiguration). Für eine einzelne Site ist die Voreinstellung auto die einfachste Wahl.

Wenn etwas schiefgeht: zurück zur alten Version

Für den Code ist der Weg zurück schnell. Cloudflare hebt jede Version deines Workers auf, und ein Befehl schaltet eine frühere wieder live. Die Liste der Versionen zeigt dir npx wrangler deployments list, danach:

npx wrangler rollback VERSIONS-ID

Das dauerte bei mir wenige Sekunden. Lies die Warnung aber genau: Zurück springt nur der Code. Die Datenbank bleibt, wie sie ist, also mit den Migrationen der neuen Version.

In meinem Test lief EmDash 1.0.1 mit der bereits migrierten Datenbank problemlos weiter. Startseite und Beiträge antworteten normal. Das ging, weil die beiden neuen Migrationen nur etwas hinzugefügt haben, das die alte Version einfach ignoriert. Garantiert ist das nicht. EmDash hat keinen Befehl, der Migrationen rückgängig macht.

Muss auch die Datenbank zurück, kommt der Sicherungspunkt aus Schritt 1 ins Spiel:

npx wrangler d1 time-travel restore DEINE-DATENBANK --bookmark=DEIN-BOOKMARK

Das ist der letzte Ausweg, nicht der erste. Ein Restore überschreibt die Datenbank vollständig. Alles, was seit dem Sicherungspunkt dazugekommen ist, ist danach weg, auch ein Kommentar oder ein Beitrag, der in der Zwischenzeit erschienen ist. Wrangler gibt dir dabei immerhin ein neues Bookmark aus, mit dem du den Restore wieder rückgängig machen kannst.

Meine Reihenfolge im Notfall: erst den Code zurückrollen und prüfen, ob die Site damit läuft. Nur wenn nicht, die Datenbank zurücksetzen.

Kurz zusammengefasst

1. Release Notes lesen.
2. Sicherungspunkt notieren: npx wrangler d1 time-travel info DEINE-DATENBANK.
3. Pakete zusammen anheben: npx upgrade-emdash@latest oder von Hand npm install emdash@latest @emdash-cms/cloudflare@latest.
4. Lokal prüfen: npm run dev.
5. Deployen: npm run deploy oder committen und pushen.
6. Startseite einmal selbst aufrufen und im Admin die Version prüfen.

Was sich in einer bestimmten Version geändert hat, fassen wir für jede Version in der Rubrik Changelog zusammen, zuletzt für EmDash 1.2.

Und bei dir?

Wie aktualisierst du deine EmDash-Sites: von Hand, über Git oder mit einem eigenen Skript? Und ist dir dabei schon einmal etwas schiefgegangen? Schreib es in die Kommentare. Ich ergänze den Artikel mit dem, was ihr meldet.