nextjs-tinacms

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Next.js 16 + React 19 + TinaCMS Skill

Next.js 16 + React 19 + TinaCMS 技能指南

Two primary workflows:

New Project: Scaffold Next.js 16 + TinaCMS with blocks page builder, visual editing, complete SEO, Tailwind CSS 4, shadcn/ui
Add CMS: Integrate TinaCMS into an existing Next.js 15/16 project

两种核心工作流：

新项目搭建：初始化带有区块页面构建器、可视化编辑、完整SEO、Tailwind CSS 4、shadcn/ui的Next.js 16 + TinaCMS项目
集成CMS：将TinaCMS整合到现有Next.js 15/16项目中

Why This Stack

技术栈优势

Next.js 16 — Turbopack default,
```
"use cache"
```
directive,
```
proxy.ts
```
replaces middleware, async params required, React 19.2
TinaCMS 3.x — Git-backed headless CMS, visual click-to-edit, GraphQL API from code-first schema, admin UI at
```
/admin
```
React 19.2 — Server Components stable, Actions,
```
use()
```
hook, View Transitions, React Compiler (opt-in)
Tailwind CSS 4 — CSS-first config,
```
@import "tailwindcss"
```
, no
```
tailwind.config.js
```
needed
shadcn/ui — Copy-paste components, works with Tailwind, not a versioned package

Next.js 16 — 默认使用Turbopack，支持
```
"use cache"
```
指令，
```
proxy.ts
```
替代middleware，强制要求异步参数，搭配React 19.2
TinaCMS 3.x — 基于Git的无头CMS，支持可视化点击即编辑，通过代码优先Schema生成GraphQL API，管理后台入口为
```
/admin
```
React 19.2 — Server Components稳定可用，支持Actions、
```
use()
```
钩子、View Transitions，可选启用React Compiler
Tailwind CSS 4 — CSS优先配置模式，支持
```
@import "tailwindcss"
```
，无需
```
tailwind.config.js
```
文件
shadcn/ui — 可直接复制粘贴的组件库，兼容Tailwind，非版本化包

Critical Knowledge

关键注意事项

Server-Client split is mandatory.
```
useTina()
```
requires
```
"use client"
```
. Every editable page needs a Server Component (data fetcher) and a Client Component (visual editing wrapper). No global
```
TinaProvider
```
needed in TinaCMS v2+.

Build order matters. Always

"build": "tinacms build && next build"

. Running

next build

first →

Cannot find module '../tina/__generated__/client'

Pin exact TinaCMS versions. No caret ranges. UI assets partially served from CDN and drift from local CLI. Keep all
```
tinacms
```
and
```
@tinacms/*
```
synced via RenovateBot grouping.

tina/__generated__/
MUST be committed. Files

_graphql.json

_lookup.json

_schema.json

, and

tina-lock.json

are needed for production builds.

Async params in Next.js 16. Every
```
page.tsx
```
,
```
layout.tsx
```
,
```
route.ts
```
must
```
await params
```
— sync access fully removed.
proxy.ts
replaces
middleware.ts
in Next.js 16. Auth, redirects, and request manipulation move to
```
app/proxy.ts
```
running on Node.js runtime.
Node.js ≥ 20.9.0 required. Next.js 16 dropped Node 18.
Field names: alphanumeric + underscores only. Hyphens/spaces in schema field names cause build errors.
pnpm required for TinaCMS ≥ 2.7.3. npm/yarn may have module resolution issues.
Dev command is
tinacms dev -c "next dev"
. Never
```
next dev
```
alone — the local GraphQL server won't run.
Self-hosted TinaCMS does NOT work in Edge Runtime (Cloudflare Workers, Vercel Edge Functions). Marked wontfix.
useTina()
returns props.data unchanged in production — zero overhead. Only subscribes to live updates in edit mode.

必须严格区分服务端与客户端组件。
```
useTina()
```
要求添加
```
"use client"
```
指令。每个可编辑页面都需要一个服务端组件（数据获取器）和一个客户端组件（可视化编辑包装器）。TinaCMS v2+无需全局
```
TinaProvider
```
。

