EmDash zu einem bestehenden Astro-Projekt hinzufügen

npm create emdash@latest liefert ein vorkonfiguriertes Projekt, aber EmDash lässt sich auch auf eine bestehende Astro-Website aufsetzen. Diese Anleitung führt durch jede Anforderung, die die Starter-Vorlage normalerweise für dich erledigt — jede einzelne verursacht einen verwirrenden Fehler, wenn sie fehlt, also arbeite die Checkliste der Reihe nach ab.

Voraussetzungen

• Astro 6 oder höher — aktualisiere zuerst, wenn du auf einer älteren Major-Version bist (npx @astrojs/upgrade)
• Node.js v22.12.0 oder höher (ungerade Versionsnummern werden nicht unterstützt)
• Server-Output — EmDash liefert Inhalte zur Laufzeit, daher braucht dein Projekt output: "server" und einen Adapter (Node, Cloudflare, …)

Pakete installieren

Installiere EmDash zusammen mit seinen erforderlichen Peer-Dependencies. React betreibt die Admin-Oberfläche unter /_emdash/admin; es ist erforderlich, auch wenn deine Website selbst kein React verwendet.

npm install emdash @astrojs/react react react-dom

pnpm add emdash @astrojs/react react react-dom

yarn add emdash @astrojs/react react react-dom

Für eine lokale SQLite-Datenbank (Standard für Entwicklung) installiere auch den Treiber:

npm install better-sqlite3

Deployment auf Cloudflare? Füge auch die Cloudflare-Pakete hinzu — die Anleitung Deploy auf Cloudflare behandelt sie im Detail:

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

Integrationen registrieren

Füge sowohl react() als auch emdash() zu deinem integrations-Array hinzu. Die Registrierung von @astrojs/react ist nicht optional: Das Paket nur zu installieren reicht nicht aus, und ohne die Integration baut der Admin einwandfrei, hydratisiert aber nie — die Seite bleibt bei “Loading EmDash…” stehen.

import { defineConfig } from "astro/config";
import node from "@astrojs/node";
import react from "@astrojs/react";
import emdash, { local } from "emdash/astro";
import { sqlite } from "emdash/db";

export default defineConfig({
	output: "server",
	adapter: node({ mode: "standalone" }),
	integrations: [
		react(),
		emdash({
			database: sqlite({ url: "file:./data.db" }),
			storage: local({
				directory: "./uploads",
				baseUrl: "/_emdash/api/media/file",
			}),
		}),
	],
});

Live-Collections-Loader hinzufügen

Erstelle src/live.config.ts, damit Astros Content-Layer EmDash-Inhalte auflösen kann. Ohne sie haben getEmDashCollection / getEmDashEntry keine Live-Collection zum Durchrouten.

import { defineLiveCollection } from "astro:content";
import { emdashLoader } from "emdash/runtime";

export const collections = {
	_emdash: defineLiveCollection({ loader: emdashLoader() }),
};

Deine bestehende src/content.config.ts (dateibasierte Collections) funktioniert parallel weiter — siehe EmDash für Astro-Entwickler für Details zur Koexistenz.

Installation überprüfen

Deployment auf Cloudflare

Folge Deploy auf Cloudflare für das vollständige Setup (D1-Datenbank, R2-Medienbucket, Cron-Trigger). Zwei Dinge bereiten bestehenden Projekten besonders Probleme:

• Verwende Cloudflare Workers, nicht Pages. Der @astrojs/cloudflare-Adapter gibt eine wrangler.json aus, die Pages nicht akzeptiert. Wenn deine Website derzeit auf Pages deployt, migriere sie zuerst zu Workers.
• Bindings müssen in deiner wrangler.jsonc existieren. Du brauchst mindestens ein D1-Binding für die Datenbank und ein R2-Binding für Medien, die den Binding-Namen in deiner astro.config.mjs entsprechen.

Fehlerbehebung

Nächste Schritte

• EmDash für Astro-Entwickler — Wie EmDash-Konzepte auf das abbilden, was du bereits kennst
• Mit Inhalten arbeiten — Inhalte abfragen und rendern
• Deploy auf Cloudflare — Die Website in Produktion bringen