Communitygithub.com

ovachiever/droid-tings

Crie sites com conteúdo pesado usando o TinaCMS com integração Git. Oferece edição visual e gerenciamento de conteúdo para blogs, documentação e sites de marketing com editores não técnicos.

O que é droid-tings?

Esta skill (ovachiever/droid-tings) capacita agentes de IA a integrarem o TinaCMS, um sistema de gerenciamento de conteúdo (CMS) headless e open-source com versionamento Git, em aplicações web modernas. Ela é ideal para construir sites com muito conteúdo, como blogs, documentação e sites de marketing, especialmente quando editores não técnicos precisam gerenciar o conteúdo visualmente. A skill oferece guias de configuração detalhados para frameworks como Next.js (App Router e Pages Router), Vite+React e Astro, abrangendo desde a inicialização do projeto até o deployment assistido por TinaCloud ou auto-hospedado (Cloudflare Workers, Vercel Functions, etc.). Além disso, inclui práticas recomendadas para modelagem de esquemas (coleções e campos), solução de problemas comuns de compilação (ESbuild) e resolução de módulos, tornando-se uma ferramenta completa para qualquer desenvolvedor que queira implementar um CMS Git-backed com edição visual.

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Habilidade TinaCMS

Habilidade completa para integrar o TinaCMS em aplicações web modernas.


O que é o TinaCMS?

TinaCMS é um sistema de gerenciamento de conteúdo (CMS) headless, open-source e com suporte a Git, que permite que desenvolvedores e criadores de conteúdo colaborem perfeitamente em sites com alto teor de conteúdo.

Principais Recursos

  1. Armazenamento com Suporte a Git

    • Conteúdo armazenado como arquivos Markdown, MDX ou JSON no repositório Git
    • Controle de versão completo e histórico de alterações
    • Sem dependência de fornecedor – o conteúdo fica no seu repositório
  2. Edição Visual/Contextual

    • Experiência de edição lado a lado
    • Visualização ao vivo das alterações enquanto você digita
    • Edição estilo WYSIWYG para conteúdo Markdown
  3. Modelagem de Conteúdo Baseada em Esquema

    • Defina a estrutura do conteúdo no código (tina/config.ts)
    • API GraphQL type-safe gerada automaticamente a partir do esquema
    • Sistema de coleções e campos para conteúdo organizado
  4. Implantação Flexível

    • TinaCloud: Serviço gerenciado (mais fácil, plano gratuito disponível)
    • Auto-hospedado: Cloudflare Workers, Vercel Functions, Netlify Functions, AWS Lambda
    • Múltiplas opções de autenticação (Auth.js, personalizada, dev local)
  5. Suporte a Frameworks

    • Melhor: Next.js (App Router + Pages Router)
    • Bom: React, Astro (edição visual experimental), Gatsby, Hugo, Jekyll, Remix, 11ty
    • Independente de Framework: Funciona com qualquer framework (edição visual limitada a React)

Versões Atuais

  • tinacms: 2.9.0 (Setembro de 2025)
  • @tinacms/cli: 1.11.0 (Outubro de 2025)
  • Suporte React: 19.x (>=18.3.1 <20.0.0)

Quando Usar Esta Habilidade

✅ Use o TinaCMS Quando:

  1. Construindo Sites com Muito Conteúdo

    • Blogs e sites pessoais
    • Sites de documentação
    • Sites de marketing
    • Sites de portfólio
  2. Editores Não Técnicos Precisam de Acesso

    • Equipes de conteúdo sem conhecimento de programação
    • Equipes de marketing gerenciando páginas
    • Autores escrevendo posts de blog
  3. Fluxo de Trabalho Baseado em Git é Desejado

    • Quer versionamento de conteúdo através do Git
    • Precisa de revisão de conteúdo através de pull requests
    • Prefere conteúdo no repositório junto com o código
  4. Edição Visual é Necessária

    • Editores querem ver as alterações ao vivo
    • Experiência WYSIWYG é preferida
    • Fluxo de trabalho de edição lado a lado

❌ Não Use o TinaCMS Quando:

  1. Colaboração em Tempo Real é Necessária

    • Múltiplos usuários editando simultaneamente (estilo Google Docs)
    • Use Sanity, Contentful ou Firebase
  2. Dados Altamente Dinâmicos

    • Catálogos de produtos de e-commerce com mudanças frequentes de inventário
    • Painéis em tempo real
    • Use bancos de dados tradicionais (D1, PostgreSQL)
  3. Nenhum Gerenciamento de Conteúdo é Necessário

    • A aplicação é orientada a dados, não a conteúdo
    • Conteúdo hard-coded é suficiente

