Communitygithub.com

ovachiever/droid-tings

Construisez des sites riches en contenu avec TinaCMS, piloté par Git. Offre une édition visuelle et une gestion de contenu pour les blogs, documentations et sites marketing avec des éditeurs non techniques.

Qu'est-ce que droid-tings ?

Cette compétence fournit un guide complet pour intégrer TinaCMS, un CMS headless open-source et basé sur Git, dans des applications web modernes. Elle est idéale pour les développeurs créant des sites axés sur le contenu (blogs, documentations, sites marketing) où des éditeurs non techniques collaborent à la gestion éditoriale. La compétence couvre l'installation et la configuration pour plusieurs frameworks, avec un support optimal pour Next.js (App Router et Pages Router), ainsi que pour Vite+React, Astro (édition visuelle expérimentale), et d'autres frameworks comme Hugo ou Jekyll (par l'approche agnostique). Elle détaille l'éditeur visuel et contextuel, le stockage par Git (fichiers Markdown, MDX ou JSON), la modélisation de contenu pilotée par schéma (tina/config.ts), et le déploiement flexible (TinaCloud géré ou auto-hébergé sur Cloudflare Workers, Vercel Functions, etc.). Elle inclut des instructions pratiques comme la configuration des variables d'environnement, les scripts de build, et des exemples de code pour les modèles Next.js et Vite+React. En résumé, c'est une ressource clé pour implémenter une solution CMS moderne, évolutive et versionnée, idéale pour des flux de travail collaboratifs non techniques.

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

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Compétence TinaCMS

Compétence complète pour intégrer TinaCMS dans des applications web modernes.


Qu'est-ce que TinaCMS ?

TinaCMS est un système de gestion de contenu (CMS) headless open-source, basé sur Git, qui permet aux développeurs et aux créateurs de contenu de collaborer de manière transparente sur des sites web riches en contenu.

Fonctionnalités clés

  1. Stockage basé sur Git

    • Contenu stocké sous forme de fichiers Markdown, MDX ou JSON dans le dépôt Git
    • Contrôle de version complet et historique des modifications
    • Pas de dépendance à un fournisseur - le contenu réside dans votre dépôt
  2. Édition visuelle/contextuelle

    • Expérience d'édition côte à côte
    • Aperçu en direct des modifications au fur et à mesure de la frappe
    • Édition de type WYSIWYG pour le contenu Markdown
  3. Modélisation de contenu pilotée par schéma

    • Définir la structure du contenu dans le code (tina/config.ts)
    • API GraphQL typée générée automatiquement à partir du schéma
    • Système de collections et de champs pour un contenu organisé
  4. Déploiement flexible

    • TinaCloud : Service géré (le plus simple, niveau gratuit disponible)
    • Auto-hébergé : Cloudflare Workers, Vercel Functions, Netlify Functions, AWS Lambda
    • Multiples options d'authentification (Auth.js, personnalisé, développement local)
  5. Support des frameworks

    • Meilleur : Next.js (App Router + Pages Router)
    • Bon : React, Astro (édition visuelle expérimentale), Gatsby, Hugo, Jekyll, Remix, 11ty
    • Agnostique : Fonctionne avec n'importe quel framework (édition visuelle limitée à React)

Versions actuelles

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

Quand utiliser cette compétence

✅ Utiliser TinaCMS quand :

  1. Création de sites riches en contenu

    • Blogs et sites personnels
    • Sites de documentation
    • Sites marketing
    • Sites portfolio
  2. Accès nécessaire pour les éditeurs non techniques

    • Équipes de contenu sans connaissance en programmation
    • Équipes marketing gérant des pages
    • Auteurs rédigeant des articles de blog
  3. Flux de travail basé sur Git souhaité

    • Versionnement du contenu via Git
    • Révision du contenu par pull requests
    • Préférence pour du contenu dans le dépôt avec le code
  4. Édition visuelle requise

    • Les éditeurs veulent voir les modifications en direct
    • Expérience WYSIWYG préférée
    • Flux de travail d'édition côte à côte

❌ Ne pas utiliser TinaCMS quand :

  1. Collaboration en temps réel nécessaire

    • Plusieurs utilisateurs éditant simultanément (style Google Docs)
    • Utiliser plutôt Sanity, Contentful ou Firebase
  2. Données hautement dynamiques

    • Catalogues de produits e-commerce avec des changements fréquents de stock
    • Tableaux de bord en temps réel
    • Utiliser plutôt des bases de données traditionnelles (D1, PostgreSQL)
  3. Aucune gestion de contenu nécessaire

    • L'application est pilotée par les données, pas par le contenu
    • Le contenu codé en dur est suffisant

Modèles de configuration par framework

Utilisez le modèle de configuration approprié en fonction de votre choix de framework.

1. Configuration Next.js (Recommandé)

App Router (Next.js 13+)

Étapes :

  1. Initialiser TinaCMS :

    npx @tinacms/cli@latest init
    
    • Lorsqu'il est demandé le répertoire des ressources publiques, entrez public
  2. Mettre à jour les scripts package.json :

    {
      "scripts": {
        "dev": "tinacms dev -c \"next dev\"",
        "build": "tinacms build && next build",
        "start": "tinacms build && next start"
      }
    }
    
  3. Définir les variables d'environnement :

    # .env.local
    NEXT_PUBLIC_TINA_CLIENT_ID=your_client_id
    TINA_TOKEN=your_read_only_token
    
  4. Démarrer le serveur de développement :

    npm run dev
    
  5. Accéder à l'interface d'administration :

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

Fichiers clés créés :

  • tina/config.ts - Configuration du schéma
  • app/admin/[[...index]]/page.tsx - Route de l'interface d'administration (si App Router)

Modèle : Voir templates/nextjs/tina-config-app-router.ts


Pages Router (Next.js 12 et versions antérieures)

La configuration est identique, sauf que la route d'administration est :

  • pages/admin/[[...index]].tsx au lieu du répertoire app

Schéma de récupération des données :

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

export default function BlogPost(props) {
  // Hydratation pour l'édition visuelle
  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' }
}

Modèle : Voir templates/nextjs/tina-config-pages-router.ts


2. Configuration Vite + React

Étapes :

  1. Installer les dépendances :

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

    npx @tinacms/cli@latest init
    
    • Définir le répertoire des ressources publiques sur public
  3. Mettre à jour vite.config.ts :

    import { defineConfig } from 'vite'
    import react from '@vitejs/plugin-react'
    
    export default defineConfig({
      plugins: [react()],
      server: {
        port: 3000  // Valeur par défaut de TinaCMS
      }
    })
    
  4. Mettre à jour les scripts package.json :

    {
      "scripts": {
        "dev": "tinacms dev -c \"vite\"",
        "build": "tinacms build && vite build",
        "preview": "vite preview"
      }
    }
    
  5. Créer l'interface d'administration :

    Option A : Route manuelle (React Router)

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

    Option B : HTML direct

    <!-- 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/[chemin-vers-tina-admin]"></script>
      </body>
    </html>
    
  6. Utiliser le hook useTina pour l'édition visuelle :

    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>{/* afficher le corps */}</div>
        </article>
      )
    }
    
  7. Définir les variables d'environnement :

    # .env
    VITE_TINA_CLIENT_ID=your_client_id
    VITE_TINA_TOKEN=your_read_only_token
    

