Communitygithub.com

ovachiever/droid-tings

Crea sitios con mucho contenido usando TinaCMS con respaldo de Git. Proporciona edición visual y gestión de contenidos para blogs, documentación y sitios de marketing con editores no técnicos.

¿Qué es droid-tings?

Esta habilidad integra **TinaCMS**, un sistema de gestión de contenidos (CMS) de código abierto respaldado por Git, en aplicaciones web modernas como Next.js, Vite+React y Astro. Es ideal para desarrolladores que necesitan ofrecer a editores no técnicos una experiencia de edición visual y contextual (WYSIWYG), manteniendo todo el contenido versionado en un repositorio Git. La habilidad proporciona guías completas de configuración para diferentes frameworks, cubre el modelado de esquemas de contenido (colecciones y campos), y detalla opciones de despliegue tanto autogestionado (Cloudflare Workers, Vercel Functions, AWS Lambda) como a través del servicio gestionado TinaCloud. También incluye resolución de problemas comunes como errores de compilación ESbuild, problemas de resolución de módulos o enlaces de Docker, lo que la convierte en un recurso integral para cualquier desarrollador que desee implementar un CMS Git-backed con capacidades de edición visual.

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

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

  1. 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
  2. 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
  3. 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
  4. 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)
  5. 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:

  1. Construyendo Sitios con Mucho Contenido

    • Blogs y sitios web personales
    • Sitios de documentación
    • Sitios web de marketing
    • Sitios de portafolio
  2. 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
  3. 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
  4. 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:

  1. Se Necesita Colaboración en Tiempo Real

    • Varios usuarios editando simultáneamente (estilo Google Docs)
    • Usa Sanity, Contentful o Firebase en su lugar
  2. 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
  3. 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:

  1. Inicializa TinaCMS:

    npx @tinacms/cli@latest init
    
    • Cuando se te solicite el directorio de activos públicos, ingresa public
  2. Actualiza los scripts de package.json:

    {
      "scripts": {
        "dev": "tinacms dev -c \"next dev\"",
        "build": "tinacms build && next build",
        "start": "tinacms build && next start"
      }
    }
    
  3. Establece las variables de entorno:

    # .env.local
    NEXT_PUBLIC_TINA_CLIENT_ID=tu_client_id
    TINA_TOKEN=tu_token_de_solo_lectura
    
  4. Inicia el servidor de desarrollo:

    npm run dev
    
  5. Accede a la interfaz de administración:

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

Archivos Clave Creados:

  • tina/config.ts - Configuración del esquema
  • app/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]].tsx en 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:

  1. Instala las dependencias:

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

    npx @tinacms/cli@latest init
    
    • Establece el directorio de activos públicos en public
  3. 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
      }
    })
    
  4. Actualiza los scripts de package.json:

    {
      "scripts": {
        "dev": "tinacms dev -c \"vite\"",
        "build": "tinacms build && vite build",
        "preview": "vite preview"
      }
    }
    
  5. 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>
    
  6. 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>
      )
    }
    
  7. 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:

  1. Usa el starter oficial (recomendado):

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

    O inicializa manualmente:

    npx @tinacms/cli@latest init
    
  2. Actualiza los scripts de package.json:

    {
      "scripts": {
        "dev": "tinacms dev -c \"astro dev\"",
        "build": "tinacms build && astro build",
        "preview": "astro preview"
      }
    }
    
  3. 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
    })
    
  4. Edición visual (experimental):

    • Requiere componentes React
    • Usa client:tinaDirective para edición interactiva
    • La edición visual completa es experimental a partir de octubre de 2025
  5. 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:

  1. Inicializa TinaCMS:

    npx @tinacms/cli@latest init
    
  2. Configura manualmente los scripts de compilación:

    {
      "scripts": {
        "dev": "tinacms dev -c \"<tu-comando-de-desarrollo>\"",
        "build": "tinacms build && <tu-comando-de-compilación>"
      }
    }
    
  3. Interfaz de administración:

    • Se crea automáticamente en http://localhost:<puerto>/admin/index.html
    • El puerto depende de tu framework
  4. 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
  5. 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ón
  • path: Ruta del archivo relativa a la raíz del proyecto
  • format: Extensión de archivo (por defecto es 'md')
  • fields: Definición de la estructura del contenido

Referencia de Tipos de Campos

TipoCaso de UsoEjemplo
stringTexto corto (una línea)Título, slug, nombre del autor
rich-textContenido formateado largoCuerpo del blog, contenido de la página
numberValores numéricosPrecio, cantidad, calificación
datetimeValores de fecha/horaFecha de publicación, hora del evento
booleanAlternativas verdadero/falsoEstado de borrador, indicador de destacado
imageCargas de imágenesImagen principal, miniatura, avatar
referenceEnlace a otro documentoAutor, categoría, publicaciones relacionadas
objectGrupo de campos anidadosMetadatos 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

Individual skills in this repo

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

Skills relacionados