Padrões de Configuração por Framework

Use o padrão de configuração apropriado com base na sua escolha de framework.

1. Configuração Next.js (Recomendado)

App Router (Next.js 13+)

Passos:

  1. Inicialize o TinaCMS:

    npx @tinacms/cli@latest init
    
    • Quando solicitado o diretório de ativos públicos, digite public
  2. Atualize os scripts do package.json:

    {
      "scripts": {
        "dev": "tinacms dev -c \"next dev\"",
        "build": "tinacms build && next build",
        "start": "tinacms build && next start"
      }
    }
    
  3. Defina as variáveis de ambiente:

    # .env.local
    NEXT_PUBLIC_TINA_CLIENT_ID=seu_client_id
    TINA_TOKEN=seu_token_somente_leitura
    
  4. Inicie o servidor de desenvolvimento:

    npm run dev
    
  5. Acesse a interface administrativa:

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

Arquivos Chave Criados:

  • tina/config.ts - Configuração do esquema
  • app/admin/[[...index]]/page.tsx - Rota da UI Admin (se usando App Router)

Modelo: Veja templates/nextjs/tina-config-app-router.ts


Pages Router (Next.js 12 e anteriores)

A configuração é idêntica, exceto que a rota admin é:

  • pages/admin/[[...index]].tsx em vez do diretório app

Padrão de Busca de Dados:

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

export default function BlogPost(props) {
  // Hidrata para edição 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' }
}

Modelo: Veja templates/nextjs/tina-config-pages-router.ts


2. Configuração Vite + React

Passos:

  1. Instale as dependências:

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

    npx @tinacms/cli@latest init
    
    • Defina o diretório de ativos públicos como public
  3. Atualize o vite.config.ts:

    import { defineConfig } from 'vite'
    import react from '@vitejs/plugin-react'
    
    export default defineConfig({
      plugins: [react()],
      server: {
        port: 3000  // Padrão do TinaCMS
      }
    })
    
  4. Atualize os scripts do package.json:

    {
      "scripts": {
        "dev": "tinacms dev -c \"vite\"",
        "build": "tinacms build && vite build",
        "preview": "vite preview"
      }
    }
    
  5. Crie a interface administrativa:

    Opção A: Rota manual (React Router)

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

    Opção B: HTML direto

    <!-- 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/[caminho-para-tina-admin]"></script>
      </body>
    </html>
    
  6. Use o hook useTina para edição 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 corpo */}</div>
        </article>
      )
    }
    
  7. Defina as variáveis de ambiente:

    # .env
    VITE_TINA_CLIENT_ID=seu_client_id
    VITE_TINA_TOKEN=seu_token_somente_leitura
    

Modelo: Veja templates/vite-react/


3. Configuração Astro

Passos:

  1. Use o starter oficial (recomendado):

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

    Ou inicialize manualmente:

    npx @tinacms/cli@latest init
    
  2. Atualize os scripts do package.json:

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

    // astro.config.mjs
    import { defineConfig } from 'astro/config'
    import react from '@astro/react'
    
    export default defineConfig({
      integrations: [react()]  // Necessário para o admin do Tina
    })
    
  4. Edição visual (experimental):

    • Requer componentes React
    • Use client:tinaDirective para edição interativa
    • Edição visual completa é experimental a partir de Outubro de 2025
  5. Defina as variáveis de ambiente:

    # .env
    PUBLIC_TINA_CLIENT_ID=seu_client_id
    TINA_TOKEN=seu_token_somente_leitura
    

Melhor para: Sites estáticos focados em conteúdo, documentação, blogs

Modelo: Veja templates/astro/


4. Configuração Independente de Framework

Aplica-se a: Hugo, Jekyll, Eleventy, Gatsby, Remix, ou qualquer framework

Passos:

  1. Inicialize o TinaCMS:

    npx @tinacms/cli@latest init
    
  2. Configure manualmente os scripts de build:

    {
      "scripts": {
        "dev": "tinacms dev -c \"<seu-comando-dev>\"",
        "build": "tinacms build && <seu-comando-build>"
      }
    }
    
  3. Interface administrativa:

    • Criada automaticamente em http://localhost:<porta>/admin/index.html
    • A porta depende do seu framework
  4. Busca de dados:

    • Sem edição visual (apenas barra lateral)
    • Conteúdo editado através da interface com suporte a Git
    • Alterações salvas diretamente nos arquivos
  5. Defina as variáveis de ambiente:

    TINA_CLIENT_ID=seu_client_id
    TINA_TOKEN=seu_token_somente_leitura
    

