baphomet480/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

| Technology | Version | Key Feature | |-----------|---------|-------------| | Next.js | 16.x | Turbopack default, "use cache", proxy.ts, async params | | TinaCMS | 3.x | Git-backed CMS, visual click-to-edit, GraphQL schema API, ESM-only | | React | 19.x | Server Components, Actions, use(), useEffectEvent | | Tailwind CSS | 4.x | CSS-first config (@import "tailwindcss"), no JS config needed | | shadcn/ui | CLI v4 | Copy-paste components, npx shadcn create, tw-animate-css | | Vercel | -- | Deploy target. @vercel/analytics, @vercel/speed-insights, Deploy Hooks | | Tina Cloud | -- | Default CMS backend. Free tier (2 users), editorial workflow on Team Plus+ |

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).

| Package | Minimum | Why | |---------|---------|-----| | next | >= 16.0.10 | Security patches | | tinacms | >= 3.3.x | Visual selector, ESM-only, current schema API | | @tinacms/cli | >= 2.1.8 | CVE-2026-28792 fix | | react / react-dom | >= 19.0.x | Server Components, Actions (19.2.x for useEffectEvent) | | tailwindcss | >= 4.x | CSS-first config (v3.4.x also acceptable) | | Node.js | >= 20.9.0 | Next.js 16 requirement |

Key Imports

| Import | From | Used For | |--------|------|----------| | defineConfig | tinacms | Schema configuration in tina/config.ts | | useTina | tinacms/dist/react | Live editing in Client Components | | tinaField | tinacms/dist/react | Click-to-edit data attributes | | TinaMarkdown | tinacms/dist/rich-text | Rich text rendering | | client | @/tina/__generated__/client | GraphQL queries (auto-generated) |

Collections

Add based on project needs:

| Collection | Type | When Needed | |-----------|------|-------------| | pages | Folder + blocks | Always | | global | Singleton | Always (site settings, SEO defaults) | | navigation | Singleton | Always (can include footer links) | | posts | Folder | If site has a blog | | authors | Folder | If site has a blog | | footer | Singleton | If footer warrants its own collection | | notFound | Singleton | Optional |

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

| File | When To Read | |------|-------------| | references/schema-design.md | Designing collections, blocks, fields, content hooks | | references/visual-editing.md | Server/client split, draft mode, click-to-edit debugging | | references/seo-meta.md | Metadata, JSON-LD, OG tags, sitemaps, RSS | | references/deployment.md | Tina Cloud vs self-hosted, media providers, env vars | | references/setup-checklist.md | Phased implementation checklist (MVP / Polish / Comprehensive) | | templates/tina-config-starter.ts | Production tina/config.ts with 5 block templates | | templates/page-server-client.tsx | Server/client page pattern with metadata and static params |