Communitygithub.com

ovachiever/droid-tings

Erstelle inhaltsreiche Seiten mit Git-basiertem TinaCMS. Bietet visuelle Bearbeitung und Content-Management für Blogs, Dokumentationen und Marketingseiten mit technisch nicht versierten Redakteuren.

Was ist droid-tings?

Dieser Skill befähigt dich, TinaCMS nahtlos in moderne Web-Frameworks wie Next.js, Vite+React und Astro zu integrieren und so ein leistungsstarkes Git-gestütztes Content-Management-System (CMS) zu nutzen. TinaCMS speichert Inhalte als Markdown-, MDX- oder JSON-Dateien direkt in deinem Git-Repository, was vollständige Versionskontrolle und Änderungshistorie ermöglicht und sich nahtlos in deinen Entwicklungs-Workflow einfügt. Der Skill bietet detaillierte Schritt-für-Schritt-Anleitungen für die Einrichtung, einschließlich der Schema-Definition, des Abrufs von Daten und der Konfiguration des visuellen Editors. Er unterstützt auch fortgeschrittene Anwendungsfälle wie die Bereitstellung auf Cloudflare Workers, die Fehlerbehebung von ESbuild-Kompilierungsfehlern, Modulauflösungsproblemen oder Docker-Bindungsproblemen sowie die Integration mit nicht-technischen Redakteuren über eine benutzerfreundliche Admin-Oberfläche.

Funktioniert mit✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ovachiever/droid-tings/tree/HEAD/skills/tinacms

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

TinaCMS Skill

Vollständiger Skill zur Integration von TinaCMS in moderne Webanwendungen.


Was ist TinaCMS?

TinaCMS ist ein quelloffenes, Git-gestütztes, kopfloses Content-Management-System (CMS), das Entwicklern und Content-Erstellern eine reibungslose Zusammenarbeit an inhaltsreichen Websites ermöglicht.

Hauptfunktionen

  1. Git-gestützte Speicherung

    • Inhalte werden als Markdown-, MDX- oder JSON-Dateien im Git-Repository gespeichert
    • Vollständige Versionskontrolle und Änderungshistorie
    • Keine Abhängigkeit von einem Anbieter – die Inhalte leben in deinem Repository
  2. Visuelle/Kontextbezogene Bearbeitung

    • Bearbeitung im Side-by-Side-Modus
    • Live-Vorschau der Änderungen während der Eingabe
    • WYSIWYG-ähnliche Bearbeitung für Markdown-Inhalte
  3. Schema-gesteuerte Inhaltsmodellierung

    • Definiere die Inhaltsstruktur im Code (tina/config.ts)
    • Typsichere GraphQL-API, automatisch aus dem Schema generiert
    • Collections- und Feldsystem für organisierte Inhalte
  4. Flexible Bereitstellung

    • TinaCloud: Verwalteter Dienst (am einfachsten, kostenloses Kontingent verfügbar)
    • Selbst gehostet: Cloudflare Workers, Vercel Functions, Netlify Functions, AWS Lambda
    • Mehrere Authentifizierungsoptionen (Auth.js, benutzerdefiniert, lokale Entwicklung)
  5. Framework-Unterstützung

    • Am besten: Next.js (App Router + Pages Router)
    • Gut: React, Astro (experimentelle visuelle Bearbeitung), Gatsby, Hugo, Jekyll, Remix, 11ty
    • Framework-agnostisch: Funktioniert mit jedem Framework (visuelle Bearbeitung auf React beschränkt)

Aktuelle Versionen

  • tinacms: 2.9.0 (September 2025)
  • @tinacms/cli: 1.11.0 (Oktober 2025)
  • React Support: 19.x (>=18.3.1 <20.0.0)

Wann dieser Skill verwendet werden sollte

✅ Verwende TinaCMS bei:

  1. Erstellung inhaltsreicher Seiten

    • Blogs und persönliche Websites
    • Dokumentationsseiten
    • Marketing-Websites
    • Portfolio-Seiten
  2. Nicht-technische Redakteure benötigen Zugriff

    • Content-Teams ohne Programmierkenntnisse
    • Marketing-Teams, die Seiten verwalten
    • Autoren, die Blogbeiträge schreiben
  3. Git-basierter Workflow gewünscht

    • Inhaltsversionierung über Git erwünscht
    • Inhaltsüberprüfung über Pull-Requests erforderlich
    • Bevorzugung von Inhalten im Repository zusammen mit dem Code
  4. Visuelle Bearbeitung erforderlich

    • Redakteure möchten Änderungen live sehen
    • WYSIWYG-Erfahrung bevorzugt
    • Side-by-Side-Bearbeitungs-Workflow