Limitações:

  • Sem edição visual (recurso exclusivo do React)
  • Integração manual necessária
  • Apenas edição baseada em barra lateral

Melhores Práticas de Modelagem de Esquema

Defina sua estrutura de conteúdo em tina/config.ts.

Estrutura Básica de Configuração

import { defineConfig } from 'tinacms'

export default defineConfig({
  // Configuração de branch
  branch: process.env.GITHUB_BRANCH ||
          process.env.VERCEL_GIT_COMMIT_REF ||
          'main',

  // Credenciais do TinaCloud (se usando serviço gerenciado)
  clientId: process.env.NEXT_PUBLIC_TINA_CLIENT_ID,
  token: process.env.TINA_TOKEN,

  // Configuração de build
  build: {
    outputFolder: 'admin',
    publicFolder: 'public',
  },

  // Configuração de mídia
  media: {
    tina: {
      mediaRoot: '',
      publicFolder: 'public',
    },
  },

  // Esquema de conteúdo
  schema: {
    collections: [
      // Defina as coleções aqui
    ],
  },
})

Coleções

Coleção = Tipo de conteúdo + mapeamento de diretório

{
  name: 'post',           // Singular, nome interno (usado na API)
  label: 'Blog Posts',    // Plural, nome de exibição (mostrado no admin)
  path: 'content/posts',  // Diretório onde os arquivos são armazenados
  format: 'mdx',          // Formato do arquivo: md, mdx, markdown, json, yaml, toml
  fields: [/* ... */]     // Array de definições de campo
}

Propriedades Chave:

  • name: Identificador interno (apenas alfanumérico e underscores)
  • label: Nome legível para humanos na interface administrativa
  • path: Caminho do arquivo relativo à raiz do projeto
  • format: Extensão do arquivo (padrão é 'md')
  • fields: Definição da estrutura do conteúdo

Referência de Tipos de Campo

TipoCaso de UsoExemplo
stringTexto curto (linha única)Título, slug, nome do autor
rich-textConteúdo formatado longoCorpo do blog, conteúdo da página
numberValores numéricosPreço, quantidade, avaliação
datetimeValores de data/horaData de publicação, horário do evento
booleanAlternativas verdadeiro/falsoStatus de rascunho, sinalizador de destaque
imageUploads de imagemImagem de destaque, miniatura, avatar
referenceLink para outro documentoAutor, categoria, posts relacionados
objectGrupo de campos aninhadosMetadados SEO, links sociais

Referência completa: Veja references/field-types-reference.md


Modelos de Coleção

Coleção de Post de Blog

{
  name: 'post',
  label: 'Blog Posts',
  path: 'content/posts',
  format: 'mdx',
  fields: [
    {
      type: 'string',
      name: 'title',
      label: 'Title',
      isTitle: true,  // Mostra na lista de conteúdo
      required: true
    },
    {
      type: 'string',
      name: 'excerpt',
      label: 'Excerpt',
      ui: {
        component: 'textarea'  // Entrada de múltiplas linhas
      }
    },
    {
      type: 'image',
      name: 'coverImage',
      label: 'Cover Image'
    },
    {
      type: 'datetime',
      name: 'date',
      label: 'Published Date',
      required: true
    },
    {
      type: 'reference',
      name: 'author',
      label: 'Author',
      collections: ['author']  // Referencia a coleção de autores
    },
    {
      type: 'boolean',
      name: 'draft',
      label: 'Draft',
      description: 'Se marcado, o post não será publicado',
      required: true
    },
    {
      type: 'rich-text',
      name: 'body',
      label: 'Body',
      isBody: true  // Área de conteúdo principal
    }
  ],
  ui: {
    router: ({ document }) => `/blog/${document._sys.filename}`
  }
}

Modelo: Veja templates/collections/blog-post.ts


Coleção de Página de Documentação

{
  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: 'Ordem de classificação na barra lateral'
    },
    {
      type: 'rich-text',
      name: 'body',
      label: 'Body',
      isBody: true,
      templates: [
        // Componentes MDX podem ser definidos aqui
      ]
    }
  ],
  ui: {
    router: ({ document }) => {
      const breadcrumbs = document._sys.breadcrumbs.join('/')
      return `/docs/${breadcrumbs}`
    }
  }
}

