tina-schema-sync

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

TinaCMS Schema Sync

TinaCMS Schema 同步

Regenerate TinaCMS artifacts locally and commit them after schema changes. This handles the hybrid deployment strategy where

tinacms build

is skipped on Vercel and artifacts are pre-committed.

通过重新生成本地TinaCMS工件并提交，来处理schema变更后的同步操作。这适用于混合部署策略，即在Vercel上跳过

tinacms build

，预先提交工件。

When to Use

适用场景

After editing
```
tina/config.ts
```
(adding fields, blocks, collections)
After upgrading
```
@tinacms/cli
```
When
```
pnpm tina:build
```
fails with "Unable to seed" (content references unknown block types)
When Vercel deploys succeed but new blocks don't render

编辑
```
tina/config.ts
```
之后（添加字段、块、集合）
升级
```
@tinacms/cli
```
之后
当
```
pnpm tina:build
```
因“Unable to seed”失败时（内容引用了未知的块类型）
当Vercel部署成功但新块无法渲染时

Prerequisites

前提条件

TinaCloud credentials in

.env.local

NEXT_PUBLIC_TINA_CLIENT_ID="..."
TINA_TOKEN="..."

If
```
.env.local
```
doesn't exist, run
```
./scripts/pull-secrets.sh
```
or copy from
```
.env.example
```
and fill in values from TinaCloud dashboard.

.env.local

中需包含TinaCloud凭证：

NEXT_PUBLIC_TINA_CLIENT_ID="..."
TINA_TOKEN="..."

如果
```
.env.local
```
不存在，运行
```
./scripts/pull-secrets.sh
```
，或从
```
.env.example
```
复制并填写TinaCloud控制台中的值。

Procedure

操作步骤

Step 1: Source credentials

步骤1：加载凭证

bash

source .env.local

Verify they're set:

bash

echo $NEXT_PUBLIC_TINA_CLIENT_ID | head -c 10
echo $TINA_TOKEN | head -c 10

bash

source .env.local

验证凭证已设置：

bash

echo $NEXT_PUBLIC_TINA_CLIENT_ID | head -c 10
echo $TINA_TOKEN | head -c 10

Step 2: Run the dev server to regenerate artifacts

步骤2：运行开发服务器以重新生成工件

bash

NEXT_PUBLIC_TINA_CLIENT_ID="$NEXT_PUBLIC_TINA_CLIENT_ID" \
TINA_TOKEN="$TINA_TOKEN" \
npx tinacms dev --noWatch --noTelemetry

Wait for "TinaCMS Dev Server is active" message, then stop the server (Ctrl+C or kill the process).

Why
tinacms dev
instead of
tinacms build
? The build command connects to TinaCloud for indexing. If the content already references new block types that TinaCloud's schema doesn't know about, the build fails with "Unable to seed." The dev server generates artifacts locally without requiring TinaCloud to re-index first.

bash

NEXT_PUBLIC_TINA_CLIENT_ID="$NEXT_PUBLIC_TINA_CLIENT_ID" \
TINA_TOKEN="$TINA_TOKEN" \
npx tinacms dev --noWatch --noTelemetry

等待出现“TinaCMS Dev Server is active”消息后，停止服务器（Ctrl+C或终止进程）。

为什么使用
tinacms dev
而非
tinacms build
？ build命令会连接到TinaCloud进行索引。如果内容已经引用了TinaCloud schema未知的新块类型，build会因“Unable to seed”失败。开发服务器会在本地生成工件，无需TinaCloud先重新索引。

Step 3: Verify artifacts were regenerated

步骤3：验证工件已重新生成

bash

git status tina/

You should see changes in:

```
tina/__generated__/client.ts
```
```
tina/__generated__/types.ts
```
```
tina/tina-lock.json
```

Also check

public/admin/

for changes.

bash

git status tina/

你应该看到以下内容的变更：

```
tina/__generated__/client.ts
```
```
tina/__generated__/types.ts
```
```
tina/tina-lock.json
```