❌ Verwende TinaCMS nicht bei:

  1. Echtzeit-Zusammenarbeit erforderlich

    • Mehrere Benutzer bearbeiten gleichzeitig (wie Google Docs)
    • Verwende stattdessen Sanity, Contentful oder Firebase
  2. Hochdynamische Daten

    • E-Commerce-Produktkataloge mit häufigen Lagerbestandsänderungen
    • Echtzeit-Dashboards
    • Verwende stattdessen traditionelle Datenbanken (D1, PostgreSQL)
  3. Kein Content-Management erforderlich

    • Die Anwendung ist datengesteuert, nicht inhaltsgesteuert
    • Hartcodierte Inhalte sind ausreichend

Einrichtungsmuster nach Framework

Verwende das passende Einrichtungsmuster basierend auf deiner Framework-Wahl.

1. Next.js Einrichtung (Empfohlen)

App Router (Next.js 13+)

Schritte:

  1. TinaCMS initialisieren:

    npx @tinacms/cli@latest init
    
    • Wenn nach dem Verzeichnis für öffentliche Assets gefragt wird, gib public ein
  2. package.json-Skripte aktualisieren:

    {
      "scripts": {
        "dev": "tinacms dev -c \"next dev\"",
        "build": "tinacms build && next build",
        "start": "tinacms build && next start"
      }
    }
    
  3. Umgebungsvariablen setzen:

    # .env.local
    NEXT_PUBLIC_TINA_CLIENT_ID=your_client_id
    TINA_TOKEN=your_read_only_token
    
  4. Entwicklungsserver starten:

    npm run dev
    
  5. Admin-Oberfläche aufrufen:

    http://localhost:3000/admin/index.html
    

Erstellte Schlüsseldateien:

  • tina/config.ts - Schema-Konfiguration
  • app/admin/[[...index]]/page.tsx - Admin-UI-Route (bei Verwendung des App Router)

Vorlage: Siehe templates/nextjs/tina-config-app-router.ts


Pages Router (Next.js 12 und älter)

Die Einrichtung ist identisch, außer dass die Admin-Route ist:

  • pages/admin/[[...index]].tsx anstelle des App-Verzeichnisses

Datenabrufmuster:

// pages/posts/[slug].tsx
import { client } from '../../tina/__generated__/client'
import { useTina } from 'tinacms/dist/react'

export default function BlogPost(props) {
  // Für visuelle Bearbeitung hydratisieren
  const { data } = useTina({
    query: props.query,
    variables: props.variables,
    data: props.data
  })

  return (
    <article>
      <h1>{data.post.title}</h1>
      <div dangerouslySetInnerHTML={{ __html: data.post.body }} />
    </article>
  )
}

export async function getStaticProps({ params }) {
  const response = await client.queries.post({
    relativePath: `${params.slug}.md`
  })

  return {
    props: {
      data: response.data,
      query: response.query,
      variables: response.variables
    }
  }
}

export async function getStaticPaths() {
  const response = await client.queries.postConnection()
  const paths = response.data.postConnection.edges.map((edge) => ({
    params: { slug: edge.node._sys.filename }
  }))

  return { paths, fallback: 'blocking' }
}

Vorlage: Siehe templates/nextjs/tina-config-pages-router.ts


2. Vite + React Einrichtung

