tinacms

TinaCMS Skill

Complete skill for integrating TinaCMS into modern web applications.

What is TinaCMS?

TinaCMS is an open-source, Git-backed headless content management system (CMS) that enables developers and content creators to collaborate seamlessly on content-heavy websites.

Key Features

1. Git-Backed Storage
2. Content stored as Markdown, MDX, or JSON files in Git repository
3. Full version control and change history
4. No vendor lock-in - content lives in your repo

1. Visual/Contextual Editing
2. Side-by-side editing experience
3. Live preview of changes as you type
4. WYSIWYG-like editing for Markdown content

1. Schema-Driven Content Modeling
2. Define content structure in code (tina/config.ts)
3. Type-safe GraphQL API auto-generated from schema
4. Collections and fields system for organized content

1. Flexible Deployment
2. TinaCloud: Managed service (easiest, free tier available)
3. Self-Hosted: Cloudflare Workers, Vercel Functions, Netlify Functions, AWS Lambda
4. Multiple authentication options (Auth.js, custom, local dev)

1. Framework Support
2. Best: Next.js (App Router + Pages Router)
3. Good: React, Astro (experimental visual editing), Gatsby, Hugo, Jekyll, Remix, 11ty
4. Framework-Agnostic: Works with any framework (visual editing limited to React)

Current Versions

• tinacms: 2.9.0 (September 2025)
• @tinacms/cli: 1.11.0 (October 2025)
• React Support: 19.x (>=18.3.1 <20.0.0)

When to Use This Skill

✅ Use TinaCMS When:

1. Building Content-Heavy Sites
2. Blogs and personal websites
3. Documentation sites
4. Marketing websites
5. Portfolio sites

1. Non-Technical Editors Need Access
2. Content teams without coding knowledge
3. Marketing teams managing pages
4. Authors writing blog posts

1. Git-Based Workflow Desired
2. Want content versioning through Git
3. Need content review through pull requests
4. Prefer content in repository with code

1. Visual Editing Required
2. Editors want to see changes live
3. WYSIWYG experience preferred
4. Side-by-side editing workflow

❌ Don't Use TinaCMS When:

1. Real-Time Collaboration Needed
2. Multiple users editing simultaneously (Google Docs-style)
3. Use Sanity, Contentful, or Firebase instead

1. Highly Dynamic Data
2. E-commerce product catalogs with frequent inventory changes
3. Real-time dashboards
4. Use traditional databases (D1, PostgreSQL) instead

1. No Content Management Needed
2. Application is data-driven, not content-driven
3. Hard-coded content is sufficient

Setup Patterns by Framework

Use the appropriate setup pattern based on your framework choice.

1. Next.js Setup (Recommended)

App Router (Next.js 13+)

Steps:

1. Initialize TinaCMS:

``bash npx @tinacms/cli@latest init ``

• When prompted for public assets directory, enter public

1. Update package.json scripts:

``json { "scripts": { "dev": "tinacms dev -c \"next dev\"", "build": "tinacms build && next build", "start": "tinacms build && next start" } } ``

1. Set environment variables:

``env # .env.local NEXT_PUBLIC_TINA_CLIENT_ID=your_client_id TINA_TOKEN=your_read_only_token ``

1. Start development server:

``bash npm run dev ``

1. Access admin interface:

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

Key Files Created:

• tina/config.ts - Schema configuration
• app/admin/[[...index]]/page.tsx - Admin UI route (if using App Router)

Template: See templates/nextjs/tina-config-app-router.ts

Pages Router (Next.js 12 and below)

Setup is identical, except admin route is:

• pages/admin/[[...index]].tsx instead of app directory

Data Fetching Pattern:

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

export default function BlogPost(props) {
  // Hydrate for visual editing
  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' }
}

Template: See templates/nextjs/tina-config-pages-router.ts

2. Vite + React Setup

Steps:

1. Install dependencies:

``bash npm install react@^19 react-dom@^19 tinacms ``

1. Initialize TinaCMS:

``bash npx @tinacms/cli@latest init ``

• Set public assets directory to public

1. Update vite.config.ts:

```typescript import { defineConfig } from 'vite' import react from '@vitejs/plugin-react'

export default defineConfig({ plugins: [react()], server: { port: 3000 // TinaCMS default } }) ```

1. Update package.json scripts:

``json { "scripts": { "dev": "tinacms dev -c \"vite\"", "build": "tinacms build && vite build", "preview": "vite preview" } } ``

1. Create admin interface:

Option A: Manual route (React Router) ```tsx // src/pages/Admin.tsx import TinaCMS from 'tinacms'

export default function Admin() { return <div id="tina-admin" /> } ```

Option B: Direct HTML ``html <!-- 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/[path-to-tina-admin]"></script> </body> </html> ``

1. Use useTina hook for visual editing:

```tsx 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>{/ render body /}</div> </article> ) } ```

1. Set environment variables:

``env # .env VITE_TINA_CLIENT_ID=your_client_id VITE_TINA_TOKEN=your_read_only_token ``

Template: See templates/vite-react/

3. Astro Setup

Steps:

1. Use official starter (recommended):

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

Or initialize manually: ``bash npx @tinacms/cli@latest init ``

1. Update package.json scripts:

``json { "scripts": { "dev": "tinacms dev -c \"astro dev\"", "build": "tinacms build && astro build", "preview": "astro preview" } } ``

1. Configure Astro:

```javascript // astro.config.mjs import { defineConfig } from 'astro/config' import react from '@astro/react'

export default defineConfig({ integrations: [react()] // Required for Tina admin }) ```

1. Visual editing (experimental):
2. Requires React components
3. Use client:tinaDirective for interactive editing
4. Full visual editing is experimental as of October 2025

1. Set environment variables:

```env # .env PUBLI