Modèle : Voir templates/vite-react/


3. Configuration Astro

Étapes :

  1. Utiliser le starter officiel (recommandé) :

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

    Ou initialiser manuellement :

    npx @tinacms/cli@latest init
    
  2. Mettre à jour les scripts package.json :

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

    // astro.config.mjs
    import { defineConfig } from 'astro/config'
    import react from '@astro/react'
    
    export default defineConfig({
      integrations: [react()]  // Requis pour l'administration Tina
    })
    
  4. Édition visuelle (expérimentale) :

    • Nécessite des composants React
    • Utiliser client:tinaDirective pour l'édition interactive
    • L'édition visuelle complète est expérimentale en octobre 2025
  5. Définir les variables d'environnement :

    # .env
    PUBLIC_TINA_CLIENT_ID=your_client_id
    TINA_TOKEN=your_read_only_token
    

Idéal pour : Sites statiques axés sur le contenu, documentation, blogs

Modèle : Voir templates/astro/


4. Configuration agnostique du framework

S'applique à : Hugo, Jekyll, Eleventy, Gatsby, Remix, ou tout autre framework

Étapes :

  1. Initialiser TinaCMS :

    npx @tinacms/cli@latest init
    
  2. Configurer manuellement les scripts de build :

    {
      "scripts": {
        "dev": "tinacms dev -c \"<votre-commande-de-dev>\"",
        "build": "tinacms build && <votre-commande-de-build>"
      }
    }
    
  3. Interface d'administration :

    • Créée automatiquement à http://localhost:<port>/admin/index.html
    • Le port dépend de votre framework
  4. Récupération des données :

    • Pas d'édition visuelle (barre latérale uniquement)
    • Contenu édité via l'interface basée sur Git
    • Les modifications sont enregistrées directement dans les fichiers
  5. Définir les variables d'environnement :

    TINA_CLIENT_ID=your_client_id
    TINA_TOKEN=your_read_only_token
    

Limites :

  • Pas d'édition visuelle (fonctionnalité React uniquement)
  • Intégration manuelle requise
  • Édition uniquement par barre latérale

Bonnes pratiques de modélisation des schémas

Définissez votre structure de contenu dans tina/config.ts.

Structure de base de la configuration

import { defineConfig } from 'tinacms'