同时检查

public/admin/

是否有变更。

Step 4: Verify new types exist

步骤4：验证新类型已生成

If you added a new block type (e.g.,

ContentTypes

bash

grep "ContentTypes" tina/__generated__/types.ts

如果你添加了新的块类型（例如

ContentTypes

）：

bash

grep "ContentTypes" tina/__generated__/types.ts

Step 5: Commit all three artifact groups

步骤5：提交所有三类工件

bash

git add tina/__generated__/ tina/tina-lock.json public/admin/
git commit -m "chore(tina): regenerate artifacts for [describe schema change]"

Critical:

tina/tina-lock.json

is the file TinaCloud reads to understand the schema on deploy. If you commit generated types but forget the lock file, deploys will fail or new block types will not render.

bash

git add tina/__generated__/ tina/tina-lock.json public/admin/
git commit -m "chore(tina): regenerate artifacts for [describe schema change]"

关键注意事项：

tina/tina-lock.json

是TinaCloud在部署时读取的schema文件。如果只提交了生成的类型但忘记提交锁文件，部署会失败或新块类型无法渲染。

Step 6: Push

步骤6：推送代码

bash

git push

TinaCloud picks up the lock file from the pushed commit and indexes the schema correctly.

bash

git push

TinaCloud会从推送的提交中获取锁文件，并正确索引schema。

Agentic Workflow & Vibe Coding

智能工作流与氛围编码

Iterative Syncing: Do not expect the schema to sync perfectly on the first try if there are complex field dependencies. If the dev server throws an error or artifacts don't generate, isolate the specific schema error, fix exactly one collection or field definition, and rerun the sync process until successful.
Vibe Coding: Create local, semantic commits for your working
```
tina/config.ts
```
changes before running the sync process, and then commit the generated artifacts separately once the sync succeeds. This ensures you can easily roll back if the generation fails.

迭代同步： 如果存在复杂的字段依赖，不要期望schema一次就能完美同步。如果开发服务器抛出错误或工件未生成，隔离具体的schema错误，仅修复一个集合或字段定义，然后重新运行同步过程直至成功。
氛围编码： 在运行同步过程之前，为你正在编辑的
```
tina/config.ts
```
变更创建本地语义化提交，然后在同步成功后单独提交生成的工件。这样如果生成失败，你可以轻松回滚。

Troubleshooting

故障排除

"Unable to seed content/pages/home.mdx"

The content file references a block type the cloud schema doesn't know about. This is the exact scenario this skill handles. Use

tinacms dev

(Step 2), not

tinacms build

内容文件引用了云schema未知的块类型。这正是本技能要处理的场景。使用

tinacms dev

（步骤2），而非

tinacms build

。

Dev server won't start

开发服务器无法启动

Check credentials are set (Step 1)
Check port 4001 isn't in use:
```
lsof -i :4001
```
Check port 6970 isn't in use:
```
lsof -i :6970
```

检查凭证是否已设置（步骤1）
检查端口4001是否被占用：
```
lsof -i :4001
```
检查端口6970是否被占用：
```
lsof -i :6970
```

Types generated but lock file unchanged

类型已生成但锁文件未变更

The schema change may not have been saved. Verify

tina/config.ts

was written before running the dev server.

可能schema变更未保存。在运行开发服务器之前，确认

tina/config.ts

已保存。

Checklist

检查清单

Before pushing, verify:

```
tina/__generated__/client.ts
```
has changes
```
tina/__generated__/types.ts
```
has new type definitions
```
tina/tina-lock.json
```
has changes
```
public/admin/
```
updated (if applicable)
All four are staged and committed together

推送前，请验证：

```
tina/__generated__/client.ts
```
有变更
```
tina/__generated__/types.ts
```
有新的类型定义
```
tina/tina-lock.json
```
有变更
```
public/admin/
```
已更新（如适用）
以上四类文件均已暂存并一起提交