EmDash zu einem bestehenden Astro-Projekt hinzufügen

Diese Anleitung fügt EmDash zu einem Astro-Projekt hinzu und überprüft die Integration mit einem veröffentlichten Eintrag. Sie verwendet den Node.js-Adapter, SQLite und lokalen Medien-Storage, sodass der komplette Pfad auf einer Maschine funktioniert.

Bevor Sie beginnen

Verwenden Sie Astro 6 oder höher und Node.js 22.16 oder höher. Überprüfen Sie beide Versionen im Projekt:

node --version
npx astro --version

Diese Anleitung stellt die Website auf Astros server-Output um und konfiguriert den Node.js-Adapter. Das ändert, wie die Website gebaut und bereitgestellt wird. Wenn das Projekt bereits einen anderen Server-Adapter verwendet, fügen Sie keinen zweiten hinzu. Behalten Sie diesen Adapter bei und folgen Sie seinen Deployment-Anforderungen; für Cloudflare verwenden Sie die Cloudflare Workers-Anleitung.

Committen oder speichern Sie das aktuelle Projekt anderweitig, bevor Sie seine Konfiguration ändern.

EmDash installieren

Installieren Sie EmDash, den Node.js-Adapter und React-Unterstützung:
npm
```
npm install emdash @astrojs/node @astrojs/react react react-dom
```
pnpm
```
pnpm add emdash @astrojs/node @astrojs/react react react-dom
```
yarn
```
yarn add emdash @astrojs/node @astrojs/react react react-dom
```
EmDash verwendet React für das Admin-Panel, auch wenn die öffentliche Website keine React-Komponenten hat.

Registrieren Sie den Adapter, React und EmDash in astro.config.mjs. Wenn die Datei bereits andere Integrationen oder Einstellungen enthält, behalten Sie sie bei und fügen Sie die relevanten Einträge aus diesem Beispiel hinzu:

import node from "@astrojs/node";
import react from "@astrojs/react";
import { defineConfig } from "astro/config";
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",
            }),
        }),
    ],
});

SQLite speichert den Inhalt und das Content-Model in data.db. Der lokale Storage-Adapter schreibt Medien nach uploads/ und stellt sie über EmDashs Medien-Route bereit. Fügen Sie beide Pfade zu .gitignore hinzu, falls sie nicht bereits ausgeschlossen sind.

Erstellen Sie src/live.config.ts, um EmDash mit Astros Content-System zu verbinden:
```
import { defineLiveCollection } from "astro:content";
import { emdashLoader } from "emdash/runtime";

export const collections = {
    _emdash: defineLiveCollection({ loader: emdashLoader() }),
};
```
Wenn das Projekt bereits src/live.config.ts hat, fügen Sie den _emdash-Eintrag zum exportierten collections-Objekt hinzu, anstatt die Datei zu ersetzen. Eine separate src/content.config.ts für dateibasierte Collections funktioniert weiterhin daneben.
Generieren Sie einen lokalen Verschlüsselungsschlüssel und schreiben Sie ihn in .env:
```
npx emdash secrets generate --write .env
```
Bestätigen Sie, dass .env von .gitignore ausgeschlossen ist. Der Schlüssel schützt Plugin-Secrets, die in der Datenbank gespeichert sind. Das Ersetzen oder Verlieren des Schlüssels macht diese verschlüsselten Werte unlesbar, erstellen Sie daher ein geschütztes Backup, bevor Sie die Website bereitstellen.

Website und Inhalte einrichten

Starten Sie den Entwicklungsserver:
```
npm run dev
```
Öffnen Sie http://localhost:4321/_emdash/admin/. Der erste Besuch leitet zum Setup-Assistenten weiter. Geben Sie die Website-Details ein, erstellen Sie das Administratorkonto und registrieren Sie einen Passkey.

Da dieses Projekt keine Seed-Datei hat, wendet das Setup EmDashs eingebautes Startmodell an. Es erstellt Posts- und Pages-Collections, Titel- und Inhaltsfelder sowie Kategorie- und Tag-Taxonomien. Es fügt keine Beispieleinträge hinzu.
Öffnen Sie Posts, wählen Sie New Post und geben Sie EmDash is connected als Titel ein. Wählen Sie Save, um den Eintrag zu erstellen, dann wählen Sie Publish.

Die Datenbank enthält jetzt einen veröffentlichten Eintrag in der eingebauten posts-Collection. Der nächste Schritt liest ihn von einer Astro-Seite.

Den Eintrag abfragen

Erstellen Sie eine server-gerenderte Testseite, die die veröffentlichten Posts auflistet:

---
import { getEmDashCollection } from "emdash";

const { entries: posts, error } = await getEmDashCollection("posts");

if (error) {
	throw error;
}
---

<h1>EmDash posts</h1>
<ul>
	{posts.map((post) => <li>{post.data.title}</li>)}
</ul>

Öffnen Sie http://localhost:4321/emdash-test/. Die Seite zeigt EmDash is connected an. Wenn Sie den Titel im Admin-Panel ändern und erneut veröffentlichen, zeigt das Neuladen dieser Seite den aktualisierten Titel.

Während der lokalen Entwicklung generiert EmDash auch emdash-env.d.ts aus dem aktuellen Content-Model. Die generierten Deklarationen geben TypeScript den posts-Collection-Namen und sein title-Feld. Bearbeiten Sie diese generierte Datei nicht manuell.

Wenn die Überprüfung fehlschlägt

Wenn das Admin bei Loading EmDash… bleibt, überprüfen Sie, dass react() im Astro- integrations-Array erscheint. Die Installation von @astrojs/react ohne Registrierung reicht nicht.
Wenn getEmDashCollection() einen Fehler über die Live-Collection zurückgibt, überprüfen Sie, dass src/live.config.ts _emdash mit emdashLoader() exportiert.
Wenn die Seite in der Entwicklung funktioniert, aber bereitgestellte Bearbeitungen nicht erscheinen, überprüfen Sie, dass die Seite nicht vorgerendert ist und dass die bereitgestellte Anwendung Server-Output verwendet.
Wenn der Build einen Import nicht auflösen kann, führen Sie den Installationsbefehl erneut aus und bestätigen Sie, dass die fünf Pakete zu diesem Projekt hinzugefügt wurden und nicht zu einem anderen Workspace-Verzeichnis.

Lesen Sie Konfiguration für andere Datenbanken, Storage-Adapter und Authentifizierungsoptionen. Der Leitfaden zur Inhaltsabfrage behandelt Filter, Paginierung, Vorschauen und Cache-Hinweise.