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
-
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
-
Visuelle/Kontextbezogene Bearbeitung
- Bearbeitung im Side-by-Side-Modus
- Live-Vorschau der Änderungen während der Eingabe
- WYSIWYG-ähnliche Bearbeitung für Markdown-Inhalte
-
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
- Definiere die Inhaltsstruktur im Code (
-
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)
-
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:
-
Erstellung inhaltsreicher Seiten
- Blogs und persönliche Websites
- Dokumentationsseiten
- Marketing-Websites
- Portfolio-Seiten
-
Nicht-technische Redakteure benötigen Zugriff
- Content-Teams ohne Programmierkenntnisse
- Marketing-Teams, die Seiten verwalten
- Autoren, die Blogbeiträge schreiben
-
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
-
Visuelle Bearbeitung erforderlich
- Redakteure möchten Änderungen live sehen
- WYSIWYG-Erfahrung bevorzugt
- Side-by-Side-Bearbeitungs-Workflow
❌ Verwende TinaCMS nicht bei:
-
Echtzeit-Zusammenarbeit erforderlich
- Mehrere Benutzer bearbeiten gleichzeitig (wie Google Docs)
- Verwende stattdessen Sanity, Contentful oder Firebase
-
Hochdynamische Daten
- E-Commerce-Produktkataloge mit häufigen Lagerbestandsänderungen
- Echtzeit-Dashboards
- Verwende stattdessen traditionelle Datenbanken (D1, PostgreSQL)
-
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:
-
TinaCMS initialisieren:
npx @tinacms/cli@latest init- Wenn nach dem Verzeichnis für öffentliche Assets gefragt wird, gib
publicein
- Wenn nach dem Verzeichnis für öffentliche Assets gefragt wird, gib
-
package.json-Skripte aktualisieren:
{ "scripts": { "dev": "tinacms dev -c \"next dev\"", "build": "tinacms build && next build", "start": "tinacms build && next start" } } -
Umgebungsvariablen setzen:
# .env.local NEXT_PUBLIC_TINA_CLIENT_ID=your_client_id TINA_TOKEN=your_read_only_token -
Entwicklungsserver starten:
npm run dev -
Admin-Oberfläche aufrufen:
http://localhost:3000/admin/index.html
Erstellte Schlüsseldateien:
tina/config.ts- Schema-Konfigurationapp/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]].tsxanstelle 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:
-
Abhängigkeiten installieren:
npm install react@^19 react-dom@^19 tinacms -
TinaCMS initialisieren:
npx @tinacms/cli@latest init- Setze das Verzeichnis für öffentliche Assets auf
public
- Setze das Verzeichnis für öffentliche Assets auf
-
vite.config.ts aktualisieren:
import { defineConfig } from 'vite' import react from '@vitejs/plugin-react' export default defineConfig({ plugins: [react()], server: { port: 3000 // TinaCMS Standard } }) -
package.json-Skripte aktualisieren:
{ "scripts": { "dev": "tinacms dev -c \"vite\"", "build": "tinacms build && vite build", "preview": "vite preview" } } -
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> -
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> ) } -
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:
-
Offiziellen Starter verwenden (empfohlen):
npx create-tina-app@latest --template tina-astro-starterOder manuell initialisieren:
npx @tinacms/cli@latest init -
package.json-Skripte aktualisieren:
{ "scripts": { "dev": "tinacms dev -c \"astro dev\"", "build": "tinacms build && astro build", "preview": "astro preview" } } -
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 }) -
Visuelle Bearbeitung (experimentell):
- Erfordert React-Komponenten
- Verwende
client:tinaDirectivefür interaktive Bearbeitung - Vollständige visuelle Bearbeitung ist ab Oktober 2025 experimentell
-
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:
-
TinaCMS initialisieren:
npx @tinacms/cli@latest init -
Build-Skripte manuell konfigurieren:
{ "scripts": { "dev": "tinacms dev -c \"<dein-dev-befehl>\"", "build": "tinacms build && <dein-build-befehl>" } } -
Admin-Oberfläche:
- Wird automatisch erstellt unter
http://localhost:<port>/admin/index.html - Der Port hängt von deinem Framework ab
- Wird automatisch erstellt unter
-
Datenabruf:
- Keine visuelle Bearbeitung (nur Seitenleiste)
- Inhalte werden über die Git-gestützte Oberfläche bearbeitet
- Änderungen werden direkt in Dateien gespeichert
-
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ächepath: Dateipfad relativ zum Projektstammverzeichnisformat: Dateierweiterung (Standard ist 'md')fields: Definition der Inhaltsstruktur
Feldtypen-Referenz
| Typ | Anwendungsfall | Beispiel |
|---|---|---|
string | Kurzer Text (einzeilig) | Titel, Slug, Autorenname |
rich-text | Langer formatierter Inhalt | Blog-Text, Seiteninhalt |
number | Numerische Werte | Preis, Menge, Bewertung |
datetime | Datums-/Uhrzeitwerte | Veröffentlichungsdatum, Veranstaltungszeit |
boolean | Wahr/Falsch-Umschalter | Entwurfsstatus, Hervorhebungs-Flag |
image | Bild-Uploads | Hero-Bild, Vorschaubild, Avatar |
reference | Link zu einem anderen Dokument | Autor, Kategorie, verwandte Beiträge |
object | Gruppe verschachtelter Felder | SEO-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:
-
Tina-Cloud-Konto erstellen:
- Gehe zu app.tina.io
- Melde dich mit GitHub an
- Erstelle ein neues Projekt
-
Inhalts-Schema pushen:
npx tinacms push -
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:
| Plattform | Typ | URL-Struktur |
|---|---|---|
| Cloudflare Workers | Serverlos | *.workers.dev |
| Vercel Functions | Serverlos | *.vercel.app |
| Netlify Functions | Serverlos | *.netlify.app |
| AWS Lambda | Serverlos | *.lambda-url.amazonaws.com |
Einrichtung:
-
Backend-Modul installieren:
npm install @tinacms/datalayer -
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() }) -
Authentifizierung konfigurieren:
- Verwende
next-authfür Next.js - Passe benutzerdefinierte Anbieter für andere Frameworks an
- Siehe
references/self-hosted-auth.md
- Verwende
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:
- Stelle sicher, dass alle TinaCMS-Abhängigkeiten installiert sind:
npm install tinacms @tinacms/cli - Aktualisiere deine Node.js-Version auf 18 oder höher
- 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:
- Überprüfe, ob TinaCMS in
package.jsonaufgeführt ist:npm ls tinacms - Stelle sicher, dass die Admin-Route korrekt konfiguriert ist
- Für Next.js, überprüfe die Datei
app/admin/[[...index]]/page.tsx(App Router) oderpages/admin/[[...index]].tsx(Pages Router)
Docker-Bindungsprobleme
Problem: Error: listen EADDRINUSE :::3000 oder Bind: address already in use
Lösung:
- Verwende einen anderen Port:
tinacms dev -c "next dev -p 3001" - Stoppe andere Prozesse auf Port 3000:
lsof -ti:3000 | xargs kill - Docker-Port-Mapping anpassen:
# docker-compose.yml ports: - "3001:3000"
Debugging-Tipps
-
Umgebungsvariablen überprüfen:
echo $TINA_TOKEN echo $NEXT_PUBLIC_TINA_CLIENT_ID -
GraphQL-Queries testen:
npx tinacms graphql:playgroundÖffne
http://localhost:4001/graphqlin deinem Browser -
Admin-UI-Logs anzeigen: Öffne die Browser-Entwicklertools (F12) > Konsole
Nächste Schritte
- Offizielle Dokumentation: Vollständige API-Referenz und Anleitungen
- TinaCMS Discord: Community und Support
- Verwaltungsdashboard: Projektverwaltung und Analysen
- GitHub-Repository: Quellcode und Issues
Lizenz
TinaCMS ist unter der Apache-2.0-Lizenz lizenziert.