Schritte:

  1. Abhängigkeiten installieren:

    npm install react@^19 react-dom@^19 tinacms
    
  2. TinaCMS initialisieren:

    npx @tinacms/cli@latest init
    
    • Setze das Verzeichnis für öffentliche Assets auf public
  3. vite.config.ts aktualisieren:

    import { defineConfig } from 'vite'
    import react from '@vitejs/plugin-react'
    
    export default defineConfig({
      plugins: [react()],
      server: {
        port: 3000  // TinaCMS Standard
      }
    })
    
  4. package.json-Skripte aktualisieren:

    {
      "scripts": {
        "dev": "tinacms dev -c \"vite\"",
        "build": "tinacms build && vite build",
        "preview": "vite preview"
      }
    }
    
  5. Admin-Oberfläche erstellen:

    Option A: Manuelle Route (React Router)

    // src/pages/Admin.tsx
    import TinaCMS from 'tinacms'
    
    export default function Admin() {
      return <div id="tina-admin" />
    }
    

    Option B: Direktes HTML

    <!-- public/admin/index.html -->
    <!DOCTYPE html>
    <html>
      <head>
        <meta charset="utf-8" />
        <title>Tina CMS</title>
        <meta name="viewport" content="width=device-width, initial-scale=1" />
      </head>
      <body>
        <div id="root"></div>
        <script type="module" src="/@fs/[path-to-tina-admin]"></script>
      </body>
    </html>
    
  6. useTina-Hook für visuelle Bearbeitung verwenden:

    import { useTina } from 'tinacms/dist/react'
    import { client } from '../tina/__generated__/client'
    
    function BlogPost({ initialData }) {
      const { data } = useTina({
        query: initialData.query,
        variables: initialData.variables,
        data: initialData.data
      })
    
      return (
        <article>
          <h1>{data.post.title}</h1>
          <div>{/* Inhalt rendern */}</div>
        </article>
      )
    }
    
  7. Umgebungsvariablen setzen:

    # .env
    VITE_TINA_CLIENT_ID=your_client_id
    VITE_TINA_TOKEN=your_read_only_token
    

Vorlage: Siehe templates/vite-react/


3. Astro Einrichtung

Schritte:

  1. Offiziellen Starter verwenden (empfohlen):

    npx create-tina-app@latest --template tina-astro-starter
    

    Oder manuell initialisieren:

    npx @tinacms/cli@latest init
    
  2. package.json-Skripte aktualisieren:

    {
      "scripts": {
        "dev": "tinacms dev -c \"astro dev\"",
        "build": "tinacms build && astro build",
        "preview": "astro preview"
      }
    }
    
  3. Astro konfigurieren:

    // astro.config.mjs
    import { defineConfig } from 'astro/config'
    import react from '@astro/react'
    
    export default defineConfig({
      integrations: [react()]  // Für Tina-Admin erforderlich
    })
    
  4. Visuelle Bearbeitung (experimentell):

    • Erfordert React-Komponenten
    • Verwende client:tinaDirective für interaktive Bearbeitung
    • Vollständige visuelle Bearbeitung ist ab Oktober 2025 experimentell
  5. Umgebungsvariablen setzen:

    # .env
    PUBLIC_TINA_CLIENT_ID=your_client_id
    TINA_TOKEN=your_read_only_token
    

Am besten geeignet für: Inhaltsorientierte statische Seiten, Dokumentationen, Blogs

Vorlage: Siehe templates/astro/


4. Framework-agnostische Einrichtung

Gilt für: Hugo, Jekyll, Eleventy, Gatsby, Remix oder jedes Framework

Schritte:

  1. TinaCMS initialisieren:

    npx @tinacms/cli@latest init
    
  2. Build-Skripte manuell konfigurieren:

    {
      "scripts": {
        "dev": "tinacms dev -c \"<dein-dev-befehl>\"",
        "build": "tinacms build && <dein-build-befehl>"
      }
    }
    
  3. Admin-Oberfläche:

    • Wird automatisch erstellt unter http://localhost:<port>/admin/index.html
    • Der Port hängt von deinem Framework ab
  4. Datenabruf:

    • Keine visuelle Bearbeitung (nur Seitenleiste)
    • Inhalte werden über die Git-gestützte Oberfläche bearbeitet
    • Änderungen werden direkt in Dateien gespeichert
  5. Umgebungsvariablen setzen:

    TINA_CLIENT_ID=your_client_id
    TINA_TOKEN=your_read_only_token
    

Einschränkungen:

  • Keine visuelle Bearbeitung (nur React-Funktion)
  • Manuelle Integration erforderlich
  • Nur seitenleistenbasierte Bearbeitung

Best Practices für Schema-Modellierung

Definiere deine Inhaltsstruktur in tina/config.ts.

Grundlegende Konfigurationsstruktur

import { defineConfig } from 'tinacms'

export default defineConfig({
  // Branch-Konfiguration
  branch: process.env.GITHUB_BRANCH ||
          process.env.VERCEL_GIT_COMMIT_REF ||
          'main',

  // TinaCloud-Anmeldeinformationen (bei Verwendung des verwalteten Dienstes)
  clientId: process.env.NEXT_PUBLIC_TINA_CLIENT_ID,
  token: process.env.TINA_TOKEN,

  // Build-Konfiguration
  build: {
    outputFolder: 'admin',
    publicFolder: 'public',
  },

  // Medienkonfiguration
  media: {
    tina: {
      mediaRoot: '',
      publicFolder: 'public',
    },
  },

  // Inhalts-Schema
  schema: {
    collections: [
      // Hier Collections definieren
    ],
  },
})