构建顺序至关重要。构建命令必须为

"build": "tinacms build && next build"

。若先执行

next build

会导致

Cannot find module '../tina/__generated__/client'

错误。

固定TinaCMS精确版本。禁止使用 caret 范围（^）。UI资源部分从CDN加载，可能与本地CLI版本不一致。通过RenovateBot分组同步所有
```
tinacms
```
和
```
@tinacms/*
```
包版本。
必须提交
tina/__generated__/
目录。其中的
```
_graphql.json
```
、
```
_lookup.json
```
、
```
_schema.json
```
和
```
tina-lock.json
```
文件是生产构建必需的。
Next.js 16的异步参数。所有
```
page.tsx
```
、
```
layout.tsx
```
、
```
route.ts
```
必须使用
```
await params
```
——同步访问已被完全移除。
Next.js 16中
proxy.ts
替代
middleware.ts
。认证、重定向和请求处理逻辑迁移至运行在Node.js runtime的
```
app/proxy.ts
```
。
要求Node.js ≥ 20.9.0。Next.js 16已放弃对Node 18的支持。
字段名称仅允许字母数字+下划线。Schema字段名称中的连字符/空格会导致构建错误。
TinaCMS ≥ 2.7.3要求使用pnpm。npm/yarn可能存在模块解析问题。
开发命令为
tinacms dev -c "next dev"
。绝对不能单独执行
```
next dev
```
——否则本地GraphQL服务器无法启动。
自托管TinaCMS无法在Edge Runtime中运行（Cloudflare Workers、Vercel Edge Functions），该问题标记为 wontfix。
生产环境中
useTina()
返回的props.data保持不变——无额外性能开销。仅在编辑模式下订阅实时更新。

Version Floors

最低版本要求

Before scaffolding, look up current stable versions (

npm view <pkg> version

). Minimum floors:

Package	Minimum	Why
`next`	≥ 16.0.10	Security patches
`tinacms`	≥ 3.3.x	Visual selector, current schema API
`@tinacms/cli`	≥ 2.1.x	Current build toolchain
`react` / `react-dom`	≥ 19.2.x	View Transitions, useEffectEvent
`tailwindcss`	≥ 4.x	CSS-first config (v3.4.x also acceptable)
Node.js	≥ 20.9.0	Next.js 16 requirement
TypeScript	≥ 5.1.0	Required for Next.js 16 types

初始化项目前，查询当前稳定版本（

npm view <pkg> version

）。最低版本要求：

包名	最低版本	原因
`next`	≥ 16.0.10	安全补丁
`tinacms`	≥ 3.3.x	可视化选择器、当前Schema API
`@tinacms/cli`	≥ 2.1.x	当前构建工具链
`react` / `react-dom`	≥ 19.2.x	View Transitions、useEffectEvent
`tailwindcss`	≥ 4.x	CSS优先配置（v3.4.x也可兼容）
Node.js	≥ 20.9.0	Next.js 16要求
TypeScript	≥ 5.1.0	Next.js 16类型定义要求

Workflow: New Project

工作流：新项目搭建

Follow the 247-task checklist in

references/day0-2-checklist.md

task-by-task. The sections below summarize the architecture — the checklist has the exhaustive implementation details.

严格按照

references/day0-2-checklist.md

中的247项任务清单逐步执行。以下内容为架构概述——详细实现步骤请参考任务清单。

Step 1: Scaffold & Install

步骤1：项目初始化与安装

bash

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

Verify:

tinacms dev

→ confirm

/admin

loads at

http://localhost:3000/admin/index.html

bash

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

验证：执行

tinacms dev

→ 确认

http://localhost:3000/admin/index.html

可加载管理后台。

Step 2: Configure Package Management

步骤2：包管理配置

Pin exact TinaCMS versions. Add

renovate.json

— see

references/day0-2-checklist.md § Stack Versions

for config.

固定TinaCMS精确版本。添加