Modelo: Veja templates/collections/doc-page.ts


Coleção de Autor (Alvo de Referência)

{
  name: 'author',
  label: 'Authors',
  path: 'content/authors',
  format: 'json',  // Use JSON para dados estruturados
  fields: [
    {
      type: 'string',
      name: 'name',
      label: 'Name',
      isTitle: true,
      required: true
    },
    {
      type: 'string',
      name: 'email',
      label: 'Email',
      ui: {
        validate: (value) => {
          if (!value?.includes('@')) {
            return 'Endereço de email inválido'
          }
        }
      }
    },
    {
      type: 'image',
      name: 'avatar',
      label: 'Avatar'
    },
    {
      type: 'object',
      name: 'social',
      label: 'Social Links',
      fields: [
        {
          type: 'string',
          name: 'twitter',
          label: 'Twitter'
        },
        {
          type: 'string',
          name: 'github',
          label: 'GitHub'
        },
        {
          type: 'string',
          name: 'linkedin',
          label: 'LinkedIn'
        }
      ]
    },
    {
      type: 'boolean',
      name: 'active',
      label: 'Active',
      description: 'Se desmarcado, o autor não será exibido'
    },
    {
      type: 'string',
      name: 'bio',
      label: 'Bio',
      ui: {
        component: 'textarea'
      }
    }
  ],
  ui: {
    router: ({ document }) => `/authors/${document._sys.filename}`
  }
}

Modelo: Veja templates/collections/author.ts


Deployment e Hospedagem

Opção 1: TinaCloud (Gerenciado)

  1. Crie uma conta em tina.io

  2. Crie um projeto e obtenha credenciais:

    • Navegue até app.tina.io
    • Conecte seu repositório GitHub
    • Copie NEXT_PUBLIC_TINA_CLIENT_ID e TINA_TOKEN
  3. Configure env vars no seu provedor de deploy

  4. Faça deploy normalmente

Opção 2: Auto-hospedado no Cloudflare Workers

  1. Instale dependências:

    npm install @tinacms/datalayer @tinacms/graphql
    npm install -D @cloudflare/workers-types
    
  2. Crie functions/tina.ts:

    import { TinaNodeBackend, LocalBackendAuthProvider } from '@tinacms/datalayer'
    import { TinaCloudCloudflareAuthProvider } from 'tinacms'
    
    const tinaBackend = TinaNodeBackend({
      authProvider: TinaCloudCloudflareAuthProvider(),
      databaseProvider: new GitHubDatabaseProvider({
        branch: process.env.GITHUB_BRANCH || 'main',
        owner: process.env.GITHUB_OWNER,
        repo: process.env.GITHUB_REPO,
        token: process.env.GITHUB_PERSONAL_ACCESS_TOKEN
      })
    })
    
    export default tinaBackend
    
  3. Configure as rotas do seu framework


Solução de Problemas

Erro: Module not found: Can't resolve '@tinacms/cli'

Solução: Instale como dependência de desenvolvimento:

npm install -D @tinacms/cli

Erro: ESbuild compilation error with TinaCMS

Solução:

  1. Atualize sua configuração do Vite:

    // vite.config.ts
    import { defineConfig } from 'vite'
    import react from '@vitejs/plugin-react'
    
    export default defineConfig({
      plugins: [react()],
      optimizeDeps: {
        include: ['tinacms', '@tinacms/cli', '@tinacms/graphql', '@tinacms/datalayer']
      },
      build: {
        commonjsOptions: {
          transformMixedEsModules: true
        }
      }
    })
    
  2. Limpe o cache do esbuild:

    npx esbuild --clear-cache
    

Erro: Error: Cannot find module 'tinacms'

Solução:

# Reinstale dependências
rm -rf node_modules
npm install

# Verifique se o Node.js é >= 18
node --version

Erro: Docker binding problems on Linux

Solução:

  1. Defina permissões corretas:

    sudo chown -R 1000:1000 .
    
  2. Use watch mode no Docker:

    ENV CHOKIDAR_USEPOLLING=true
    
  3. Configuração do Docker Compose:

    services:
      app:
        image: node:20
        working_dir: /app
        volumes:
          - .:/app
          - /app/node_modules
        command: npm run dev
        environment:
          - CHOKIDAR_USEPOLLING=true
          - WATCHPACK_POLLING=true
    

Recursos Adicionais

Individual skills in this repo

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

Habilidades Relacionadas