TinaCMS

Git-backed headless CMS with visual editing for content-heavy sites.

Last Updated: 2026-01-21 Versions: [email protected], @tinacms/[email protected]

---

Quick Start

Package Manager Recommendation:

• Recommended: pnpm (required for TinaCMS >2.7.3)
• Alternative: npm or yarn (may have module resolution issues in newer versions)

# Install pnpm (if needed)
npm install -g pnpm

# Initialize TinaCMS
npx @tinacms/cli@latest init

# Install dependencies with pnpm
pnpm install

# Update package.json scripts
{
  "dev": "tinacms dev -c \"next dev\"",
  "build": "tinacms build && next build"
}

# Set environment variables
NEXT_PUBLIC_TINA_CLIENT_ID=your_client_id
TINA_TOKEN=your_read_only_token

# Start dev server
pnpm run dev

# Access admin interface
http://localhost:3000/admin/index.html

Version Locking (Recommended):

Pin exact versions to prevent breaking changes from automatic CLI/UI updates:

{
  "dependencies": {
    "tinacms": "3.3.1",  // NOT "^3.3.1"
    "@tinacms/cli": "2.1.1"
  }
}

Why: TinaCMS UI assets are served from CDN and may update before your local CLI, causing incompatibilities.

Source: GitHub Issue #5838

---

Next.js Integration

useTina Hook (enables visual editing):

import { useTina } from 'tinacms/dist/react'
import { client } from '../../tina/__generated__/client'

export default function BlogPost(props) {
  const { data } = useTina({
    query: props.query,
    variables: props.variables,
    data: props.data
  })

  return <article><h1>{data.post.title}</h1></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
    }
  }
}

App Router: Admin route at app/admin/[[...index]]/page.tsx Pages Router: Admin route at pages/admin/[[...index]].tsx

---

Schema Configuration

tina/config.ts structure:

import { defineConfig } from 'tinacms'

export default defineConfig({
  branch: process.env.GITHUB_BRANCH || 'main',
  clientId: process.env.NEXT_PUBLIC_TINA_CLIENT_ID,
  token: process.env.TINA_TOKEN,
  build: {
    outputFolder: 'admin',
    publicFolder: 'public',
  },
  schema: {
    collections: [/* ... */],
  },
})

Collection Example (Blog Post):

{
  name: 'post',           // Alphanumeric + underscores only
  label: 'Blog Posts',
  path: 'content/posts',  // No trailing slash
  format: 'mdx',
  fields: [
    {
      type: 'string',
      name: 'title',
      label: 'Title',
      isTitle: true,
      required: true
    },
    {
      type: 'rich-text',
      name: 'body',
      label: 'Body',
      isBody: true
    }
  ]
}

Field Types: string, rich-text, number, datetime, boolean, image, reference, object

Reference Field Note: When a reference field references multiple collection types with shared field names, ensure the field types match. Conflicting types (e.g., bio: string vs bio: rich-text) cause GraphQL schema errors.

// Example: Reference field referencing multiple collections
{
  type: 'reference',
  name: 'contributor',
  collections: ['author', 'editor']  // Ensure shared fields have same type
}

Source: Community-sourced

---

Common Errors & Solutions

1. ❌ ESbuild Compilation Errors

Error Message:

ERROR: Schema Not Successfully Built
ERROR: Config Not Successfully Executed

Causes:

• Importing code with custom loaders (webpack, babel plugins, esbuild loaders)
• Importing frontend-only code (uses window, DOM APIs, React hooks)
• Importing entire component libraries instead of specific modules

Solution:

Import only what you need:

// ❌ Bad - Imports entire component directory
import { HeroComponent } from '../components/'

// ✅ Good - Import specific file
import { HeroComponent } from '../components/blocks/hero'

Prevention Tips:

• Keep tina/config.ts imports minimal
• Only import type definitions and simple utilities
• Avoid importing UI components directly
• Create separate .schema.ts files if needed

Reference: See references/common-errors.md#esbuild

---

2. ❌ Module Resolution: "Could not resolve 'tinacms'"

Error Message:

Error: Could not resolve "tinacms"

Causes:

• Corrupted or incomplete installation
• Version mismatch between dependencies
• Missing peer dependencies

Solution:

# Clear cache and reinstall
rm -rf node_modules package-lock.json
npm install

# Or with pnpm
rm -rf node_modules pnpm-lock.yaml
pnpm install

# Or with yarn
rm -rf node_modules yarn.lock
yarn install

Prevention:

• Use lockfiles (package-lock.json, pnpm-lock.yaml, yarn.lock)
• Don't use --no-optional or --omit=optional flags
• Ensure react and react-dom are installed (even for non-React frameworks)

---

3. ❌ Field Naming Constraints

Error Message:

Field name contains invalid characters

Cause:

• TinaCMS field names can only contain: letters, numbers, underscores
• Hyphens, spaces, special characters are NOT allowed

Solution:

// ❌ Bad - Uses hyphens
{
  name: 'hero-image',
  label: 'Hero Image',
  type: 'image'
}

// ❌ Bad - Uses spaces
{
  name: 'hero image',
  label: 'Hero Image',
  type: 'image'
}

// ✅ Good - Uses underscores
{
  name: 'hero_image',
  label: 'Hero Image',
  type: 
how to use tinacms
CursorClaude CodeClineCodexWindsurfGooseGitHub CopilotVS CodeGemini CLIKiloOpencodeKimi CLIRoo ClineAiderContinueZedBolt.newLovablev0Replit AgentSweepSmol DeveloperDevinCavemanAmpAntigravity
How to use tinacms on Cursor
AI-first code editor with Composer
1
Prerequisites
Before installing skills in Cursor, ensure your development environment meets these requirements:
›Cursor installed and configured on your development machine
›Node.js version 16.0+ with npm package manager (verify with node --version)
›Active project directory or workspace where you want to add tinacms
2
Execute installation command
Execute the skills CLI command in your project's root directory to begin installation:
$npx skills add https://github.com/jezweb/claude-skills --skill tinacmscopy
The skills CLI fetches tinacms from GitHub repository jezweb/claude-skills and configures it for Cursor.
3
Select Cursor when prompted
The CLI will show a list of available agents. Use arrow keys to navigate and space to select Cursor:
◆ Which agents do you want to install to?
│
│ ── Universal (.agents/skills) ── always included ────
│   • Amp
│   • Antigravity
│   • Cline
│   • Codex
│ ●Cursor(selected)
│   • Cursor
│   • Windsurf
4
Verify installation
Confirm successful installation by checking the skill directory location:
.cursor/skills/tinacms
Reload or restart Cursor to activate tinacms. Access the skill through slash commands (e.g., /tinacms) or your agent's skill management interface.
⚠
Security & Verification Notice
We perform automated surface-level scans (Gen AI Scanner, Socket, Snyk) during installation. These checks detect common vulnerabilities but do not guarantee complete security. Always review skill source code and verify the publisher's reputation before production use.
Skills execute code in your development environment. Always verify the publisher's identity, review recent commits, and test in isolated environments before production deployment.
Additional Resources
›View source code on GitHub›Skills CLI documentation›Learn more about Cursor›What are agent skills?