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
-
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
-
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
-
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
- Defina a estrutura do conteúdo no código (
-
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)
-
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:
-
Construindo Sites com Muito Conteúdo
- Blogs e sites pessoais
- Sites de documentação
- Sites de marketing
- Sites de portfólio
-
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
-
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
-
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:
-
Colaboração em Tempo Real é Necessária
- Múltiplos usuários editando simultaneamente (estilo Google Docs)
- Use Sanity, Contentful ou Firebase
-
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)
-
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:
-
Inicialize o TinaCMS:
npx @tinacms/cli@latest init- Quando solicitado o diretório de ativos públicos, digite
public
- Quando solicitado o diretório de ativos públicos, digite
-
Atualize os scripts do package.json:
{ "scripts": { "dev": "tinacms dev -c \"next dev\"", "build": "tinacms build && next build", "start": "tinacms build && next start" } } -
Defina as variáveis de ambiente:
# .env.local NEXT_PUBLIC_TINA_CLIENT_ID=seu_client_id TINA_TOKEN=seu_token_somente_leitura -
Inicie o servidor de desenvolvimento:
npm run dev -
Acesse a interface administrativa:
http://localhost:3000/admin/index.html
Arquivos Chave Criados:
tina/config.ts- Configuração do esquemaapp/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]].tsxem 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:
-
Instale as dependências:
npm install react@^19 react-dom@^19 tinacms -
Inicialize o TinaCMS:
npx @tinacms/cli@latest init- Defina o diretório de ativos públicos como
public
- Defina o diretório de ativos públicos como
-
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 } }) -
Atualize os scripts do package.json:
{ "scripts": { "dev": "tinacms dev -c \"vite\"", "build": "tinacms build && vite build", "preview": "vite preview" } } -
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> -
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> ) } -
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:
-
Use o starter oficial (recomendado):
npx create-tina-app@latest --template tina-astro-starterOu inicialize manualmente:
npx @tinacms/cli@latest init -
Atualize os scripts do package.json:
{ "scripts": { "dev": "tinacms dev -c \"astro dev\"", "build": "tinacms build && astro build", "preview": "astro preview" } } -
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 }) -
Edição visual (experimental):
- Requer componentes React
- Use
client:tinaDirectivepara edição interativa - Edição visual completa é experimental a partir de Outubro de 2025
-
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:
-
Inicialize o TinaCMS:
npx @tinacms/cli@latest init -
Configure manualmente os scripts de build:
{ "scripts": { "dev": "tinacms dev -c \"<seu-comando-dev>\"", "build": "tinacms build && <seu-comando-build>" } } -
Interface administrativa:
- Criada automaticamente em
http://localhost:<porta>/admin/index.html - A porta depende do seu framework
- Criada automaticamente em
-
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
-
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 administrativapath: Caminho do arquivo relativo à raiz do projetoformat: Extensão do arquivo (padrão é 'md')fields: Definição da estrutura do conteúdo
Referência de Tipos de Campo
| Tipo | Caso de Uso | Exemplo |
|---|---|---|
string | Texto curto (linha única) | Título, slug, nome do autor |
rich-text | Conteúdo formatado longo | Corpo do blog, conteúdo da página |
number | Valores numéricos | Preço, quantidade, avaliação |
datetime | Valores de data/hora | Data de publicação, horário do evento |
boolean | Alternativas verdadeiro/falso | Status de rascunho, sinalizador de destaque |
image | Uploads de imagem | Imagem de destaque, miniatura, avatar |
reference | Link para outro documento | Autor, categoria, posts relacionados |
object | Grupo de campos aninhados | Metadados 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)
-
Crie uma conta em tina.io
-
Crie um projeto e obtenha credenciais:
- Navegue até
app.tina.io - Conecte seu repositório GitHub
- Copie
NEXT_PUBLIC_TINA_CLIENT_IDeTINA_TOKEN
- Navegue até
-
Configure env vars no seu provedor de deploy
-
Faça deploy normalmente
Opção 2: Auto-hospedado no Cloudflare Workers
-
Instale dependências:
npm install @tinacms/datalayer @tinacms/graphql npm install -D @cloudflare/workers-types -
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 -
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:
-
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 } } }) -
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:
-
Defina permissões corretas:
sudo chown -R 1000:1000 . -
Use watch mode no Docker:
ENV CHOKIDAR_USEPOLLING=true -
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
- Documentação Oficial: tina.io/docs
- Comunidade Discord: discord.gg/tinacms
- GitHub: github.com/tinacms/tinacms
- Modelos: Veja o diretório
templates/neste repositório - Referências: Veja o diretório
references/para documentação detalhada de tipos de campo