renovate.json

文件——配置示例请参考

references/day0-2-checklist.md § 技术栈版本

。

Step 3: Schema Design in

tina/config.ts

步骤3：

tina/config.ts

中的Schema设计

Read

references/nextjs16-react19-tinacms-reference.md § Schema Design Patterns

for full examples. Use

templates/tina-config-starter.ts

as starting point.

Required collections:

Collection	Type	Purpose
`pages`	Folder + blocks	Dynamic pages with visual page builder
`posts`	Folder	Blog/articles with structured fields
`authors`	Folder	Referenced by posts
`global`	Single doc	Site-wide settings, SEO defaults, social links
`navigation`	Single doc	Editable nav structure
`footer`	Single doc	Footer content and link groups
`notFound`	Single doc	Customizable 404 page content

Singleton pattern:

typescript

ui: { global: true, allowedActions: { create: false, delete: false } }

Blocks pattern:

typescript

{
  type: 'object', list: true, name: 'blocks', label: 'Page Sections',
  ui: { visualSelector: true },
  templates: [heroBlock, featuresBlock, contentBlock, ctaBlock, faqBlock],
}

Every block template needs:

ui.previewSrc

ui.defaultItem

, section style group (layout/background/height/textColor as enums mapped to Tailwind classes).

Field quality — enforce on every field:

```
isTitle: true
```
on title fields,
```
required: true
```
on mandatory fields
```
ui.validate
```
for character limits, format validation
```
ui.description
```
for editorial guidance
```
ui.itemProps
```
on every list field with meaningful labels
```
ui.component: 'textarea'
```
on multi-line strings,
```
'group'
```
for collapsible groups

Reusable field groups — extract as shared variables:

seoFields

ctaFields

linkFields

responsiveImageFields

sectionStyleFields

Content hooks:

typescript

ui: {
  beforeSubmit: async ({ values }) => ({
    ...values,
    slug: values.title.toLowerCase().replace(/\s+/g, '-').replace(/[^a-z0-9-]/g, ''),
    modifiedDate: new Date().toISOString(),
  }),
}

完整示例请参考

references/nextjs16-react19-tinacms-reference.md § Schema设计模式

。以

templates/tina-config-starter.ts

为初始模板。

必需集合：

集合名称	类型	用途
`pages`	文件夹+区块	支持可视化页面构建器的动态页面
`posts`	文件夹	带有结构化字段的博客/文章
`authors`	文件夹	文章引用的作者信息
`global`	单文档	站点全局设置、SEO默认值、社交链接
`navigation`	单文档	可编辑的导航结构
`footer`	单文档	页脚内容和链接组
`notFound`	单文档	可自定义的404页面内容

单例模式：

typescript

ui: { global: true, allowedActions: { create: false, delete: false } }

区块模式：

typescript

{
  type: 'object', list: true, name: 'blocks', label: '页面区块',
  ui: { visualSelector: true },
  templates: [heroBlock, featuresBlock, contentBlock, ctaBlock, faqBlock],
}

每个区块模板需要：

ui.previewSrc

、

ui.defaultItem

、区块样式组（布局/背景/高度/文字颜色为枚举类型，映射到Tailwind类名）。

字段质量规范——所有字段必须遵循：

标题字段添加
```
isTitle: true
```
，必填字段添加
```
required: true
```
使用
```
ui.validate
```
进行字符限制、格式验证
添加
```
ui.description
```
提供编辑指导
所有列表字段添加
```
ui.itemProps
```
，设置有意义的标签
多行字符串使用
```
ui.component: 'textarea'
```
，可折叠分组使用
```
'group'
```

可复用字段组——提取为共享变量：

seoFields

、

ctaFields

、

linkFields

、

responsiveImageFields

、

sectionStyleFields

。

内容钩子：

typescript

ui: {
  beforeSubmit: async ({ values }) => ({
    ...values,
    slug: values.title.toLowerCase().replace(/\s+/g, '-').replace(/[^a-z0-9-]/g, ''),
    modifiedDate: new Date().toISOString(),
  }),
}

