nextjs-tinacms

Next.js 16 + React 19 + TinaCMS + Vercel

次の構成に特化しています：Next.js App Router + TinaCMS + Tina Cloud + Vercel + Tailwind CSS 4 + shadcn/ui。

2 つのワークフロー：新規プロジェクト（ゼロから構築）またはCMS の追加（既存の Next.js 15/16 プロジェクトに統合）。

スタック

技術	バージョン	主な機能
Next.js	16.x	Turbopack がデフォルト、"use cache"、proxy.ts、非同期 params
TinaCMS	3.x	Git ベースの CMS、クリックして編集できるビジュアル編集、GraphQL スキーマ API、ESM 専用
React	19.x	サーバーコンポーネント、Actions、use()、useEffectEvent
Tailwind CSS	4.x	CSS ファーストの設定（@import "tailwindcss"）、JS 設定は不要
shadcn/ui	CLI v4	コピー＆ペーストできるコンポーネント、npx shadcn create、tw-animate-css
Vercel	--	デプロイ先。@vercel/analytics、@vercel/speed-insights、Deploy Hooks
Tina Cloud	--	デフォルトの CMS バックエンド。無料プラン（2 ユーザー）、Team Plus 以上で編集ワークフローを利用可能

クイックスタート

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

確認：tinacms dev を実行し、http://localhost:3000/admin/index.html を開きます。

ローカル開発はローカルのみモードで実行されます -- コンテンツはファイルシステムから直接読み書きされるため、Tina Cloud への接続は不要です。本番ビルドでは、Vercel 上の NEXT_PUBLIC_TINA_CLIENT_ID と TINA_TOKEN 環境変数を介して Tina Cloud に接続します。

重要な知識

