Erste Schritte

Diese Anleitung führt Sie durch die Erstellung Ihrer ersten EmDash-Website, von der Installation bis zur Veröffentlichung Ihres ersten Beitrags.

Voraussetzungen

• Node.js v22.16.0 oder höher (ungerade Versionsnummern werden nicht unterstützt)
• npm, pnpm oder yarn
• Ein Code-Editor (VS Code empfohlen)

Neues Projekt erstellen

npm create emdash@latest

pnpm create emdash@latest

yarn create emdash

Folgen Sie den Eingabeaufforderungen, um Ihr Projekt zu benennen und Ihre Einstellungen festzulegen.

Entwicklungsserver starten

Setup-Assistenten abschließen

Beim ersten Besuch des Admin-Panels führt Sie der EmDash-Setup-Assistent durch die Erstkonfiguration:

Sobald Ihr Passkey registriert ist, sind Sie eingeloggt und werden zum Admin-Dashboard weitergeleitet.

Ihr erster Beitrag

Projektstruktur

Ihr EmDash-Projekt folgt einer Standard-Astro-Struktur mit einigen Ergänzungen:

my-emdash-site/
├── astro.config.mjs      # Astro + EmDash-Konfiguration
├── src/
│   ├── live.config.ts    # Live Collections-Konfiguration
│   ├── pages/
│   │   ├── index.astro   # Startseite
│   │   └── posts/
│   │       └── [...slug].astro  # Dynamische Beitragsseiten
│   ├── layouts/
│   │   └── Base.astro    # Basis-Layout
│   └── components/       # Ihre Astro-Komponenten
├── .emdash/
│   ├── seed.json         # Template-Seed-Datei
│   └── types.ts          # Generierte TypeScript-Typen
└── package.json

Konfigurationsdateien

astro.config.mjs

Die folgende Konfiguration registriert EmDash als Astro-Integration mit einer lokalen SQLite-Datenbank und lokalem Dateispeicher:

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

export default defineConfig({
	integrations: [
		react(), // Erforderlich — die Admin-Oberfläche ist eine React-App
		emdash({
			database: sqlite({ url: "file:./data.db" }),
			storage: local({
				directory: "./uploads",
				baseUrl: "/_emdash/api/media/file",
			}),
		}),
	],
});

src/live.config.ts

Die folgende Datei verbindet EmDash mit Astros Content-System über eine einzelne Live-Collection:

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

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

Umgebungsvariablen

Für die Produktion generieren Sie einen Verschlüsselungsschlüssel für Plugin-Geheimnisse mit dem folgenden Befehl:

npx emdash secrets generate

Fügen Sie den generierten Wert als EMDASH_ENCRYPTION_KEY zu Ihrer Umgebung hinzu, wie unten gezeigt. Dieser Schlüssel verschlüsselt Plugin-Geheimnisse im Ruhezustand. Setzen Sie ihn jetzt, damit Ihr Deployment bereit ist, wenn die Plugin-Geheimnis-Verschlüsselung ihn verwendet.

EMDASH_ENCRYPTION_KEY=emdash_enc_v1_...

Der Schlüssel wird nie in der Datenbank gespeichert — nur verschlüsselter Chiffretext. Sichern Sie ihn an einem dauerhaften Ort, denn ihn zu verlieren bedeutet, jedes damit verschlüsselte Geheimnis zu verlieren.

Das Preview-HMAC-Geheimnis und der Kommentator-IP-Hash-Salt werden beim ersten Gebrauch generiert und in der Datenbank gespeichert, Sie müssen sie also nicht setzen. Überschreiben Sie das Preview-Geheimnis nur, wenn ein separater Prozess dieselben Token wie Ihre Hauptseite verifizieren muss, wie unten gezeigt.

EMDASH_PREVIEW_SECRET=your-preview-secret

Inhalte in Seiten abfragen

Verwenden Sie die Abfragefunktionen von EmDash in Ihren Astro-Seiten. Diese folgen Astros Live-Collections-Muster und geben { entries, error } für Collections und { entry, error } für einzelne Einträge zurück:

---
import { getEmDashCollection } from "emdash";
import Base from "../layouts/Base.astro";

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

<Base title="Home">
  <h1>Neueste Beiträge</h1>
  <ul>
    {posts.map((post) => (
      <li>
        <a href={`/posts/${post.slug}`}>{post.data.title}</a>
      </li>
    ))}
  </ul>
</Base>

Die folgende Seite ruft einen einzelnen Eintrag nach Slug ab:

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

const { slug } = Astro.params;
const { entry: post } = await getEmDashEntry("posts", slug);

if (!post) {
  return Astro.redirect("/404");
}
---

<h1>{post.data.title}</h1>

TypeScript-Typen generieren

Für vollständige Typsicherheit generieren Sie Typen aus Ihrem Datenbankschema:

npx emdash types

Dies erstellt .emdash/types.ts mit Interfaces für alle Ihre Collections. Ihr Editor wird nun Feldnamen automatisch vervollständigen und Typfehler erkennen.

Nächste Schritte

Mit der laufenden Website decken die folgenden Seiten ab, was als nächstes zu tun ist:

• Kernkonzepte — Verstehen, wie EmDash unter der Haube funktioniert
• Mit Inhalten arbeiten — Inhalte abfragen und rendern lernen
• Medienbibliothek — Bilder und Dateien hochladen und verwalten
• Blog erstellen — Einen kompletten Blog mit Kategorien und Tags aufbauen
• Auf Cloudflare bereitstellen — Ihre Website in Produktion bringen