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.12.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-Assistent abschließen

Wenn Sie zum ersten Mal das Admin-Panel besuchen, führt Sie der EmDash Setup-Assistent durch die Erstkonfiguration:

Sobald Ihr Passkey registriert ist, sind Sie angemeldet 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-UI 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 Inhaltssystem über eine einzelne Live-Collection:

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

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

Umgebungsvariablen

Generieren Sie für die Produktion einen Verschlüsselungsschlüssel für Plugin-Secrets 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-Secrets im Ruhezustand. Setzen Sie ihn jetzt, damit Ihr Deployment bereit ist, wenn die Plugin-Secret-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, da sein Verlust den Verlust jedes damit verschlüsselten Secrets bedeutet.

Das Preview-HMAC-Secret und der Commenter-IP-Hash-Salt werden bei der ersten Verwendung generiert und in der Datenbank gespeichert, sodass Sie sie nicht setzen müssen. Überschreiben Sie das Preview-Secret nur, wenn ein separater Prozess dieselben Tokens wie Ihre Hauptseite verifizieren muss, wie unten gezeigt.

EMDASH_PREVIEW_SECRET=your-preview-secret

Inhalte in Seiten abfragen

Verwenden Sie die EmDash-Abfragefunktionen in Ihren Astro-Seiten. Diese folgen dem Astro 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 per 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 behandeln die folgenden Seiten, was als Nächstes zu tun ist:

• Kernkonzepte — Verstehen Sie, wie EmDash unter der Haube funktioniert
• Mit Inhalten arbeiten — Lernen Sie, Inhalte abzufragen und zu rendern
• Medienbibliothek — Laden Sie Bilder und Dateien hoch und verwalten Sie sie
• Blog erstellen — Erstellen Sie einen kompletten Blog mit Kategorien und Tags
• Auf Cloudflare deployen — Bringen Sie Ihre Website in Produktion