TinaCMS Skill

Complete integration skill for TinaCMS - Git-backed headless CMS for content-heavy sites

---

Auto-Trigger Keywords

This skill automatically activates when you mention:

CMS & Content Management

• tinacms, tina cms, tina, tinacloud
• headless cms, git-backed cms, git cms, markdown cms
• content management system, cms setup, cms integration
• visual editing, contextual editing, live editing, wysiwyg markdown
• content modeling, content schema, content structure

Use Cases

• blog cms, blog setup, blog integration
• documentation cms, docs cms, documentation site
• marketing site cms, landing page cms
• portfolio cms, personal website cms
• content-heavy site, editorial workflow

Technologies

• next.js cms, nextjs tina, next tina
• vite cms, react cms, vite react tina
• astro cms, astro tina
• markdown editor, mdx editor, markdown management
• gatsby cms, hugo cms, jekyll cms, eleventy cms, remix cms

Features

• git-based content, content in repository, versioned content
• visual markdown editor, markdown preview, live preview
• schema-driven cms, graphql cms, type-safe cms
• self-hosted cms, cloudflare cms, vercel cms

Problems & Errors

• tinacms error, tina error, tinacms setup issue
• esbuild error tina, module resolution tina
• tinacms docker, tinacms 503, reference field error
• failed loading tinacms assets, tinacms build error
• tinacms path mismatch, _template error
• field naming constraints, tinacms alphanumeric

Deployment

• tinacms cloudflare, tina workers, tinacms vercel
• tinacms netlify, self-hosted tina, tina backend
• tinacloud setup, tina authentication, auth.js tina

---

What This Skill Does

Provides complete, production-tested patterns for integrating TinaCMS into modern web applications with support for:

• 4 Frameworks: Next.js (App Router + Pages Router), Vite + React, Astro, Framework-agnostic
• 3 Deployment Options: TinaCloud (managed), Cloudflare Workers, Vercel/Netlify Functions
• 4 Collection Templates: Blog posts, documentation pages, landing pages, authors
• 9 Common Errors Prevented: ESbuild, module resolution, field naming, Docker, _template, paths, build scripts, asset loading, reference fields

---

When to Use This Skill

✅ Use When:

• Building blogs, documentation sites, or marketing websites
• Non-technical users need to manage content
• Content should be versioned in Git with code
• Visual/live editing experience desired
• Self-hosting CMS backend required

❌ Don't Use When:

• Need real-time collaborative editing (use Sanity, Contentful instead)
• Building e-commerce with dynamic inventory (use database instead)
• No content management needed (hardcoded content fine)

---

What's Included

Templates

• Next.js: App Router + Pages Router configurations
• Vite + React: Complete Vite setup with Tina integration
• Astro: Astro starter configuration
• Collections: Blog post, doc page, landing page, author schemas
• Backend: Cloudflare Workers self-hosted backend

References

• Schema Patterns: Advanced collection and field modeling
• Field Types Reference: Complete documentation of all field types
• Deployment Guide: TinaCloud, Cloudflare, Vercel, Netlify
• Self-Hosting on Cloudflare: Complete Workers setup guide
• Common Errors: All 9 errors with causes and solutions
• Migration Guide: Forestry.io to TinaCMS migration

Scripts

• init-nextjs.sh: Automated Next.js setup
• init-vite-react.sh: Automated Vite + React setup
• init-astro.sh: Automated Astro setup
• check-versions.sh: Verify package versions are current

---

Features

Git-Backed Storage ✅

• Content stored as Markdown, MDX, JSON in Git repository
• Full version control and change history
• No vendor lock-in - content lives with your code

Visual/Contextual Editing ✅

• Side-by-side editing experience
• Live preview of changes
• WYSIWYG-like editing for Markdown content

Schema-Driven Content Modeling ✅

• Define content structure in code (tina/config.ts)
• Type-safe GraphQL API auto-generated
• Collections and fields system

Flexible Deployment ✅

• TinaCloud: Managed service (free tier)
• Self-Hosted: Cloudflare Workers, Vercel, Netlify
• Multiple authentication options

Framework Support ✅

• Best: Next.js (App Router + Pages Router)
• Good: React, Astro, Gatsby, Hugo, Jekyll, Remix, 11ty
• Framework-Agnostic: Works with any framework

---

Errors Prevented (9 Total)

This skill prevents 100% of common TinaCMS errors:

1. ESbuild Compilation Errors

   • Importing code with custom loaders
   • Frontend-only code in config
   • Solution: Specific imports, minimal config dependencies

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

   • Corrupted installations
   • Version mismatches
   • Solution: Clean reinstall procedure

3. Field Naming Constraints

   • Hyphens and special characters not allowed
   • Only alphanumeric + underscores
   • Solution: Proper naming patterns

4. Docker Binding Issues

   • TinaCMS not accessible outside container
   • Solution: Bind to 0.0.0.0 instead of 127.0.0.1

5. Missing _template Key Error

   • Templates array requires _template field
   • Solution: Use fields instead or add _template

6. Path Mismatch Issues

   • Collection path doesn't match files
   • Solution: Correct path configuration

7. Build Script Ordering Problems

   • TypeScript errors from missing Tina types
   • Solution: Run tinacms build before framework build

8. Failed Loading TinaCMS Assets

   • Dev assets pushed to production
   • Solution: Always use tinacms build in CI

9. Reference Field 503 Service Unavailable

   • Too many items in referenced collection
   • Solution: Split collections or use string fields

---

Token Efficiency

Estimated Savings: 65-70% (~10,900 tokens saved)

---

Quick Examples

Example 1: Blog with Next.js + TinaCloud

npx create-next-app@latest my-blog --typescript --app
cd my-blog
npx @tinacms/cli@latest init
# Set env vars, start dev server
npm run dev

Example 2: Documentation Site with Astro

npx create-tina-app@latest my-docs --template tina-astro-starter
cd my-docs
npm install && npm run dev

Example 3: Self-Hosted on Cloudflare Workers

npm create cloudflare@latest my-app
npx @tinacms/cli@latest init
npx @tinacms/cli@latest init backend
# Copy Cloudflare Workers backend template
npx wrangler deploy

---

Package Versions

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

Last Verified: 2025-10-24

---

Production Examples

• TinaCMS Website: https://tina.io (dogfooding their own CMS)
• Tina Astro Starter: https://github.com/tinacms/tina-astro-starter
• Tina Next.js Starter: https://github.com/tinacms/tina-starter-alpaca

---

Official Resources

• Website: https://tina.io
• Documentation: https://tina.io/docs
• GitHub: https://github.com/tinacms/tinacms
• Discord: https://discord.gg/zumN63Ybpf

---

Related Skills

Use TinaCMS in combination with:

• clerk-auth - Add authentication to TinaCMS admin
• cloudflare-worker-base - Self-host TinaCMS backend on Workers
• cloudflare-d1 - Store TinaCMS metadata in D1
• ai-sdk-ui - Add AI-powered content generation to editor
• react-hook-form-zod - Extend TinaCMS forms with validation
• tailwind-v4-shadcn - Style TinaCMS frontend

---

License

MIT

---

Support

Issues? Check SKILL.md and references/common-errors.md

Still Stuck?

• Discord: https://discord.gg/zumN63Ybpf
• GitHub Issues: https://github.com/tinacms/tinacms/issues
• Official Docs: https://tina.io/docs

---

Skill Version: 1.0.0 Last Updated: 2025-10-24