Collections

Collection = Inhaltstyp + Verzeichniszuordnung

{
  name: 'post',           // Singular, interner Name (in der API verwendet)
  label: 'Blog Posts',    // Plural, Anzeigename (im Admin angezeigt)
  path: 'content/posts',  // Verzeichnis, in dem die Dateien gespeichert werden
  format: 'mdx',          // Dateiformat: md, mdx, markdown, json, yaml, toml
  fields: [/* ... */]     // Array von Felddefinitionen
}

Wichtige Eigenschaften:

  • name: Interner Bezeichner (nur alphanumerische Zeichen und Unterstriche)
  • label: Für Menschen lesbarer Name für die Admin-Oberfläche
  • path: Dateipfad relativ zum Projektstammverzeichnis
  • format: Dateierweiterung (Standard ist 'md')
  • fields: Definition der Inhaltsstruktur

Feldtypen-Referenz

TypAnwendungsfallBeispiel
stringKurzer Text (einzeilig)Titel, Slug, Autorenname
rich-textLanger formatierter InhaltBlog-Text, Seiteninhalt
numberNumerische WertePreis, Menge, Bewertung
datetimeDatums-/UhrzeitwerteVeröffentlichungsdatum, Veranstaltungszeit
booleanWahr/Falsch-UmschalterEntwurfsstatus, Hervorhebungs-Flag
imageBild-UploadsHero-Bild, Vorschaubild, Avatar
referenceLink zu einem anderen DokumentAutor, Kategorie, verwandte Beiträge
objectGruppe verschachtelter FelderSEO-Metadaten, soziale Links

Vollständige Referenz: Siehe references/field-types-reference.md


Collection-Vorlagen

Blogbeitrag-Collection

{
  name: 'post',
  label: 'Blog Posts',
  path: 'content/posts',
  format: 'mdx',
  fields: [
    {
      type: 'string',
      name: 'title',
      label: 'Title',
      isTitle: true,  // Wird in der Inhaltsliste angezeigt
      required: true
    },
    {
      type: 'string',
      name: 'excerpt',
      label: 'Excerpt',
      ui: {
        component: 'textarea'  // Mehrzeilige Eingabe
      }
    },
    {
      type: 'image',
      name: 'coverImage',
      label: 'Cover Image'
    },
    {
      type: 'datetime',
      name: 'date',
      label: 'Published Date',
      required: true
    },
    {
      type: 'reference',
      name: 'author',
      label: 'Author',
      collections: ['author']  // Referenziert die Autoren-Collection
    },
    {
      type: 'boolean',
      name: 'draft',
      label: 'Draft',
      description: 'If checked, post will not be published',
      required: true
    },
    {
      type: 'rich-text',
      name: 'body',
      label: 'Body',
      isBody: true  // Hauptinhaltsbereich
    }
  ],
  ui: {
    router: ({ document }) => `/blog/${document._sys.filename}`
  }
}

Vorlage: Siehe templates/collections/blog-post.ts


Dokumentationsseiten-Collection

{
  name: 'doc',
  label: 'Documentation',
  path: 'content/docs',
  format: 'mdx',
  fields: [
    {
      type: 'string',
      name: 'title',
      label: 'Title',
      isTitle: true,
      required: true
    },
    {
      type: 'string',
      name: 'description',
      label: 'Description',
      ui: {
        component: 'textarea'
      }
    },
    {
      type: 'number',
      name: 'order',
      label: 'Order',
      description: 'Sort order in sidebar'
    },
    {
      type: 'rich-text',
      name: 'body',
      label: 'Body',
      isBody: true,
      templates: [
        // MDX-Komponenten können hier definiert werden
      ]
    }
  ],
  ui: {
    router: ({ document }) => {
      const breadcrumbs = document._sys.breadcrumbs.join('/')
      return `/docs/${breadcrumbs}`
    }
  }
}

Vorlage: Siehe templates/collections/doc-page.ts


Autoren-Collection (Referenzziel)

{
  name: 'author',
  label: 'Authors',
  path: 'content/authors',
  format: 'json',  // JSON für strukturierte Daten verwenden
  fields: [
    {
      type: 'string',
      name: 'name',
      label: 'Name',
      isTitle: true,
      required: true
    },
    {
      type: 'string',
      name: 'email',
      label: 'Email',
      ui: {
        validate: (value) => {
          if (!value?.includes('@')) {
            return 'Invalid email address'
          }
        }
      }
    },
    /* ... */
  ]
}