Step 4: Server-Client Page Pattern

步骤4：服务端-客户端页面模式

See

templates/page-server-client.tsx

for the complete pattern.

typescript

// app/[...slug]/page.tsx — Server Component
import client from '@/tina/__generated__/client'
import PageClient from './client-page'

export default async function Page({ params }: { params: Promise<{ slug: string[] }> }) {
  const { slug } = await params
  const relativePath = `${slug.join('/')}.md`
  const { data, query, variables } = await client.queries.page({ relativePath })
  return <PageClient data={data} query={query} variables={variables} />
}

export async function generateStaticParams() {
  const pages = await client.queries.pageConnection()
  return pages.data.pageConnection.edges?.map((edge) => ({
    slug: edge?.node?._sys.breadcrumbs,
  })) ?? []
}

typescript

// app/[...slug]/client-page.tsx — Client Component
'use client'
import { useTina, tinaField } from 'tinacms/dist/react'
import { Blocks } from '@/components/blocks'

export default function PageClient(props: { data: any; query: string; variables: any }) {
  const { data } = useTina(props)
  return (
    <main data-tina-field={tinaField(data.page, 'blocks')}>
      <Blocks blocks={data.page.blocks} />
    </main>
  )
}

完整示例请参考

templates/page-server-client.tsx

。

typescript

// app/[...slug]/page.tsx — 服务端组件
import client from '@/tina/__generated__/client'
import PageClient from './client-page'

export default async function Page({ params }: { params: Promise<{ slug: string[] }> }) {
  const { slug } = await params
  const relativePath = `${slug.join('/')}.md`
  const { data, query, variables } = await client.queries.page({ relativePath })
  return <PageClient data={data} query={query} variables={variables} />
}

export async function generateStaticParams() {
  const pages = await client.queries.pageConnection()
  return pages.data.pageConnection.edges?.map((edge) => ({
    slug: edge?.node?._sys.breadcrumbs,
  })) ?? []
}

typescript

// app/[...slug]/client-page.tsx — 客户端组件
'use client'
import { useTina, tinaField } from 'tinacms/dist/react'
import { Blocks } from '@/components/blocks'

export default function PageClient(props: { data: any; query: string; variables: any }) {
  const { data } = useTina(props)
  return (
    <main data-tina-field={tinaField(data.page, 'blocks')}>
      <Blocks blocks={data.page.blocks} />
    </main>
  )
}

Step 5: Visual Editing & Draft Mode

步骤5：可视化编辑与草稿模式

