Build Tinacms Nextjs

Build TinaCMS Next.js

Build, extend, and debug a Next.js App Router site whose content layer is TinaCMS (git-backed MDX/JSON, GraphQL on top, optional visual editing). This file is the router: detect the project shape, pick the lane, jump to the smallest reference set, deliver the change, verify it.

When To Use

• "Add TinaCMS to my Next.js 14/15/16 App Router site."
• "Model a posts / pages / blocks collection in tina/config.ts."
• "Render an MDX/rich-text body via useTina and ` in app/[slug]/page.tsx`."
• "Wire visual editing, draft mode, data-tina-field, proxy.ts, or live preview."
• "Deploy a TinaCloud site to Vercel" or "self-host the Tina backend with Clerk + MongoDB."
• "Debug tinacms build failures, missing generated client, schema/MDX errors, stale Vercel cache, or admin auth."
• "Migrate from Pages Router or from TinaCloud to self-hosted."

Do NOT use this skill for:

• Plain Next.js work with no TinaCMS surface (no tina/, no tinacms in package.json).
• Converting a live URL or HTML snapshot to Next.js before CMS modeling — use convert-url-to-nextjs.
• Pages Router as the primary target — App Router is the trigger; Pages references here are legacy.
• Edge-runtime backend deploys (Cloudflare Workers, Vercel Edge). Tina backend requires Node.js.

Detect TinaCMS In The Repo (First Hop)

Before drafting any code, run these scans against the user's project. Strong signals mean the skill is correctly engaged:

| Signal | Meaning | |---|---| | tina/config.ts or tina/config.tsx | TinaCMS project — required | | tina/tina-lock.json | Schema lockfile — must be committed | | tina/__generated__/ or .tina/__generated__/ | Generated client — must be gitignored | | tinacms, @tinacms/cli in package.json | TinaCMS install | | tinacms dev -c "next dev" in scripts | App Router + Tina dev script | | import { useTina } from "tinacms/dist/react" | Visual-editing hook — Client Component only | | import { client } from "@/tina/__generated__/client" | Generated GraphQL client | | app/api/tina/[...routes]/route.ts | Self-hosted backend route | | NEXT_PUBLIC_TINA_CLIENT_ID, TINA_TOKEN, NEXT_PUBLIC_TINA_BRANCH | TinaCloud env | | proxy.ts (Next 16+) or middleware.ts | May block /admin, /api/tina/* — inspect |

Optional read-only helpers (do not modify the project):

• bash scripts/check-tina-versions.sh /path/to/project — package versions, package manager, App/Pages Router shape, scripts, routes. See [scripts/check-tina-versions.md](scripts/check-tina-versions.md).
• bash scripts/check-tina-env.sh /path/to/project — env names, config files, generated client, preview/admin/API files, likely lane. See [scripts/check-tina-env.md](scripts/check-tina-env.md).

Read first: [references/setup/01-prerequisites.md](references/setup/01-prerequisites.md), [references/setup/04-package-scripts.md](references/setup/04-package-scripts.md), [references/setup/05-env-vars.md](references/setup/05-env-vars.md), [references/cli/01-overview.md](references/cli/01-overview.md), [references/setup/07-agent-automation.md](references/setup/07-agent-automation.md).

Hard Rules (Top-Loaded)

These rules cause the most expensive failures. Honor them before chasing framework bugs.

• Server vs Client split. useTina() is a Client hook. The page (Server Component) fetches { data, query, variables } from the generated client; a "use client" child receives those three props and calls useTina(props). See [references/rendering/01-app-router-pattern.md](references/rendering/01-app-router-pattern.md), [references/rendering/03-usetina-hook.md](references/rendering/03-usetina-hook.md).
• data-tina-field lands on DOM elements, not React component wrappers. Custom components must forward the attribute to a real DOM node, or the visual-editing overlay misses.
• tinacms build precedes next build. CI runs tinacms build && next build. Never ship a tinacms dev artifact. See [references/cli/03-tinacms-build.md](references/cli/03-tinacms-build.md).
• Pin tinacms, @tinacms/cli, and all @tinacms/* to the same version and update them together.
• Commit tina/tina-lock.json. Never commit tina/__generated__/. See [references/setup/06-gitignore-and-lockfile.md](references/setup/06-gitignore-and-lockfile.md).
• No frontend imports in tina/config.*. Tina builds the config in a separate Node bundle; UI imports break the build.
• Field-name discipline. Alphanumeric + underscore only. No hyphens, spaces, or reserved names: children (in wrong context), mark, _template, _sys, id, __typename. See [references/field-types/11-reserved-names.md](references/field-types/11-reserved-names.md), [references/schema/03-naming-rules.md](references/schema/03-naming-rules.md).
• Use fields: for one document shape; templates: only when documents genuinely have multiple shapes. See [references/schema/02-collection-templates.md](references/schema/02-collection-templates.md).
• Vercel + TinaCMS clients must pass explicit revalidation. Pass fetchOptions: { next: { revalidate: N } } on every Tina query, or content goes stale forever. See [references/rendering/11-vercel-cache-caveat.md](references/rendering/11-vercel-cache-caveat.md), [references/data-fetching/04-fetch-options-revalidate.md](references/data-fetching/04-fetch-options-revalidate.md).
• Next 15+: params, searchParams, draftMode(), cookies(), headers() are async. Await them. Never use them inside a "use cache" scope.
• No proxy.ts / middleware.ts rewrites that touch /admin, /api/preview, or /api/tina/*. See [references/visual-editing/08-proxy-ts.md](references/visual-editing/08-proxy-ts.md).
• Self-hosted Tina backend = Node runtime only. Never deploy to Cloudflare Workers, Vercel Edge, or any V8 isolate. See [references/deployment/05-edge-runtime-not-supported.md](references/deployment/05-edge-runtime-not-supported.md).
• Admin must live at the domain root or its own subdomain. Never example.com/blog/admin.
• Hash self-hosted user passwords. Never commit raw credentials.
• Never edit tina/__generated__/* or .tina/__generated__/* by hand.
• Tina build env reads .env / host env, not .env.local. Build env vars must exist where the build actually runs.
• Never install with --no-optional / --omit=optional when debugging Tina module resolution.

Choose Backend Lane Early

| Lane | Choose when | First references | Success check | |---|---|---|---| | TinaCloud | Managed auth/API, fastest path, GitHub integration, greenfield default | [references/concepts/03-tinacloud-vs-self-hosted.md](references/concepts/03-tinacloud-vs-self-hosted.md), [references/tinacloud/01-overview.md](references/tinacloud/01-overview.md), [references/deployment/01-vercel-tinacloud.md](references/deployment/01-vercel-tinacloud.md) | Admin loads, edits commit to GitHub, queries refresh via revalidate/deploy hook | | Self-hosted | Custom auth, custom storage, private network, enterprise control, no TinaCloud dependency | [references/self-hosted/00-overview.md](references/self-hosted/00-overview.md), [references/self-hosted/01-architecture.md](references/self-hosted/01-architecture.md), [references/deployment/02-vercel-self-hosted.md](references/deployment/02-vercel-self-hosted.md) | /api/tina/gql responds on Node runtime, auth gates writes, DB + git provider configured | | Unknown | User has not specified | Default to TinaCloud for greenfield unless compliance / auth / storage / network constraints point to self-hosted | State the assumption before scaffolding |

Do not split this skill into Cloud and self-hosted variants. One spine; two lanes.

Detect Intent → First Reference Hop

| User intent | First hop | Essential follow-ups | Success check | |---|---|---|---| | Greenfield TinaCMS + App Router | [references/workflows/01-greenfield-blog.md](references/workflows/01-greenfield-blog.md) or [references/workflows/02-greenfield-marketing-site.md](references/workflows/02-greenfield-marketing-site.md) | [references/setup/02-new-project-scaffold.md](references/setup/02-new-project-scaffold.md), [references/concepts/03-tinacloud-vs-self-hosted.md](references/concepts/03-tinacloud-vs-self-hosted.md), [references/setup/06-gitignore-and-lockfile.md](references/setup/06-gitignore-and-lockfile.md) | tinacms dev -c "next dev" runs, /admin/index.html loads, generated client exists, one Tina-backed route renders | | Add Tina to existing App Router site | [references/workflows/03-add-cms-to-existing-site.md](references/workflows/03-add-cms-to-existing-site.md) | [references/setup/03-existing-project-add.md](references/setup/03-existing-project-add.md), [references/setup/04-package-scripts.md](references/setup/04-package-scripts.md), [references/schema/01-collections.md](references/schema/01-collections.md), [references/troubleshooting/04-content-errors.md](references/troubleshooting/04-content-errors.md) | Existing routes intact; one migrated content type audits, builds, renders through Tina | | Model collections / schema | [references/schema/00-schema-overview.md](references/schema/00-schema-overview.md) | [references/schema/01-collections.md](references/schema/01-collections.md), [references/schema/03-naming-rules.md](references/schema/03-naming-rules.md), [references/schema/04-blocks-pattern.md](references/schema/04-blocks-pattern.md), [references/schema/05-reusable-field-groups.md](references/schema/05-reusable-field-groups.md), [references/schema/06-content-hooks.md](references/schema/06-content-hooks.md), [references/schema/07-list-ui-customization.md](references/schema/07-list-ui-customization.md), [references/schema/08-default-collection-set.md](references/schema/08-default-collection-set.md) | tinacms audit and tinacms build pass; content paths match schema | | Choose / implement fields | [references/field-types/00-overview.md](references/field-types/00-overview.md) | [references/field-types/01-string.md](references/field-types/01-string.md), [references/field-types/02-number.md](references/field-types/02-number.md), [references/field-types/03-boolean.md](references/field-types/03-boolean.md), [references/field-types/04-datetime.md](references/field-types/04-datetime.md), [references/field-types/05-image.md](references/field-types/05-image.md), [references/field-types/06-reference.md](references/field-types/06-reference.md), [references/field-types/07-object.md](references/field-types/07-object.md), [references/toolkit-fields/00-toolkit-overview.md](references/toolkit-fields/00-toolkit-overview.md) when custom widgets are required | Editor form matches the model; defaultItem and ui.itemProps prevent empty editor states | | MDX / rich-text body + custom components | [references/field-types/09-rich-text-mdx.md](references/field-types/09-rich-text-mdx.md) | [references/field-types/08-rich-text-markdown.md](references/field-types/08-rich-text-markdown.md), [references/field-types/10-markdown-shortcodes.md](references/field-types/10-markdown-shortcodes.md), [references/rendering/04-tinamarkdown.md](references/rendering/04-tinamarkdown.md), [references/rendering/05-mdx-component-mapping.md](references/rendering/05-mdx-component-mapping.md), [references/rendering/06-overriding-builtins.md](references/rendering/06-overriding-builtins.md), [references/rendering/07-mermaid-diagrams.md](references/rendering/07-mermaid-diagrams.md), [references/rendering/08-block-renderer.md](references/rendering/08-block-renderer.md), [references/visual-editing/04-tinamarkdown-tinafield.md](references/visual-editing/04-tinamarkdown-tinafield.md) | MDX renders with mapped components in App Router, including nested children | | Dynamic page rendering / data fetching / metadata | [references/rendering/01-app-router-pattern.md](references/rendering/01-app-router-pattern.md) | [references/rendering/03-usetina-hook.md](references/rendering/03-usetina-hook.md), [references/data-fetching/01-overview.md](references/data-fetching/01-overview.md), [references/data-fetching/02-generated-client.md](references/data-fetching/02-generated-client.md), [references/data-fetching/03-custom-queries.md](references/data-fetching/03-custom-queries.md), [references/rendering/09-static-params.md](references/rendering/09-static-params.md), [references/seo/01-generate-metadata.md](references/seo/01-generate-metadata.md) | Server fetches Tina data, Client receives { data, query, variables }, route + metadata render under installed Next version | | Caching / revalidation | [references/rendering/11-vercel-cache-caveat.md](references/rendering/11-vercel-cache-caveat.md) | [references/data-fetching/04-fetch-options-revalidate.md](references/data-fetching/04-fetch-options-revalidate.md), [references/rendering/10-caching-use-cache.md](references/rendering/10-caching-use-cache.md), [references/deployment/03-deploy-hooks.md](references/deployment/03-deploy-hooks.md) | Deployed edits refresh within chosen TTL or via webhook revalidation | | Visual editing + draft / preview | [references/visual-editing/01-overview.md](references/visual-editing/01-overview.md) | [references/visual-editing/02-router-config.md](references/visual-editing/02-router-config.md), [references/visual-editing/03-tinafield-helper.md](references/visual-editing/03-tinafield-helper.md), [references/visual-editing/05-draft-mode.md](references/visual-editing/05-draft-mode.md), [references/visual-editing/06-edit-state-hook.md](references/visual-editing/06-edit-state-hook.md), [references/visual-editing/07-debugging-checklist.md](references/visual-editing/07-debugging-checklist.md), [references/visual-editing/08-proxy-ts.md](references/visual-editing/08-proxy-ts.md) | Draft Mode cookie sets, useTina updates preview, data-tina-field targets DOM, proxy.ts/middleware does not block admin/API | | Tina config (provider, branch, admin, client, paths) | [references/config/01-config-anatomy.md](references/config/01-config-anatomy.md) | [references/config/02-build-and-server.md](references/config/02-build-and-server.md), [references/config/03-admin-and-ui.md](references/config/03-admin-and-ui.md), [references/config/04-branch-resolution.md](references/config/04-branch-resolution.md), [references/config/05-client-and-content-api.md](references/config/05-client-and-content-api.md), [references/config/06-typescript-path-aliases.md](references/config/06-typescript-path-aliases.md) | tina/config.* parses, build server resolves, admin route serves, branch resolves correctly | | GraphQL queries / pagination / sorting | [references/graphql/01-overview.md](references/graphql/01-overview.md) | [references/graphql/02-get-document.md](references/graphql/02-get-document.md), [references/graphql/03-query-documents.md](references/graphql/03-query-documents.md), [references/graphql/04-filter-documents.md](references/graphql/04-filter-documents.md), [references/graphql/05-sorting.md](references/graphql/05-sorting.md), [references/graphql/06-pagination.md](references/graphql/06-pagination.md), [references/graphql/07-performance.md](references/graphql/07-performance.md), [references/graphql/08-limitations.md](references/graphql/08-limitations.md), [references/graphql/09-add-document.md](references/graphql/09-add-document.md), [references/graphql/10-update-document.md](references/graphql/10-update-document.md), [references/data-fetching/05-graphql-cli.md](references/data-fetching/05-graphql-cli.md) | Query returns expected shape; tinacms graphql reproduces it | | SEO / OG / sitemap / RSS | [references/seo/01-generate-metadata.md](references/seo/01-generate-metadata.md) | [references/seo/02-description-waterfall.md](references/seo/02-description-waterfall.md), [references/seo/03-og-image-waterfall.md](references/seo/03-og-image-waterfall.md), [references/seo/04-json-ld-structured-data.md

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: yigitkonur
• Source: yigitkonur/skills-by-yigitkonur
• License: MIT

Install and usage instructions live in the source repository linked above.