Vorlage: Siehe templates/collections/author.ts


Administrativer Setup

TinaCloud (Empfohlen für die meisten Projekte)

Bereitstellungsschritte:

  1. Tina-Cloud-Konto erstellen:

    • Gehe zu app.tina.io
    • Melde dich mit GitHub an
    • Erstelle ein neues Projekt
  2. Inhalts-Schema pushen:

    npx tinacms push
    
  3. Build-Befehl aktualisieren:

    {
      "scripts": {
        "build": "tinacms build && next build"
      }
    }
    

Wann verwenden:

  • Schnellste Einrichtung
  • Beinhaltet Authentifizierung
  • Automatische GraphQL-Generierung
  • Kostenloses Kontingent verfügbar

Selbst gehostete Bereitstellung

Optionen:

PlattformTypURL-Struktur
Cloudflare WorkersServerlos*.workers.dev
Vercel FunctionsServerlos*.vercel.app
Netlify FunctionsServerlos*.netlify.app
AWS LambdaServerlos*.lambda-url.amazonaws.com

Einrichtung:

  1. Backend-Modul installieren:

    npm install @tinacms/datalayer
    
  2. Datenbankschema konfigurieren:

    TinaForest (empfohlen - Git-Datenbank):

    import { TinaForest } from '@tinacms/datalayer'
    
    const database = new TinaForest({
      branch: process.env.GITHUB_BRANCH,
      owner: process.env.GITHUB_OWNER,
      repo: process.env.GITHUB_REPO,
    })
    

    Lokale Dateien (Git-Klon):

    import { FilesystemDatabase } from '@tinacms/datalayer'
    
    const database = new FilesystemDatabase({
      rootPath: process.cwd()
    })
    
  3. Authentifizierung konfigurieren:

    • Verwende next-auth für Next.js
    • Passe benutzerdefinierte Anbieter für andere Frameworks an
    • Siehe references/self-hosted-auth.md

Wann verwenden:

  • Vollständige Kontrolle über die Bereitstellung
  • Keine Abhängigkeit von Drittanbieter-Diensten
  • Benötigt DevOps-Kenntnisse für Einrichtung und Wartung

Fehlerbehebung

Häufige Probleme

ESbuild-Kompilierungsfehler

Problem: Build failed with 1 error: ERROR: Could not resolve "@tinacms/..."

Lösung:

  1. Stelle sicher, dass alle TinaCMS-Abhängigkeiten installiert sind:
    npm install tinacms @tinacms/cli
    
  2. Aktualisiere deine Node.js-Version auf 18 oder höher
  3. Leere den npm-Cache und installiere neu:
    npm cache clean --force
    rm -rf node_modules package-lock.json
    npm install
    

Modulauflösungsprobleme

Problem: Module not found: Can't resolve 'tinacms/...'

Lösung:

  1. Überprüfe, ob TinaCMS in package.json aufgeführt ist: npm ls tinacms
  2. Stelle sicher, dass die Admin-Route korrekt konfiguriert ist
  3. Für Next.js, überprüfe die Datei app/admin/[[...index]]/page.tsx (App Router) oder pages/admin/[[...index]].tsx (Pages Router)

Docker-Bindungsprobleme

Problem: Error: listen EADDRINUSE :::3000 oder Bind: address already in use

Lösung:

  1. Verwende einen anderen Port: tinacms dev -c "next dev -p 3001"
  2. Stoppe andere Prozesse auf Port 3000: lsof -ti:3000 | xargs kill
  3. Docker-Port-Mapping anpassen:
    # docker-compose.yml
    ports:
      - "3001:3000"
    

Debugging-Tipps

  1. Umgebungsvariablen überprüfen:

    echo $TINA_TOKEN
    echo $NEXT_PUBLIC_TINA_CLIENT_ID
    
  2. GraphQL-Queries testen:

    npx tinacms graphql:playground
    

    Öffne http://localhost:4001/graphql in deinem Browser

  3. Admin-UI-Logs anzeigen: Öffne die Browser-Entwicklertools (F12) > Konsole


Nächste Schritte


Lizenz

TinaCMS ist unter der Apache-2.0-Lizenz lizenziert.

Individual skills in this repo

This repo contains 3 individual skills — each has its own dedicated page.

Verwandte Skills