Habilidad de TinaCMS
Habilidad completa para integrar TinaCMS en aplicaciones web modernas.
¿Qué es TinaCMS?
TinaCMS es un sistema de gestión de contenidos (CMS) headless, de código abierto y respaldado por Git, que permite a desarrolladores y creadores de contenido colaborar sin problemas en sitios web con gran cantidad de contenido.
Características Clave
-
Almacenamiento Respadaldo por Git
- El contenido se almacena como archivos Markdown, MDX o JSON en el repositorio Git
- Control de versiones completo e historial de cambios
- Sin dependencia del proveedor: el contenido vive en tu repositorio
-
Edición Visual/Contextual
- Experiencia de edición lado a lado
- Vista previa en vivo de los cambios mientras escribes
- Edición tipo WYSIWYG para contenido Markdown
-
Modelado de Contenido Basado en Esquemas
- Define la estructura del contenido en código (
tina/config.ts) - API GraphQL con seguridad de tipos generada automáticamente a partir del esquema
- Sistema de colecciones y campos para contenido organizado
- Define la estructura del contenido en código (
-
Despliegue Flexible
- TinaCloud: Servicio gestionado (el más fácil, nivel gratuito disponible)
- Autogestionado: Cloudflare Workers, Vercel Functions, Netlify Functions, AWS Lambda
- Múltiples opciones de autenticación (Auth.js, personalizada, desarrollo local)
-
Soporte de Frameworks
- Mejor: Next.js (App Router + Pages Router)
- Bueno: React, Astro (edición visual experimental), Gatsby, Hugo, Jekyll, Remix, 11ty
- Independiente del Framework: Funciona con cualquier framework (la edición visual está limitada a React)
Versiones Actuales
- tinacms: 2.9.0 (Septiembre 2025)
- @tinacms/cli: 1.11.0 (Octubre 2025)
- Soporte de React: 19.x (>=18.3.1 <20.0.0)
Cuándo Usar Esta Habilidad
✅ Usa TinaCMS Cuando:
-
Construyendo Sitios con Mucho Contenido
- Blogs y sitios web personales
- Sitios de documentación
- Sitios web de marketing
- Sitios de portafolio
-
Editores No Técnicos Necesitan Acceso
- Equipos de contenido sin conocimientos de codificación
- Equipos de marketing gestionando páginas
- Autores escribiendo publicaciones de blog
-
Se Desea un Flujo de Trabajo Basado en Git
- Quieres versionado de contenido a través de Git
- Necesitas revisión de contenido mediante pull requests
- Prefieres el contenido en el repositorio junto con el código
-
Se Requiere Edición Visual
- Los editores quieren ver los cambios en vivo
- Se prefiere una experiencia WYSIWYG
- Flujo de trabajo de edición lado a lado
❌ No Uses TinaCMS Cuando:
-
Se Necesita Colaboración en Tiempo Real
- Varios usuarios editando simultáneamente (estilo Google Docs)
- Usa Sanity, Contentful o Firebase en su lugar
-
Datos Altamente Dinámicos
- Catálogos de productos de comercio electrónico con cambios frecuentes de inventario
- Paneles de control en tiempo real
- Usa bases de datos tradicionales (D1, PostgreSQL) en su lugar
-
No se Necesita Gestión de Contenidos
- La aplicación está basada en datos, no en contenido
- El contenido codificado es suficiente
Patrones de Configuración por Framework
Usa el patrón de configuración apropiado según tu elección de framework.
1. Configuración de Next.js (Recomendado)
App Router (Next.js 13+)
Pasos:
-
Inicializa TinaCMS:
npx @tinacms/cli@latest init- Cuando se te solicite el directorio de activos públicos, ingresa
public
- Cuando se te solicite el directorio de activos públicos, ingresa
-
Actualiza los scripts de package.json:
{ "scripts": { "dev": "tinacms dev -c \"next dev\"", "build": "tinacms build && next build", "start": "tinacms build && next start" } } -
Establece las variables de entorno:
# .env.local NEXT_PUBLIC_TINA_CLIENT_ID=tu_client_id TINA_TOKEN=tu_token_de_solo_lectura -
Inicia el servidor de desarrollo:
npm run dev -
Accede a la interfaz de administración:
http://localhost:3000/admin/index.html
Archivos Clave Creados:
tina/config.ts- Configuración del esquemaapp/admin/[[...index]]/page.tsx- Ruta de la interfaz de administración (si se usa App Router)
Plantilla: Ver templates/nextjs/tina-config-app-router.ts
Pages Router (Next.js 12 y anteriores)
La configuración es idéntica, excepto que la ruta de administración es:
pages/admin/[[...index]].tsxen lugar del directorio app
Patrón de Obtención de Datos:
// pages/posts/[slug].tsx
import { client } from '../../tina/__generated__/client'
import { useTina } from 'tinacms/dist/react'
export default function BlogPost(props) {
// Hidrata para edición visual
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' }
}
Plantilla: Ver templates/nextjs/tina-config-pages-router.ts
2. Configuración de Vite + React
Pasos:
-
Instala las dependencias:
npm install react@^19 react-dom@^19 tinacms -
Inicializa TinaCMS:
npx @tinacms/cli@latest init- Establece el directorio de activos públicos en
public
- Establece el directorio de activos públicos en
-
Actualiza vite.config.ts:
import { defineConfig } from 'vite' import react from '@vitejs/plugin-react' export default defineConfig({ plugins: [react()], server: { port: 3000 // Puerto por defecto de TinaCMS } }) -
Actualiza los scripts de package.json:
{ "scripts": { "dev": "tinacms dev -c \"vite\"", "build": "tinacms build && vite build", "preview": "vite preview" } } -
Crea la interfaz de administración:
Opción A: Ruta manual (React Router)
// src/pages/Admin.tsx import TinaCMS from 'tinacms' export default function Admin() { return <div id="tina-admin" /> }Opción B: HTML directo
<!-- 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/[ruta-al-admin-de-tina]"></script> </body> </html> -
Usa el hook useTina para edición visual:
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>{/* renderizar cuerpo */}</div> </article> ) } -
Establece las variables de entorno:
# .env VITE_TINA_CLIENT_ID=tu_client_id VITE_TINA_TOKEN=tu_token_de_solo_lectura
Plantilla: Ver templates/vite-react/
3. Configuración de Astro
Pasos:
-
Usa el starter oficial (recomendado):
npx create-tina-app@latest --template tina-astro-starterO inicializa manualmente:
npx @tinacms/cli@latest init -
Actualiza los scripts de package.json:
{ "scripts": { "dev": "tinacms dev -c \"astro dev\"", "build": "tinacms build && astro build", "preview": "astro preview" } } -
Configura Astro:
// astro.config.mjs import { defineConfig } from 'astro/config' import react from '@astro/react' export default defineConfig({ integrations: [react()] // Requerido para la administración de Tina }) -
Edición visual (experimental):
- Requiere componentes React
- Usa
client:tinaDirectivepara edición interactiva - La edición visual completa es experimental a partir de octubre de 2025
-
Establece las variables de entorno:
# .env PUBLIC_TINA_CLIENT_ID=tu_client_id TINA_TOKEN=tu_token_de_solo_lectura
Mejor Para: Sitios estáticos centrados en contenido, documentación, blogs
Plantilla: Ver templates/astro/
4. Configuración Independiente del Framework
Aplica a: Hugo, Jekyll, Eleventy, Gatsby, Remix, o cualquier framework
Pasos:
-
Inicializa TinaCMS:
npx @tinacms/cli@latest init -
Configura manualmente los scripts de compilación:
{ "scripts": { "dev": "tinacms dev -c \"<tu-comando-de-desarrollo>\"", "build": "tinacms build && <tu-comando-de-compilación>" } } -
Interfaz de administración:
- Se crea automáticamente en
http://localhost:<puerto>/admin/index.html - El puerto depende de tu framework
- Se crea automáticamente en
-
Obtención de datos:
- Sin edición visual (solo barra lateral)
- El contenido se edita a través de la interfaz respaldada por Git
- Los cambios se guardan directamente en los archivos
-
Establece las variables de entorno:
TINA_CLIENT_ID=tu_client_id TINA_TOKEN=tu_token_de_solo_lectura
Limitaciones:
- Sin edición visual (funcionalidad solo de React)
- Se requiere integración manual
- Solo edición basada en barra lateral
Mejores Prácticas de Modelado de Esquemas
Define la estructura de tu contenido en tina/config.ts.
Estructura Básica de Configuración
import { defineConfig } from 'tinacms'
export default defineConfig({
// Configuración de rama
branch: process.env.GITHUB_BRANCH ||
process.env.VERCEL_GIT_COMMIT_REF ||
'main',
// Credenciales de TinaCloud (si se usa el servicio gestionado)
clientId: process.env.NEXT_PUBLIC_TINA_CLIENT_ID,
token: process.env.TINA_TOKEN,
// Configuración de compilación
build: {
outputFolder: 'admin',
publicFolder: 'public',
},
// Configuración de medios
media: {
tina: {
mediaRoot: '',
publicFolder: 'public',
},
},
// Esquema de contenido
schema: {
collections: [
// Define las colecciones aquí
],
},
})
Colecciones
Colección = Tipo de contenido + mapeo de directorio
{
name: 'post', // Singular, nombre interno (usado en la API)
label: 'Blog Posts', // Plural, nombre para mostrar (se muestra en la administración)
path: 'content/posts', // Directorio donde se almacenan los archivos
format: 'mdx', // Formato de archivo: md, mdx, markdown, json, yaml, toml
fields: [/* ... */] // Array de definiciones de campos
}
Propiedades Clave:
name: Identificador interno (solo alfanumérico y guiones bajos)label: Nombre legible para humanos para la interfaz de administraciónpath: Ruta del archivo relativa a la raíz del proyectoformat: Extensión de archivo (por defecto es 'md')fields: Definición de la estructura del contenido
Referencia de Tipos de Campos
| Tipo | Caso de Uso | Ejemplo |
|---|---|---|
string | Texto corto (una línea) | Título, slug, nombre del autor |
rich-text | Contenido formateado largo | Cuerpo del blog, contenido de la página |
number | Valores numéricos | Precio, cantidad, calificación |
datetime | Valores de fecha/hora | Fecha de publicación, hora del evento |
boolean | Alternativas verdadero/falso | Estado de borrador, indicador de destacado |
image | Cargas de imágenes | Imagen principal, miniatura, avatar |
reference | Enlace a otro documento | Autor, categoría, publicaciones relacionadas |
object | Grupo de campos anidados | Metadatos SEO, enlaces sociales |
Referencia completa: Ver references/field-types-reference.md
Plantillas de Colecciones
Colección de Publicaciones de Blog
{
name: 'post',
label: 'Blog Posts',
path: 'content/posts',
format: 'mdx',
fields: [
{
type: 'string',
name: 'title',
label: 'Title',
isTitle: true, // Se muestra en la lista de contenido
required: true
},
{
type: 'string',
name: 'excerpt',
label: 'Extracto',
ui: {
component: 'textarea' // Entrada de múltiples líneas
}
},
{
type: 'image',
name: 'coverImage',
label: 'Imagen de Portada'
},
{
type: 'datetime',
name: 'date',
label: 'Fecha de Publicación',
required: true
},
{
type: 'reference',
name: 'author',
label: 'Autor',
collections: ['author'] // Referencia a la colección de autores
},
{
type: 'boolean',
name: 'draft',
label: 'Borrador',
description: 'Si está marcado, la publicación no se publicará',
required: true
},
{
type: 'rich-text',
name: 'body',
label: 'Cuerpo',
isBody: true // Área de contenido principal
}
],
ui: {
router: ({ document }) => `/blog/${document._sys.filename}`
}
}
Plantilla: Ver templates/collections/blog-post.ts
Colección de Páginas de Documentación
{
name: 'doc',
label: 'Documentación',
path: 'content/docs',
format: 'mdx',
fields: [
{
type: 'string',
name: 'title',
label: 'Título',
isTitle: true,
required: true
},
{
type: 'string',
name: 'description',
label: 'Descripción',
ui: {
component: 'textarea'
}
},
{
type: 'number',
name: 'order',
label: 'Orden',
description: 'Orden de clasificación en la barra lateral'
},
{
type: 'rich-text',
name: 'body',
label: 'Cuerpo',
isBody: true,
templates: [
// Los componentes MDX se pueden definir aquí
]
}
],
ui: {
router: ({ document }) => {
const breadcrumbs = document._sys.breadcrumbs.join('/')
return `/docs/${breadcrumbs}`
}
}
}
Plantilla: Ver templates/collections/doc-page.ts
Colección de Autores (Destino de Referencia)
{
name: 'author',
label: 'Authors',
path: 'content/authors',
format: 'json', // Usa JSON para datos estructurados
fields: [
{
type: 'string',
name: 'name',
label: 'Nombre',
isTitle: true,
required: true
},
{
type: 'string',
name: 'email',
label: 'Email',
ui: {
validate: (value) => {
if (!value?.includes('@')) {
return 'Dirección de correo electrónico no válida'
}
}
}
},
{
type: 'image',
name: 'avatar',
label: 'Avatar'
}
]
}
Plantilla: Ver templates/collections/author.ts