export default defineConfig({
  // Configuration de la branche
  branch: process.env.GITHUB_BRANCH ||
          process.env.VERCEL_GIT_COMMIT_REF ||
          'main',

  // Identifiants TinaCloud (si service géré)
  clientId: process.env.NEXT_PUBLIC_TINA_CLIENT_ID,
  token: process.env.TINA_TOKEN,

  // Configuration de build
  build: {
    outputFolder: 'admin',
    publicFolder: 'public',
  },

  // Configuration des médias
  media: {
    tina: {
      mediaRoot: '',
      publicFolder: 'public',
    },
  },

  // Schéma de contenu
  schema: {
    collections: [
      // Définir les collections ici
    ],
  },
})

Collections

Collection = Type de contenu + mappage de répertoire

{
  name: 'post',           // Nom interne, singulier (utilisé dans l'API)
  label: 'Articles de blog',    // Nom d'affichage, pluriel (affiché dans l'administration)
  path: 'content/posts',  // Répertoire où les fichiers sont stockés
  format: 'mdx',          // Format de fichier : md, mdx, markdown, json, yaml, toml
  fields: [/* ... */]     // Tableau de définitions de champs
}

Propriétés clés :

  • name : Identifiant interne (alphanumérique et underscores uniquement)
  • label : Nom lisible par l'homme pour l'interface d'administration
  • path : Chemin relatif du fichier par rapport à la racine du projet
  • format : Extension de fichier (par défaut 'md')
  • fields : Définition de la structure du contenu

Référence des types de champs

TypeCas d'utilisationExemple
stringTexte court (une seule ligne)Titre, slug, nom d'auteur
rich-textContenu long formatéCorps du blog, contenu de page
numberValeurs numériquesPrix, quantité, note
datetimeValeurs de date/heureDate de publication, heure d'événement
booleanBoutons vrai/fauxStatut brouillon, indicateur en vedette
imageTéléchargements d'imagesImage à la une, miniature, avatar
referenceLien vers un autre documentAuteur, catégorie, articles connexes
objectGroupe de champs imbriquésMétadonnées SEO, liens sociaux

Référence complète : Voir references/field-types-reference.md


Modèles de collection

Collection d'articles de blog

{
  name: 'post',
  label: 'Articles de blog',
  path: 'content/posts',
  format: 'mdx',
  fields: [
    {
      type: 'string',
      name: 'title',
      label: 'Titre',
      isTitle: true,  // S'affiche dans la liste de contenu
      required: true
    },
    {
      type: 'string',
      name: 'excerpt',
      label: 'Extrait',
      ui: {
        component: 'textarea'  // Saisie multi-ligne
      }
    },
    {
      type: 'image',
      name: 'coverImage',
      label: 'Image de couverture'
    },
    {
      type: 'datetime',
      name: 'date',
      label: 'Date de publication',
      required: true
    },
    {
      type: 'reference',
      name: 'author',
      label: 'Auteur',
      collections: ['author']  // Référence la collection d'auteurs
    },
    {
      type: 'boolean',
      name: 'draft',
      label: 'Brouillon',
      description: 'Si coché, l\'article ne sera pas publié',
      required: true
    },
    {
      type: 'rich-text',
      name: 'body',
      label: 'Corps',
      isBody: true  // Zone de contenu principal
    }
  ],
  ui: {
    router: ({ document }) => `/blog/${document._sys.filename}`
  }
}

Modèle : Voir templates/collections/blog-post.ts


Collection de pages de documentation

{
  name: 'doc',
  label: 'Documentation',
  path: 'content/docs',
  format: 'mdx',
  fields: [
    {
      type: 'string',
      name: 'title',
      label: 'Titre',
      isTitle: true,
      required: true
    },
    {
      type: 'string',
      name: 'description',
      label: 'Description',
      ui: {
        component: 'textarea'
      }
    },
    {
      type: 'number',
      name: 'order',
      label: 'Ordre',
      description: 'Ordre de tri dans la barre latérale'
    },
    {
      type: 'rich-text',
      name: 'body',
      label: 'Corps',
      isBody: true,
      templates: [
        // Les composants MDX peuvent être définis ici
      ]
    }
  ],
  ui: {
    router: ({ document }) => {
      const breadcrumbs = document._sys.breadcrumbs.join('/')
      return `/docs/${breadcrumbs}`
    }
  }
}

Modèle : Voir templates/collections/doc-page.ts


Collection d'auteurs (cible de référence)

{
  name: 'author',
  label: 'Auteurs',
  path: 'content/authors',
  format: 'json',  // Utiliser JSON pour les données structurées
  fields: [
    {
      type: 'string',
      name: 'name',
      label: 'Nom',
      isTitle: true,
      required: true
    },
    {
      type: 'string',
      name: 'email',
      label: 'Email',
      ui: {
        validate: (value) => {
          if (!value?.includes('@')) {
            return 'Adresse email invalide'
          }
        }
      }
    },
    {
      type: 'boolean',
      name: 'draft',
      label: 'Brouillon',
      required: true
    },
    {
      type: 'rich-text',
      name: 'body',
      label: 'Corps',
      isBody: true
    }
  ],
  ui: {
    router: ({ document }) => `/authors/${document._sys.filename}`
  }
}

Modèle : Voir templates/collections/author.ts

Individual skills in this repo

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

Skills associés