EmDash zu einem bestehenden Astro-Projekt hinzufügen

npm create emdash@latest liefert ein vorkonfiguriertes Projekt, aber EmDash lässt sich auch auf eine Astro-Website aufpfropfen, die Sie bereits haben. Diese Anleitung führt durch jede Anforderung, die das Starter-Template normalerweise für Sie übernimmt — jede einzelne erzeugt einen verwirrenden Fehler, wenn sie fehlt, also arbeiten Sie die Checkliste der Reihe nach ab.

Voraussetzungen

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

Pakete installieren

Installieren Sie EmDash zusammen mit seinen erforderlichen Peer-Dependencies. React betreibt die Admin-Oberfläche unter /_emdash/admin; es ist auch erforderlich, wenn Ihre 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

Deployment auf Cloudflare? Fügen Sie auch die Cloudflare-Pakete hinzu — die Anleitung Auf Cloudflare bereitstellen behandelt sie im Detail:

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

Integrationen registrieren

Fügen Sie sowohl react() als auch emdash() zu Ihrem integrations-Array hinzu. Die Registrierung von @astrojs/react ist nicht optional: Das bloße Installieren des Pakets reicht nicht aus, und ohne die Integration baut der Admin zwar erfolgreich, hydratisiert aber nie — die Seite bleibt ewig 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

Erstellen Sie src/live.config.ts, damit Astros Content-Layer EmDash-Inhalte auflösen kann. Ohne sie haben getEmDashCollection / getEmDashEntry keine Live-Collection, durch die sie routen können.

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

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

Ihre bestehende src/content.config.ts (dateibasierte Collections) funktioniert weiterhin daneben — siehe EmDash für Astro-Entwickler für das Zusammenspiel der beiden.

Installation überprüfen

Auf Cloudflare bereitstellen

Folgen Sie Auf Cloudflare bereitstellen für das vollständige Setup (D1-Datenbank, R2-Medien-Bucket, Cron-Trigger). Zwei Dinge stolpern bestehende Projekte besonders:

• Verwenden Sie Cloudflare Workers, nicht Pages. Der @astrojs/cloudflare-Adapter gibt eine wrangler.json aus, die Pages nicht akzeptiert. Wenn Ihre Website derzeit auf Pages deployt, migrieren Sie sie zuerst zu Workers.
• Bindings müssen in Ihrer wrangler.jsonc existieren. Mindestens benötigen Sie ein D1-Binding für die Datenbank und ein R2-Binding für Medien, passend zu den Binding-Namen in Ihrer astro.config.mjs.

Fehlerbehebung

Nächste Schritte

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