Draft Mode API route (

app/api/preview/route.ts

typescript

import { draftMode } from 'next/headers'
import { redirect } from 'next/navigation'

export async function GET(request: Request) {
  const { searchParams } = new URL(request.url)
  const slug = searchParams.get('slug') || '/'
  ;(await draftMode()).enable()
  redirect(slug)
}

Visual editing debug checklist — if click-to-edit doesn't work:

Draft mode enabled? (
```
/api/preview
```
)
Component is
```
"use client"
```
?
```
useTina()
```
called with correct
```
{ data, query, variables }
```
props?

data-tina-field={tinaField(data.page, 'fieldName')}

on DOM elements (not wrapper components)?

Tina dev server running? (
```
tinacms dev
```
)
Types generated and current? (
```
tina/__generated__/
```
)

ui.router
on every content collection for contextual editing preview:

typescript

ui: { router: ({ document }) => `/blog/${document._sys.filename}` }

草稿模式API路由（

app/api/preview/route.ts

）：

typescript

import { draftMode } from 'next/headers'
import { redirect } from 'next/navigation'

export async function GET(request: Request) {
  const { searchParams } = new URL(request.url)
  const slug = searchParams.get('slug') || '/'
  ;(await draftMode()).enable()
  redirect(slug)
}

可视化编辑调试清单——若点击即编辑功能失效：

是否启用了草稿模式？（访问
```
/api/preview
```
）
组件是否添加了
```
"use client"
```
指令？
```
useTina()
```
是否传入了正确的
```
{ data, query, variables }
```
参数？
DOM元素上是否添加了
```
data-tina-field={tinaField(data.page, 'fieldName')}
```
（而非包装组件）？
Tina开发服务器是否在运行？（执行
```
tinacms dev
```
）
类型文件是否已生成且为最新版本？（检查
```
tina/__generated__/
```
）

**所有内容集合添加

ui.router

**以支持上下文编辑预览：

typescript

ui: { router: ({ document }) => `/blog/${document._sys.filename}` }

Step 6: Complete SEO Implementation

步骤6：完整SEO实现

Read

references/day0-2-checklist.md

— Day 1 tasks 1.16–1.98 for the exhaustive 80+ SEO field specs covering global settings singleton, per-page SEO object, article fields, JSON-LD schemas, OG tags, Twitter cards, discovery files.

Key patterns:

SEO description waterfall:

```
metaDescription
```
(explicit) → 2.
```
excerpt
```
→ 3. Auto-truncated content → 4.
```
siteDescription
```
(global)

generateMetadata()
in every page:

typescript

export async function generateMetadata({ params }: Props): Promise<Metadata> {
  const { slug } = await params
  const { data } = await client.queries.page({ relativePath: `${slug}.md` })
  const seo = data.page.seo
  const global = await client.queries.global({ relativePath: 'settings.json' })
  return {
    title: seo?.metaTitle || data.page.title,
    description: resolveDescription(seo, data.page, global.data.global),
    openGraph: {
      images: resolveOgImage(seo, global.data.global),
      type: 'website',
      siteName: global.data.global.siteName,
    },
    robots: { index: !seo?.noIndex, follow: !seo?.noFollow },
    alternates: { canonical: seo?.canonical || `${global.data.global.siteUrl}/${slug}` },
  }
}

JSON-LD — on every page:

Organization

WebSite

(homepage),

WebPage

Article

BlogPosting

(posts),

BreadcrumbList

FAQPage

(FAQ blocks).

Discovery files:

```
app/sitemap.ts
```
— dynamic from all collections, respects
```
noIndex
```
/
```
draft
```
```
app/robots.ts
```
— disallows
```
/admin
```
,
```
/api/preview
```
```
app/feed.xml/route.ts
```
— RSS for blog

详细的80+项SEO字段规范请参考

references/day0-2-checklist.md

——第1天任务1.16–1.98，涵盖全局设置单例、页面级SEO对象、文章字段、JSON-LD Schema、OG标签、Twitter卡片、站点发现文件。

核心模式：

SEO描述优先级：

```
metaDescription
```
（显式设置）→ 2.
```
excerpt
```
（摘要）→ 3. 自动截断的内容 → 4.
```
siteDescription
```
（全局站点描述）

每个页面添加
generateMetadata()
：

typescript

export async function generateMetadata({ params }: Props): Promise<Metadata> {
  const { slug } = await params
  const { data } = await client.queries.page({ relativePath: `${slug}.md` })
  const seo = data.page.seo
  const global = await client.queries.global({ relativePath: 'settings.json' })
  return {
    title: seo?.metaTitle || data.page.title,
    description: resolveDescription(seo, data.page, global.data.global),
    openGraph: {
      images: resolveOgImage(seo, global.data.global),
      type: 'website',
      siteName: global.data.global.siteName,
    },
    robots: { index: !seo?.noIndex, follow: !seo?.noFollow },
    alternates: { canonical: seo?.canonical || `${global.data.global.siteUrl}/${slug}` },
  }
}

JSON-LD Schema——每个页面添加：

Organization

、

WebSite

（首页）、

WebPage

、

Article

BlogPosting

（文章）、

BreadcrumbList

、

FAQPage

（FAQ区块）。

站点发现文件：

```
app/sitemap.ts
```
— 从所有集合动态生成，尊重
```
noIndex
```
/
```
draft
```
状态
```
app/robots.ts
```
— 禁止爬虫访问
```
/admin
```
、
```
/api/preview
```
```
app/feed.xml/route.ts
```
— 博客RSS订阅源

Step 7: Caching Strategy

步骤7：缓存策略

typescript

async function getPage(slug: string) {
  'use cache'
  cacheLife({ stale: 300, revalidate: 60, expire: 3600 })
  const { data } = await client.queries.page({ relativePath: `${slug}.md` })
  return data
}

Draft mode bypasses all caches (confirmed after Next.js PR #77141). Next.js 15+ changed

fetch()

default to

no-store

— explicitly opt into caching.

typescript

async function getPage(slug: string) {
  'use cache'
  cacheLife({ stale: 300, revalidate: 60, expire: 3600 })
  const { data } = await client.queries.page({ relativePath: `${slug}.md` })
  return data
}

草稿模式会绕过所有缓存（Next.js PR #77141已确认）。Next.js 15+将

fetch()

默认改为

no-store

——需显式启用缓存。

Step 8: Media Management

步骤8：媒体管理

Provider	Best For	Setup
Repo-based ( `tina: { mediaRoot, publicFolder }` )	Small sites, blogs	2 lines in config
Cloudinary ( `next-tinacms-cloudinary` )	Media-heavy	Package + API route + 3 env vars
S3/R2 ( `next-tinacms-s3` )	Enterprise	Package + IAM + bucket config

All providers integrate with

next/image

— add

images.remotePatterns

next.config.js

提供商	适用场景	配置方式
基于仓库（ `tina: { mediaRoot, publicFolder }` ）	小型站点、博客	配置文件中添加2行代码
Cloudinary（ `next-tinacms-cloudinary` ）	媒体密集型站点	安装包 + API路由 + 3个环境变量
S3/R2（ `next-tinacms-s3` ）	企业级站点	安装包 + IAM配置 + 存储桶设置

所有提供商均兼容

next/image

——需在

next.config.js

中添加

images.remotePatterns

配置。

Step 9: Build & Deploy

步骤9：构建与部署

json

{
  "scripts": {
    "dev": "tinacms dev -c \"next dev\"",
    "build": "tinacms build && next build",
    "start": "next start"
  }
}

Vercel env vars for Tina Cloud:

NEXT_PUBLIC_TINA_CLIENT_ID=<from app.tina.io>
TINA_TOKEN=<read-only token>
NEXT_PUBLIC_TINA_BRANCH=main

Vercel env vars for self-hosted:

TINA_PUBLIC_IS_LOCAL=false
GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxx
NEXTAUTH_SECRET=<random-secret>
KV_REST_API_URL=https://xxx.kv.vercel-storage.com
KV_REST_API_TOKEN=xxx

json

{
  "scripts": {
    "dev": "tinacms dev -c \"next dev\"",
    "build": "tinacms build && next build",
    "start": "next start"
  }
}

Tina Cloud的Vercel环境变量：

NEXT_PUBLIC_TINA_CLIENT_ID=<来自app.tina.io>
TINA_TOKEN=<只读令牌>
NEXT_PUBLIC_TINA_BRANCH=main

自托管的Vercel环境变量：

TINA_PUBLIC_IS_LOCAL=false
GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxx
NEXTAUTH_SECRET=<随机密钥>
KV_REST_API_URL=https://xxx.kv.vercel-storage.com
KV_REST_API_TOKEN=xxx

Workflow: Self-Hosted TinaCMS

工作流：自托管TinaCMS

Three pluggable components: database adapter (Vercel KV / MongoDB / custom), git provider (GitHub), auth provider (AuthJS/Clerk).

Read

references/nextjs16-react19-tinacms-reference.md § Self-Hosted TinaCMS

for

database.ts

configuration.

Choose self-hosting for: full control, cost sensitivity, open-source purity. Choose Tina Cloud for: quick setup, non-technical teams, built-in editorial workflow ($29-599/mo).

三个可插拔组件：数据库适配器（Vercel KV / MongoDB / 自定义）、Git提供商（GitHub）、认证提供商（AuthJS/Clerk）。

database.ts

配置示例请参考

references/nextjs16-react19-tinacms-reference.md § 自托管TinaCMS

。

选择自托管的场景：需要完全控制权、对成本敏感、追求开源纯粹性。 选择Tina Cloud的场景：快速搭建、面向非技术团队、内置编辑工作流（每月29-599美元）。

Common Gotchas

常见问题排查

Problem	Cause	Fix
`Cannot find module '../tina/__generated__/client'`	Wrong build order	`tinacms build && next build`
`Schema Not Successfully Built`	Frontend imports in `tina/config.ts`	Keep imports minimal
`Field name contains invalid characters`	Hyphens/spaces	Alphanumeric + underscores only
`GetCollection failed: template name not provided`	Missing `_template` in frontmatter	Add when using `templates` array
Visual editing not working	Multiple causes	Run debug checklist (Step 5)
`Expected workUnitAsyncStorage`	Turbopack prerendering bug	`--webpack` fallback
List items show "Item 0"	Missing `ui.itemProps`	Add meaningful label function
Reference dropdown slow/503	Large collections	Custom field with pagination
SCSS modules broken	TinaCMS esbuild issue	CSS modules or Tailwind
Mismatched package versions	Tina packages out of sync	Pin exact, RenovateBot grouping
Content stale after Git push	Database index not updated	Re-index from dashboard
iOS share sheet broken (iMessage, AirDrop)	`manifest.json` with `display: "standalone"`	Use `"display": "browser"` or omit manifest; `<meta name="theme-color">` handles tinting

问题	原因	解决方案
`Cannot find module '../tina/__generated__/client'`	构建顺序错误	执行 `tinacms build && next build`
`Schema Not Successfully Built`	`tina/config.ts` 中导入了前端代码	最小化导入依赖
`Field name contains invalid characters`	字段名称包含连字符/空格	仅使用字母数字+下划线
`GetCollection failed: template name not provided`	Frontmatter中缺少 `_template`	使用 `templates` 数组时添加该字段
可视化编辑功能失效	多种可能原因	执行步骤5中的调试清单
`Expected workUnitAsyncStorage`	Turbopack预渲染Bug	使用 `--webpack` 作为 fallback
列表项显示"Item 0"	缺少 `ui.itemProps`	添加有意义的标签函数
引用下拉框缓慢/503错误	集合数据量过大	使用带分页的自定义字段
SCSS模块失效	TinaCMS esbuild问题	使用CSS模块或Tailwind
包版本不匹配	Tina相关包版本不同步	固定精确版本，使用RenovateBot分组更新
Git推送后内容未更新	数据库索引未更新	从后台重新索引
iOS分享面板失效（iMessage、AirDrop）	`manifest.json` 中设置了 `display: "standalone"`	使用 `"display": "browser"` 或移除manifest；通过 `<meta name="theme-color">` 处理着色

Anti-Patterns

反模式

Don't	Do Instead
Single rich-text for page body	Blocks list with templates
Expose CSS values in schema	Enums mapped to Tailwind classes
Generic wrapper components	Purpose-built components accepting Tina types
`useTina` in Server Components	Client Component wrapper
Dependabot for Tina packages	RenovateBot with grouping
Inline media (base64)	External media provider
No block fallback	Default case in renderer
Hardcoded SEO	SEO object in schema with waterfall
Missing `ui.itemProps` on lists	Meaningful label functions
Sync `params` access	`await params` everywhere
Manifest `display: "standalone"` on non-PWA sites	`"display": "browser"` or omit; use `<meta name="theme-color">` for tinting

不推荐的做法	推荐替代方案
使用单个富文本字段作为页面主体	使用带模板的区块列表
在Schema中暴露CSS值	使用映射到Tailwind类名的枚举类型
使用通用包装组件	构建接收Tina类型的专用组件
在服务端组件中使用 `useTina`	使用客户端组件包装
使用Dependabot更新Tina包	使用带分组功能的RenovateBot
使用内联媒体（base64）	使用外部媒体提供商
区块未设置 fallback	在渲染器中添加默认处理分支
硬编码SEO内容	在Schema中添加SEO对象并使用优先级策略
列表字段缺少 `ui.itemProps`	添加有意义的标签函数
同步访问 `params`	所有地方使用 `await params`
非PWA站点设置 `manifest.display: "standalone"`	使用 `"display": "browser"` 或移除manifest；通过 `<meta name="theme-color">` 处理着色

Reference Files

参考文件

File	Purpose
`references/day0-2-checklist.md`	247-task checklist — follow task-by-task for complete setup
`references/nextjs16-react19-tinacms-reference.md`	Deep technical reference: schema patterns, field types, blocks, SEO, React 19, caching, self-hosting, custom components, deployment
`templates/tina-config-starter.ts`	Production `tina/config.ts` with reusable SEO fields, 5 block templates, 7 collections
`templates/page-server-client.tsx`	Complete server-client page pattern with metadata, static params, block renderer

文件	用途
`references/day0-2-checklist.md`	247项任务清单——完整搭建请逐项执行
`references/nextjs16-react19-tinacms-reference.md`	深度技术参考：Schema模式、字段类型、区块、SEO、React 19、缓存、自托管、自定义组件、部署
`templates/tina-config-starter.ts`	生产级 `tina/config.ts` 模板，包含可复用SEO字段、5个区块模板、7个集合
`templates/page-server-client.tsx`	完整的服务端-客户端页面模式，包含元数据、静态参数、区块渲染器

nextjs-tinacms

Original

Translation

Next.js 16 + React 19 + TinaCMS Skill

Next.js 16 + React 19 + TinaCMS 技能指南

Why This Stack

技术栈优势

Critical Knowledge

关键注意事项

Version Floors

最低版本要求

Workflow: New Project

工作流：新项目搭建

Step 1: Scaffold & Install

步骤1：项目初始化与安装

Step 2: Configure Package Management

步骤2：包管理配置

Step 3: Schema Design in
`tina/config.ts`

步骤3：
`tina/config.ts`
中的Schema设计

Step 4: Server-Client Page Pattern

步骤4：服务端-客户端页面模式

Step 5: Visual Editing & Draft Mode

步骤5：可视化编辑与草稿模式

Step 6: Complete SEO Implementation

步骤6：完整SEO实现

Step 7: Caching Strategy

步骤7：缓存策略

Step 8: Media Management

步骤8：媒体管理

Step 9: Build & Deploy

步骤9：构建与部署

Workflow: Self-Hosted TinaCMS

工作流：自托管TinaCMS

Common Gotchas

常见问题排查

Anti-Patterns

反模式

Reference Files

参考文件

nextjs-tinacms

Original

Translation

Next.js 16 + React 19 + TinaCMS Skill

Next.js 16 + React 19 + TinaCMS 技能指南

Why This Stack

技术栈优势

Critical Knowledge

关键注意事项

Version Floors

最低版本要求

Workflow: New Project

工作流：新项目搭建

Step 1: Scaffold & Install

步骤1：项目初始化与安装

Step 2: Configure Package Management

步骤2：包管理配置

Step 3: Schema Design in tina/config.ts

步骤3：tina/config.ts中的Schema设计

Step 4: Server-Client Page Pattern

步骤4：服务端-客户端页面模式

Step 5: Visual Editing & Draft Mode

步骤5：可视化编辑与草稿模式

Step 6: Complete SEO Implementation

步骤6：完整SEO实现

Step 7: Caching Strategy

步骤7：缓存策略

Step 8: Media Management

步骤8：媒体管理

Step 9: Build & Deploy

步骤9：构建与部署

Workflow: Self-Hosted TinaCMS

工作流：自托管TinaCMS

Common Gotchas

常见问题排查

Anti-Patterns

反模式

Reference Files

参考文件

Step 3: Schema Design in
`tina/config.ts`

步骤3：
`tina/config.ts`
中的Schema设计