Astro Frontend Editing Quickstart Speedrun

Dieses Dokument beschreibt die konkreten, praxisnahen Schritte zur Implementierung von Front End Editing für den Astro-basierten Prototyp von dev.chrswndrs.de. Ziel ist es, nicht-technischen Mitgliedern des Freundeskreis Großkarlbach e.V. ein direktes, visuelles Bearbeiten von Texten und Inhalten im Browser zu ermöglichen, während die performante und sichere Git-gestützte Static-Site-Architektur gewahrt bleibt.

---

1. Architekturentscheidung: TinaCMS

Für ein Astro-Projekt, das standardmäßig keine dynamische PHP/Datenbank-Umgebung wie TYPO3 besitzt, ist TinaCMS die optimale Wahl.

• Git-Backed Workflow: Änderungen, die Redakteure im Frontend vornehmen, werden als Git-Commits (Markdown/MDX-Dateien) direkt in das GitHub-Repository zurückgeschrieben.
• Echtzeit-Vorschau (Visual Editing): Redakteure sehen eine WYSIWYG-Oberfläche direkt auf der Website und bearbeiten Texte per Klick im Kontext.
• Zero-JS im Production-Build: Der visual Editor läuft über eine separate Route (/admin) und lädt Preview-JS nur für authentifizierte Redakteure. Die öffentliche Seite bleibt schlank und schnell.

---

2. Schritt-für-Schritt-Implementierung

Schritt 1: Initialisierung & Installation

Führe folgenden Befehl im Hauptverzeichnis des Astro-Projekts aus:

npx @tinacms/cli@latest init

Dieser Assistent installiert die benötigten Pakete (@tinacms/cli, tinacms) und erstellt die Verzeichnisstruktur unter tina/.

Schritt 2: Schema definieren (tina/config.ts)

Passe das Schema so an, dass es die vorhandene src/content/ Struktur spiegelt (z.B. für Feste, den Verein und allgemeine Seiten).

Datei: tina/config.ts

import { defineConfig } from "tinacms";
 
export default defineConfig({
  branch: "main",
  clientId: process.env.NEXT_PUBLIC_TINA_CLIENT_ID, // Aus Umgebungsvariablen geladen
  token: process.env.TINA_TOKEN,                    // Aus Umgebungsvariablen geladen
  build: {
    outputFolder: "admin",
    publicFolder: "public",
  },
  media: {
    tina: {
      mediaRoot: "images",
      publicFolder: "public",
    },
  },
  schema: {
    collections: [
      {
        name: "page",
        label: "Seiten",
        path: "src/content/pages",
        format: "mdx",
        fields: [
          {
            type: "string",
            name: "title",
            label: "Titel",
            isTitle: true,
            required: true,
          },
          {
            type: "rich-text",
            name: "body",
            label: "Inhalt",
            isBody: true,
          },
        ],
      },
      {
        name: "feste",
        label: "Feste & Veranstaltungen",
        path: "src/content/feste",
        format: "md",
        fields: [
          {
            type: "string",
            name: "title",
            label: "Veranstaltung",
            isTitle: true,
            required: true,
          },
          {
            type: "datetime",
            name: "date",
            label: "Datum",
          },
          {
            type: "string",
            name: "location",
            label: "Ort",
          },
          {
            type: "rich-text",
            name: "body",
            label: "Details",
            isBody: true,
          },
        ],
      },
    ],
  },
});

Schritt 3: Visual Editing im Frontend verkabeln

Damit TinaCMS weiß, welches DOM-Element zu welchem Markdown-Feld gehört, müssen im Astro-Layout bzw. den Seiten entsprechende data-tina-field-Attribute hinterlegt werden.

Beispiel für Daten-Query & Rendering:

---
// src/pages/[slug].astro
import { client } from "../../tina/__generated__/client";
 
const { slug } = Astro.params;
const response = await client.queries.page({ relativePath: `${slug}.mdx` });
---
 
<Layout title={response.data.page.title}>
  <!-- Das Attribut data-tina-field markiert das Element als editierbar -->
  <h1 data-tina-field={tinaField(response.data.page, 'title')}>
    {response.data.page.title}
  </h1>
  
  <div data-tina-field={tinaField(response.data.page, 'body')}>
    <TinaMarkdown content={response.data.page.body} />
  </div>
</Layout>

Schritt 4: Hybrid-Rendering & Live-Preview konfigurieren

Da Astro standardmäßig voll-statisch generiert, muss für den Preview-Modus (Live-Editor) serverseitiges Rendering (SSR) oder Hybrid-Rendering konfiguriert werden.

Datei: astro.config.mjs

import { defineConfig } from 'astro/config';
import react from '@astrojs/react'; // Benötigt für den TinaCMS-Editor-Wrapper
 
export default defineConfig({
  output: 'hybrid', // Ermöglicht SSR für Preview-Routen
  integrations: [react()],
});

Schritt 5: Cloud-Anbindung & Authentifizierung

1. Registriere das Projekt auf Tina Cloud.
2. Erstelle eine neue App und verknüpfe sie mit dem GitHub-Repository von grosskarlbach.com.
3. Trage die generierte NEXT_PUBLIC_TINA_CLIENT_ID und das TINA_TOKEN in die Environment-Secrets deines Hosting-Anbieters (z.B. Netlify) ein.
4. Lade berechtigte Redakteure in der Tina Cloud ein. Diese können sich nun über /admin auf der Website anmelden und visuelle Änderungen direkt in Git committen.

---

3. Verifikation

Lokaler Funktionstest

1. Starte die lokale Entwicklungsumgebung mit npm run dev.
2. Öffne http://localhost:4321/admin im Browser.
3. Klicke auf eine Seite, wähle einen Text aus und verändere ihn visuelle.
4. Klicke auf “Save”.
5. Erwartetes Ergebnis: Der Text ändert sich lokal in Echtzeit. Prüfe via git diff, ob die Datei (z.B. src/content/pages/home.mdx) mit der Änderung beschrieben wurde.

---

4. Annahmen & Risiken

• Voraussetzung: Inhalte müssen sauber in Markdown/MDX ausgelagert sein. Liegen Texte hardcoded in .astro-Dateien, können diese nicht von TinaCMS erfasst werden und müssen vorher in Content-Collections refaktoriert werden.
• Build-Zeiten: Jede Änderung löst einen GitHub/GitLab-Webhook aus, der ein neues Deployment auf dem Webserver (z. B. Hetzner) anstößt. Bei häufigen, kleinen Änderungen kann dies zu Warteschlangen führen.