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
-
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
-
É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
-
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é
- Définir la structure du contenu dans le code (
-
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)
-
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 :
-
Création de sites riches en contenu
- Blogs et sites personnels
- Sites de documentation
- Sites marketing
- Sites portfolio
-
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
-
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
-
É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 :
-
Collaboration en temps réel nécessaire
- Plusieurs utilisateurs éditant simultanément (style Google Docs)
- Utiliser plutôt Sanity, Contentful ou Firebase
-
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)
-
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 :
-
Initialiser TinaCMS :
npx @tinacms/cli@latest init- Lorsqu'il est demandé le répertoire des ressources publiques, entrez
public
- Lorsqu'il est demandé le répertoire des ressources publiques, entrez
-
Mettre à jour les scripts package.json :
{ "scripts": { "dev": "tinacms dev -c \"next dev\"", "build": "tinacms build && next build", "start": "tinacms build && next start" } } -
Définir les variables d'environnement :
# .env.local NEXT_PUBLIC_TINA_CLIENT_ID=your_client_id TINA_TOKEN=your_read_only_token -
Démarrer le serveur de développement :
npm run dev -
Accéder à l'interface d'administration :
http://localhost:3000/admin/index.html
Fichiers clés créés :
tina/config.ts- Configuration du schémaapp/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]].tsxau 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 :
-
Installer les dépendances :
npm install react@^19 react-dom@^19 tinacms -
Initialiser TinaCMS :
npx @tinacms/cli@latest init- Définir le répertoire des ressources publiques sur
public
- Définir le répertoire des ressources publiques sur
-
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 } }) -
Mettre à jour les scripts package.json :
{ "scripts": { "dev": "tinacms dev -c \"vite\"", "build": "tinacms build && vite build", "preview": "vite preview" } } -
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> -
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> ) } -
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 :
-
Utiliser le starter officiel (recommandé) :
npx create-tina-app@latest --template tina-astro-starterOu initialiser manuellement :
npx @tinacms/cli@latest init -
Mettre à jour les scripts package.json :
{ "scripts": { "dev": "tinacms dev -c \"astro dev\"", "build": "tinacms build && astro build", "preview": "astro preview" } } -
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 }) -
Édition visuelle (expérimentale) :
- Nécessite des composants React
- Utiliser
client:tinaDirectivepour l'édition interactive - L'édition visuelle complète est expérimentale en octobre 2025
-
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 :
-
Initialiser TinaCMS :
npx @tinacms/cli@latest init -
Configurer manuellement les scripts de build :
{ "scripts": { "dev": "tinacms dev -c \"<votre-commande-de-dev>\"", "build": "tinacms build && <votre-commande-de-build>" } } -
Interface d'administration :
- Créée automatiquement à
http://localhost:<port>/admin/index.html - Le port dépend de votre framework
- Créée automatiquement à
-
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
-
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'administrationpath: Chemin relatif du fichier par rapport à la racine du projetformat: Extension de fichier (par défaut 'md')fields: Définition de la structure du contenu
Référence des types de champs
| Type | Cas d'utilisation | Exemple |
|---|---|---|
string | Texte court (une seule ligne) | Titre, slug, nom d'auteur |
rich-text | Contenu long formaté | Corps du blog, contenu de page |
number | Valeurs numériques | Prix, quantité, note |
datetime | Valeurs de date/heure | Date de publication, heure d'événement |
boolean | Boutons vrai/faux | Statut brouillon, indicateur en vedette |
image | Téléchargements d'images | Image à la une, miniature, avatar |
reference | Lien vers un autre document | Auteur, catégorie, articles connexes |
object | Groupe de champs imbriqués | Mé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