datocms-frontend-integrations

DatoCMS フロントエンド統合スキル

共有フロントエンド統合バンドルです。単一機能または複数機能を対象とした実装、部分的なパッチ適用、フレームワークの比較、関連リファレンスの読み込みに対応します。

Structured Text コンポーネントとレンダラーのコールバックを扱います。これには、renderBlock に渡される解決済みの record も含まれます。ドキュメントスペシャリストを読み込むのは、ドキュメントの確認、変換、形式変換、検証が依頼された場合のみです。通常のレンダラーの例では、関連ドキュメントを読み込む必要はありません。

プレースホルダーが残っている場合は scaffolded と報告してください。実装が未解決のプロジェクト固有の値に依存しなくなった場合にのみ production-ready と報告してください。

ステップ 1：コンテキストを検出する（非表示）

コンテキストが確立済みの場合はスキップしてください。過去のコンテキストから質問に回答できない場合にのみ、再確認してください。

次の項目を非表示で確認します。

1. フレームワーク — package.json を確認します。next → Next.js App Router、nuxt → Nuxt、@sveltejs/kit → SvelteKit、astro → Astro、@remix-run/* または @react-router/dev → Remix / React Router framework mode（React のリファレンスを使用し、既存の loader / route モジュールにパッチを適用）、または React / Vue / その他を推定します
2. UI スタック — Dato のレンダリングライブラリを確認します。React（react-datocms）、Vue（vue-datocms）、SvelteKit / Svelte（@datocms/svelte）、React を使わない Astro（@datocms/astro）
3. 既存の Dato ヘルパー — @datocms/cda-client、クエリラッパー、画像 / Structured Text ヘルパー、環境変数
4. 既存の統合マーカー — ドラフトモードのエンドポイント、preview-links、Content Link、リアルタイムサブスクリプション、キャッシュタグの転送、検索ルート、robots / sitemap
5. ファイル構成 — src/ またはルート直下のアプリディレクトリ。リファレンスでは src/ パスを使用します。src/ のない Next.js → app/、lib/datocms/。SvelteKit と Astro のデフォルトは src/（kit.files.src、srcDir）です。Nuxt のリファレンスではルート直下の lib/、composables/ を示しています（srcDir を基準とする ~）。Nuxt 4 → app/ があればその中、なければルート直下です。server/ はルート直下に置きます（references/nuxt.md › File Structure）
6. スターター規約のマーカー（gql.tada プロジェクト）— package.json 内の gql.tada、lib/datocms/gqlUrlBuilder/ フォルダー、プロジェクト内の <StructuredText /> を包む <Text> ラッパー、block / inline-record / link-to-record コンポーネントの隣に配置された fragments.ts。これらが存在する場合、プロジェクトは references/url-builders.md + datocms-cda/references/fragment-patterns.md のパターンに従っています。

停止条件

• フレームワークが不明 → ユーザーに確認する
• 統合が存在する → デフォルトでは既存の実装を確認してパッチを適用する
• 全面的な置き換えについて確認するのは、明らかに互換性がない、壊れている、またはユーザーが明示的に書き換えを依頼した場合のみ

ステップ 2：分類して振り分ける

次のカテゴリに分類します。

カテゴリ	選択するタイミング
ドラフトモードの設定	ドラフト Cookie、有効化 / 無効化エンドポイント、ドラフト CDA トークンの切り替え
Web プレビューの設定	Preview-links エンドポイント、ルートマッピング、Visual タブのサポート
レスポンシブ画像	Dato の画像レンダリングヘルパーまたはコンポーネントの選択
Structured Text のレンダリング	Structured Text のクエリ形状またはレンダラーの接続
動画プレーヤー	Dato / Mux 動画再生の統合
SEO とメタタグ	_seoMetaTags、ファビコンタグ、canonical の接続
リアルタイム更新	ライブプレビューサブスクリプションまたは <QueryListener /> の接続
ビジュアル編集 / Content Link	クリックして編集するオーバーレイと stega 対応レンダリング
サイト内検索	React / Vue ウィジェットまたは低レベルの Search API 接続
Robots とサイトマップ	robots.txt、sitemap ルート、クローラー対応ルール
キャッシュタグ	詳細な無効化またはタグ転送のパターン

複数のカテゴリが該当する場合があります。

ビジュアル編集 = ドラフトモード + Web プレビュー + Content Link。リアルタイム機能は依頼された場合のみ含めます。Content Link のみを選ぶのは、ユーザーがオーバーレイ / stega を単独で求めている場合に限ります。バンドルのデフォルト、Vercel との競合ルール、プラグインへの引き継ぎフィールドについては、references/visual-editing-concepts.md を参照してください。

質問

デフォルトでは質問しません。

リポジトリから回答できない問題で作業が止まった場合に限り、質問してください。

• プレビュー／サイトマップ用のモデルとルートのマッピングが不足している
• キャッシュプロバイダーまたはパージアダプターの選択が不足している
• レンダラーが複数あり、誤ったレンダラーにパッチを当てるリスクがある

それ以外の場合は作業を進め、未解決の値があれば、作業を止めずにその旨を伝えてください。

ステップ 3：リファレンスを読み込む

references/から関連するセクションを読みます。長いファイルは、まず内容をプレビューしてください。

キャッシュタグを扱う場合は、既存のクエリーヘルパーへの対象を絞ったパッチであっても、選択したフレームワークのリファレンスにある**キャッシュタグ（オプション）**セクションを読みます。Core セクションだけでは、きめ細かな無効化については説明されていません。手動で CDN の収集／パージを行う場合は、references/cache-tag-adapters.mdも読み込みます。Next.js のクエリー ID マッピングまたはネイティブキャッシュプロバイダーの場合は、このアダプターファイルを読み込む必要はありません。

コンポーネントの概念リファレンス

まず概念ファイル（共有 GraphQL クエリー、フィールド定義、パターン）を読み、次にフレームワーク固有のファイルでコンポーネントの API／props を確認します。

カテゴリー	概念ファイル
レスポンシブ画像	references/image-concepts.md
ビデオプレーヤー	references/video-player-concepts.md
SEO とメタタグ	references/seo-concepts.md
リアルタイム更新	references/realtime-concepts.md
サイト検索	references/site-search-concepts.md

セットアップの基礎

複数の機能を組み合わせたセットアップでは、以下を読み込みます。

• references/draft-mode-concepts.md
• フレームワークのリファレンスを1つ：
  • references/nextjs.md
  • references/nuxt.md
  • references/sveltekit.md
  • references/astro.md
• 任意の概念リファレンス：
  • references/web-previews-concepts.md
  • references/content-link-concepts.md
  • references/realtime-concepts.md

React のリファレンス

カテゴリー	リファレンスファイル
レスポンシブ画像	references/react-image.md
構造化テキストのレンダリング	references/react-structured-text.md
ビデオプレーヤー	references/react-video-player.md
SEO とメタタグ	references/react-seo.md
リアルタイム更新	references/react-realtime.md
ビジュアル編集／コンテンツリンク	references/react-content-link.md
サイト検索	references/react-site-search.md

Vue のリファレンス

カテゴリー	リファレンスファイル
レスポンシブ画像	references/vue-image.md
構造化テキストのレンダリング	references/vue-structured-text.md
ビデオプレーヤー	references/vue-video-player.md
SEO とメタタグ	references/vue-seo.md
リアルタイム更新	references/vue-realtime.md
ビジュアル編集／コンテンツリンク	references/vue-content-link.md
サイト検索	references/vue-site-search.md

Svelte のリファレンス

カテゴリー	リファレンスファイル
レスポンシブ画像	references/svelte-image.md
構造化テキストのレンダリング	references/svelte-structured-text.md
ビデオプレーヤー	references/svelte-video-player.md
SEO とメタタグ	references/svelte-seo.md
リアルタイム更新	references/svelte-realtime.md
ビジュアル編集／コンテンツリンク	references/svelte-content-link.md

Svelte／SvelteKit のサイト検索作業では、references/site-search-api.mdを使用します。

Astro のリファレンス

カテゴリー	リファレンスファイル
レスポンシブ画像	references/astro-image.md
構造化テキストのレンダリング	references/astro-structured-text.md
SEO とメタタグ	references/astro-seo.md
リアルタイム更新	references/astro-realtime.md
ビジュアル編集／コンテンツリンク	references/astro-content-link.md

Astro のサイト検索作業では、references/site-search-api.mdを使用します。Astro のビデオには、Mux の Web コンポーネントを直接使用します（references/video-player-concepts.md › React インテグレーションを使わない Astro）。プロジェクトですでに React を使用している場合は、React インテグレーションを使用します。

gql.tada スターター規約のリファレンス

プロジェクトで gql.tada を使用しており、タスクでブロック、インラインレコード、レコードへのリンク、ルーティング可能なモデル、またはページクエリを追加・拡張する場合に読み込みます。

• references/url-builders.md — モデルごとの URL ビルダーと buildUrlFromGql() ディスパッチャー
• ../datocms-cda/references/fragment-patterns.md — マスキングの規律、readFragment() の境界、フラグメントの構成、ページクエリのルール

プロジェクトで通常の executeQuery 文字列や、手動で形状を定義した型を使うコード生成を使用している場合は読み込まないでください。これらのパターンは適用されません。

汎用検索およびクロールのリファレンス

フレームワークに依存しない場合、ウィジェットベースではない場合、またはクローラー固有の場合に読み込みます。

• references/site-search-api.md
• references/robots-and-sitemaps.md

ステップ 4：コードを生成または修正する

読み込んだリファレンスと共通ルールに従います。

ワークフロールール

• 既存の抽象化を尊重し、デフォルトではその場で修正します
• 現在のコードが使用できない場合を除き、全面的な書き換えではなく、対象を絞った変更を行います

セキュリティと環境のルール

• すべてのシークレットは環境変数から取得します
• 新しい実行時環境変数は、.env.example とリポジトリ内のローカルな Git 無視対象の環境ファイルにプレースホルダーのエントリーを追加します。既存の名前を再利用し、実際の値は決してコミットしません。CLI/CMA トークンは対象外です（CLI は login と link で認証します）
• 下書きモードまたはプレビューリンクのフローで必要な場合は、専用のプレビュー／Webhook シークレット環境変数を検証します。既存のリポジトリ名がある場合は維持します
• リダイレクトの検証には isRelativeUrl() を使用します
• 下書きモードを無効にするエンドポイントで認証を必須にしないでください

クエリラッパーのルール

• 共通ヘルパー：フレームワークリファレンスの ## Core クエリヘルパー。下書きモードが存在するまでは公開済みコンテンツのみを対象とするバリアントを使用します。ドキュメント型はリポジトリに合わせます（gql.tada の場合は TadaDocumentNode、コード生成では TypedDocumentNode、それ以外では query: string）。クライアントオプション：client-and-config.md
• 下書きを考慮したクエリのために、includeDrafts オプションを追加または維持します
• このオプションに応じて、公開用 CDA トークンと下書き用 CDA トークンを切り替えます
• タスクでスキーマ作業中に無効なレコードが明示的に必要とされない限り、下書き対応ラッパーのパターンでは excludeInvalid: true をデフォルトにします
• リポジトリに既存の contentLink モード（'v1' または 'vercel-v1'）がある場合は、下書きまたはビジュアル編集のコンテキストでのみ有効にします
• クエリで _editingUrl を選択する場合は、公開コンテンツの読み取りも含め、必ず公開用の baseEditingUrl を指定します

フレームワークのルール

• 検出されたフレームワークのネイティブな環境変数 API とリダイレクト API を使用します
• サブパスインポート：@datocms/astro/*、react-datocms/<feature>（ルートのバレルにはオプションの @mux/mux-player-react が必要です）
• メモリ内の別フレームワークのパターンではなく、読み込んだリファレンスにあるフレームワークに適したコンポーネントまたはヘルパー API を使用します

TypeScript のルール

• as unknown as は使用しません
• 不要な型アサーションは避けます
• 型のみのインポートには import type { ... } を優先します
• 可能な場合は TypeScript の型推論に任せます

依存関係のルール

• タスクで本当に必要な場合に限り、不足しているパッケージをインストールします
• 生成されたコードがインポートするパッケージは、Dato パッケージがすでに依存関係として取り込んでいる場合でも、直接の dependencies に追加します（厳格な pnpm のため）。@types/* と datocms CLI は devDependencies に追加します
• React の動画には @mux/mux-player-react を使用します
• Vue または Svelte の動画には @mux/mux-player を使用します
• React／Vue のウィジェットベースのサイト検索には @datocms/cma-client-browser を使用します

検索とクロールの安全ルール

• 明示的な検索インデックス ID を使用します
• ブラウザーでは、権限を最小限に抑えた公開検索トークンを使用します
• サイトマップの出力は、設定された公開ドメインのみに限定します
• Dato クローラーの Allow ルールは、すべてに一致する Disallow: / より前に配置します

顧客固有の値（ルートマッピング、プロバイダーの詳細、インデックス ID）が未解決のまま残る場合は、明確なプレースホルダーを残し、不足している入力を明示してください。作業が完全に準備できているかのように提示しないでください。

ステップ 5：検証

references/verification-checklists.md を読み込み、実際に行った作業に関連するセクションだけを確認します。

最低限、以下を検証します。

• セキュリティ、トークンの取り扱い、リダイレクトの検証、環境変数の使用
• クエリの形式、ラッパーのオプション、フレームワーク固有のコンポーネント API
• 依存関係の選択とインポートパス
• 下書き専用の動作が下書き専用のまま維持されていること
• 残っているプレースホルダーや顧客固有のマッピングがあれば、明確に明記されていること

スキル間の振り分け

DAST の構造／検証 → document model；コンテンツの走査／変換 → editing；Markdown／HTML のインポートおよびフレームワークに依存しないエクスポート → conversion。これらはすべて datocms-structured-text が管理します。該当する作業でのみ読み込みます。コンポーネントの配線とクエリ／レンダリングのアダプターは引き続きこちらで扱います。参照先の兄弟スキルが見つからない場合は、datocms/agent-skills からそのスキルをインストールするか、バンドル全体を更新してください。

作業がこのバンドルの得意分野から外れる場合は、関連スキルを使用します。

条件	振り分け先
複数の手順を案内するセットアップ、新しいサイトの構築、またはユーザーが必要な成果を判断できない場合	datocms-setup
CDA 向けの GraphQL クエリの作成または最適化	datocms-cda
gql.tada のフラグメント作成の手法（マスキング、合成、ページクエリ）	datocms-cda（../datocms-cda/references/fragment-patterns.md）
REST 経由でのプログラムによるコンテンツ管理、スキーマの変更、移行スクリプト、アクセス制御、Webhook の作成	datocms-cma
DatoCMS プラグインの構築	datocms-plugin