Nextjs Tinacms

Next.js 16 + React 19 + TinaCMS + Vercel

Opinionated for: Next.js App Router + TinaCMS + Tina Cloud + Vercel + Tailwind CSS 4 + shadcn/ui.

Two workflows: New Project (scaffold from scratch) or Add CMS (integrate into existing Next.js 15/16 project).

Stack

Quick Start

npx create-next-app@latest my-site --typescript --tailwind --app --src-dir
cd my-site
npx @tinacms/cli@latest init

Verify: tinacms dev then open http://localhost:3000/admin/index.html.

Local dev runs in local-only mode -- content reads/writes directly to the filesystem, no Tina Cloud connection needed. Production builds connect to Tina Cloud via NEXT_PUBLIC_TINA_CLIENT_ID and TINA_TOKEN env vars on Vercel.

Critical Knowledge

1. Server-Client split is mandatory. useTina() requires "use client". Every editable page needs a Server Component (data fetcher) + Client Component (visual editing wrapper).
2. Build order matters. Always "build": "tinacms build && next build". Wrong order breaks with Cannot find module '../tina/__generated__/client'.
3. Pin exact TinaCMS versions. No caret ranges. UI assets drift from CDN. Keep tinacms and @tinacms/* synced via package grouping (RenovateBot or Dependabot).
4. tina/__generated__/ should be gitignored. Only tina-lock.json must be committed. The __generated__/ folder is rebuilt by tinacms build.
5. TinaCMS 3.x is ESM-only. Config files must use import syntax. Set "type": "module" in package.json or use .ts extensions.
6. Async params in Next.js 16. Every page.tsx, layout.tsx, route.ts must await params -- sync access fully removed.
7. proxy.ts replaces middleware.ts. Lives at project root, exports proxy function, runs Node.js runtime only. Codemod: npx @next/codemod@canary middleware-to-proxy .
8. Security: @tinacms/cli >= 2.1.8 required. CVE-2026-28792 (Critical, CVSS 9.6) -- drive-by attacks via CORS + path traversal in older versions.
9. Dev command is tinacms dev -c "next dev". Never next dev alone -- the local GraphQL server won't run.

Version Floors

Look up current stable versions before scaffolding (npm view <pkg> version).

Key Imports

Collections

Add based on project needs:

Common Tasks

Create a new block

Add a template object to the blocks field's templates array in tina/config.ts. Every block needs ui.defaultItem. Optional: ui.previewSrc for visual selector thumbnails.

Add visual editing to a page

1. Server Component fetches { data, query, variables } from Tina client
2. Client Component calls useTina() with those props
3. Add data-tina-field={tinaField(data.page, 'fieldName')} on DOM elements

Enable caching

Set cacheComponents: true in next.config.ts, then use "use cache" directive with cacheLife() presets: seconds, minutes, hours, days, weeks, max.

Deploy to Vercel

1. Build command: tinacms build && next build
2. Set Vercel env vars: NEXT_PUBLIC_TINA_CLIENT_ID, TINA_TOKEN, NEXT_PUBLIC_TINA_BRANCH
3. Install @vercel/analytics + @vercel/speed-insights, render <Analytics /> and <SpeedInsights /> in root layout
4. Set up a Deploy Hook for content change rebuilds
5. Use Vercel Team Environment Variables to share keys across preview/production

Always use Tina Cloud unless the project has a specific reason to self-host. See references/deployment.md for self-hosted as a secondary option.

Claude Code Automations

Set up in .claude/settings.json early in Day 0:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "prompt",
        "prompt": "If the file path contains 'tina/__generated__/' or ends with 'tina-lock.json', BLOCK this edit. These files are auto-generated by tinacms build and must not be manually edited."
      }]
    }],
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "npx prettier --write $CLAUDE_FILE_PATH 2>/dev/null || true"
      }]
    }]
  },
  "permissions": {
    "allow": [
      "Bash(npx tinacms dev:*)",
      "Bash(npx tinacms build:*)",
      "Bash(pnpm dev:*)",
      "Bash(pnpm build:*)",
      "Bash(npx shadcn@latest add:*)"
    ]
  }
}

MCP servers:

• claude mcp add context7 -- npx -y @upstash/context7-mcp@latest -- live TinaCMS/Next.js/React/Tailwind docs
• claude mcp add playwright -- npx -y @anthropic-ai/mcp-server-playwright@latest -- test visual editing in browser

Consider creating project-level skills for repeated tasks:

• /new-block -- scaffold a block template + component + renderer mapping
• /tinacms-check -- audit schema for missing ui.itemProps, broken tinaField, version drift

Agentic Workflow & Vibe Coding

• Iterative Building: Do not expect a perfect CMS integration on the first try. Draft the schema and visual editing wrapper, test the connection locally (tinacms dev), isolate any specific data-fetching or rendering error, adjust exactly ONE field or query at a time, and refresh until the click-to-edit experience is seamless.
• Vibe Coding: Commit your working Next.js pages and Tina schema configurations locally before attempting complex block template additions or deploying to Vercel. Ensure tina-lock.json is included in these commits.

Reference Files