1. サーバーとクライアントの分離は必須です。 useTina() には "use client" が必要です。編集可能なページにはすべて、サーバーコンポーネント（データ取得）とクライアントコンポーネント（ビジュアル編集のラッパー）が必要です。
2. ビルドの順序が重要です。 常に "build": "tinacms build && next build" とします。順序を誤ると Cannot find module '../tina/__generated__/client' が発生します。
3. TinaCMS のバージョンは厳密に固定してください。 キャレット範囲は使わないでください。UI アセットの CDN との不整合が発生します。パッケージグループ（RenovateBot または Dependabot）を使って tinacms と @tinacms/* のバージョンを揃えてください。
4. tina/__generated__/ は Git の対象外にしてください。 コミットが必要なのは tina-lock.json のみです。__generated__/ フォルダーは tinacms build によって再生成されます。
5. TinaCMS 3.x は ESM 専用です。 設定ファイルでは import 構文を使う必要があります。package.json に "type": "module" を設定するか、.ts 拡張子を使用してください。
6. Next.js 16 の非同期 params。 すべての page.tsx、layout.tsx、route.ts で params を await する必要があります -- 同期アクセスは完全に廃止されました。
7. proxy.ts は middleware.ts に代わるものです。 プロジェクトのルートに配置し、proxy 関数をエクスポートします。Node.js ランタイムのみで実行されます。Codemod：npx @next/codemod@canary middleware-to-proxy .
8. セキュリティ：@tinacms/cli >= 2.1.8 が必要です。 CVE-2026-28792（重大、CVSS 9.6）-- 古いバージョンには、CORS とパストラバーサルを利用したドライブバイ攻撃のリスクがあります。
9. 開発コマンドは tinacms dev -c "next dev" です。 next dev のみで実行しないでください -- ローカル GraphQL サーバーが起動しません。

最低バージョン

構築前に、最新の安定バージョンを確認してください（npm view <pkg> version）。

パッケージ	最低バージョン	理由
next	>= 16.0.10	セキュリティパッチ
tinacms	>= 3.3.x	ビジュアルセレクター、ESM 専用、最新のスキーマ API
@tinacms/cli	>= 2.1.8	CVE-2026-28792 の修正
react / react-dom	>= 19.0.x	サーバーコンポーネント、Actions（useEffectEvent には 19.2.x）
tailwindcss	>= 4.x	CSS ファーストの設定（v3.4.x も使用可能）
Node.js	>= 20.9.0	Next.js 16 の要件

主なインポート

インポート	インポート元	用途
defineConfig	tinacms	tina/config.ts でのスキーマ設定
useTina	tinacms/dist/react	クライアントコンポーネントでのライブ編集
tinaField	tinacms/dist/react	クリックして編集するためのデータ属性
TinaMarkdown	tinacms/dist/rich-text	リッチテキストのレンダリング
client	@/tina/__generated__/client	GraphQL クエリ（自動生成）

コレクション

プロジェクトのニーズに応じて追加します。

コレクション	種類	必要な場合
pages	フォルダー＋ブロック	常に
global	シングルトン	常に（サイト設定、SEO のデフォルト）
navigation	シングルトン	常に（フッターのリンクを含めることもできます）
posts	フォルダー	サイトにブログがある場合
authors	フォルダー	サイトにブログがある場合
footer	シングルトン	フッター専用のコレクションが必要な場合
notFound	シングルトン	任意

よくあるタスク

新しいブロックを作成する

t ina/config.ts の blocks フィールドにある templates 配列に、テンプレートオブジェクトを追加します。すべてのブロックに ui.defaultItem が必要です。任意で、ビジュアルセレクターのサムネイル用に ui.previewSrc を設定できます。

ページでビジュアル編集を有効にする

1. サーバーコンポーネントで Tina クライアントから { data, query, variables } を取得します
2. クライアントコンポーネントで、それらの props を使って useTina() を呼び出します
3. DOM 要素に data-tina-field={tinaField(data.page, 'fieldName')} を追加します

キャッシュを有効にする

next.config.ts で cacheComponents: true を設定し、cacheLife() のプリセットである seconds、minutes、hours、days、weeks、max とともに "use cache" ディレクティブを使用します。

Vercel にデプロイする

1. ビルドコマンド：tinacms build && next build
2. Vercel の環境変数を設定します：NEXT_PUBLIC_TINA_CLIENT_ID、TINA_TOKEN、NEXT_PUBLIC_TINA_BRANCH
3. @vercel/analytics と @vercel/speed-insights をインストールし、ルートレイアウトで <Analytics /> と <SpeedInsights /> をレンダリングします
4. コンテンツ変更時の再ビルド用に Deploy Hook を設定します
5. Vercel Team Environment Variables を使用して、プレビュー環境と本番環境でキーを共有します

セルフホストする具体的な理由がプロジェクトにない限り、必ず Tina Cloud を使用してください。 セルフホストの代替手段については、references/deployment.md を参照してください。

Claude Code の自動化

Day 0 の早い段階で .claude/settings.json に設定します。

{
  "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 サーバー：

• claude mcp add context7 -- npx -y @upstash/context7-mcp@latest -- TinaCMS／Next.js／React／Tailwind の最新ドキュメント
• claude mcp add playwright -- npx -y @anthropic-ai/mcp-server-playwright@latest -- ブラウザーでビジュアル編集をテスト

繰り返し行うタスクには、プロジェクトレベルのスキルの作成を検討してください：

• /new-block -- ブロックテンプレート、コンポーネント、レンダラーマッピングをひな形から作成
• /tinacms-check -- ui.itemProps の不足、壊れた tinaField、バージョンのずれがないかスキーマを監査

エージェント型ワークフローとバイブコーディング

• 反復的な構築： 最初の試行で CMS 連携が完璧になることを期待しないでください。スキーマとビジュアル編集用のラッパーを作成し、ローカルで接続をテストし（tinacms dev）、データ取得やレンダリングに関するエラーを特定し、一度に変更するフィールドまたはクエリを 1 つだけにして、クリックして編集する体験がシームレスになるまで更新を繰り返します。
• バイブコーディング： 複雑なブロックテンプレートの追加や Vercel へのデプロイを試みる前に、動作する Next.js ページと Tina のスキーマ設定をローカルでコミットします。これらのコミットに tina-lock.json が含まれていることを確認してください。

参考ファイル

ファイル	読むタイミング
references/schema-design.md	コレクション、ブロック、フィールド、コンテンツフックの設計
references/visual-editing.md	サーバー／クライアントの分割、ドラフトモード、クリックして編集する機能のデバッグ
references/seo-meta.md	メタデータ、JSON-LD、OG タグ、サイトマップ、RSS
references/deployment.md	Tina Cloud とセルフホスト、メディアプロバイダー、環境変数
references/setup-checklist.md	段階的な実装チェックリスト（MVP／仕上げ／包括的）
templates/tina-config-starter.ts	5 つのブロックテンプレートを含む、本番用 tina/config.ts
templates/page-server-client.tsx	メタデータと静的パラメーターを含む、サーバー／クライアントのページパターン