datocms-cda

DatoCMS Content Delivery API スキル

@datocms/cda-client を使用して DatoCMS CDA（読み取り専用の GraphQL）をクエリするエキスパートです。手順に沿って進めてください。

Step 1：コンテキストの検出

コンテキストがすでに確立されている場合は、広範な検出を省略してください。必要な場合にのみ再調査します。

プロジェクトのセットアップを確認します。

1. package.json で @datocms/cda-client を確認します。インストールされていない場合は、npm install @datocms/cda-client を実行します。

2. 既存の executeQuery または rawExecuteQuery のインポートを探し、使用パターンを把握します。

3. .env* ファイル（.env.example を含む）で *DATOCMS*TOKEN* 変数を確認し、その名前を再利用します。スターターで使われる変数：DATOCMS_PUBLISHED_CONTENT_CDA_TOKEN、DATOCMS_DRAFT_CONTENT_CDA_TOKEN。

4. フレームワーク（Next.js、Astro、Remix、Nuxt、SvelteKit）を確認し、サーバーとクライアントのどちらでクエリするかを判断します。公開読み取り専用トークンを使う場合を除き、トークンをブラウザーに公開しないでください。

5. 型生成のセットアップを確認します。

   • gql.tada： 依存関係に gql.tada があり、initGraphQLTada の呼び出しがある（通常は lib/datocms/graphql.ts）
   • graphql-codegen： devDependencies に @graphql-codegen/cli があり、graphql.config.ts がある
   • コンテキストの確認のみです。既存のセットアップに合わせてください。型生成のセットアップを提案しないでください。

CDA に必要なのは読み取り専用トークンのみです。 DATOCMS_API_TOKEN を CMA にも使用している場合は、CDA 用に別の読み取り専用トークンを使うことを推奨します。

Step 2：リファレンスの読み込み

依頼が明確な場合は、そのまま進めてください。references/ から関連するリファレンスのみを読みます。

タスク	リファレンス
基本（スラッグ／ID での取得、単一インスタンス、コレクション、メタ）	references/querying-basics.md
フィルタリング（フィールド／メタフィルター、AND／OR、深い階層、アップロード）	references/filtering.md
ページネーションと並べ替え（first／skip、自動、ソート、ツリー）	references/pagination-and-ordering.md
ローカライズ（ローカライズされたフィールド、フォールバック、全ロケールの値）	references/localization.md
モジュラーコンテンツ（ブロック、フラグメント、ネストされたブロック）	references/modular-content.md
構造化テキスト（DAST の値／ブロック／リンク、レンダリング）	references/structured-text.md
画像とメディア（responsiveImage、imgix、プレースホルダー、焦点、動画）	references/images-and-videos.md
SEO とメタ（_seoMetaTags、ファビコン、globalSeo、OG タグ）	references/seo-and-meta.md
下書き／プレビュー、厳格モード、キャッシュタグの読み取り、CDN、環境、Content Link のクエリオプション	references/draft-caching-environments.md
型生成（gql.tada、graphql-codegen、スキーマ型、型付きクエリ）	references/type-generation.md
gql.tada のフラグメント規則（マスキング、合成、ページクエリ）	references/fragment-patterns.md
クライアントのセットアップ／ラッパー、オプション、トークンの権限、ApiError の処理、429／複雑度／CDN の診断、カスタムスカラー	references/client-and-config.md

横断的な項目：

• ローカライズされたフィルタリング → references/localization.md
• モジュラーコンテンツを含む構造化テキスト → references/modular-content.md
• ブロック内の画像 → references/images-and-videos.md
• フィルター済みコレクションのページネーション → references/pagination-and-ordering.md
• 複雑なネスト → 複雑度コストについては references/pagination-and-ordering.md
• gql.tada プロジェクトでのフラグメントの記述／拡張 → references/fragment-patterns.md

Step 3：コード生成に関する必須ルール

コードを記述する際は、Step 4 のすべてのチェックも適用してください。

クライアントの使用

• デフォルト： @datocms/cda-client の executeQuery（またはリポジトリに既存のラッパーがあれば、それを使用）
• レスポンスヘッダー（キャッシュタグ）が必要な場合にのみ、rawExecuteQuery を使用します。

GraphQL クエリ

• テンプレートリテラル文字列として記述します（プロジェクトが TypedDocumentNode／gql.tada を使っている場合を除く）。文字列クエリは unknown を返すため、型を指定します：executeQuery<Result>(query, …)
• 必要なフィールドのみを要求し、過剰にデータを取得しないでください。
• 宣言では DatoCMS のカスタムスカラーを使用します（$first: IntType、$id: ItemId）。
• プロジェクトの規約に合わせてください。/* GraphQL */ のプレフィックスを付けると、エディターのハイライト／検証が有効になります。

const query = /* GraphQL */ `query { ... }`

エラー処理

• カスタムの再試行ロジックは使用しないでください。 レート制限は autoRetry が処理します。

ステップ 4：確認

最終的なコードを提示する前に、次の項目を確認してください。

1. トークン — 環境変数を使用する（ハードコードしない）。読み取り権限を確認する
2. エラー処理 — 境界で ApiError を捕捉する
3. ページネーション — 500 件以上のレコードがある場合は、executeQueryWithAutoPagination を使用する
4. ドラフトモード — includeDrafts が意図した設定であることを確認する（本番環境で未公開コンテンツを公開しない）
5. excludeInvalid — 安定したスキーマにはこれを推奨します。スキーマを変更する場合は、代わりに filter: { _isValid: { eq: true } } を使用する
6. 型安全性 — エラーを無視するために as / as unknown as を使用しない
7. インポート — CDA は @datocms/cda-client からインポートする。型生成が設定されている場合は、生成された GraphQL ヘルパーを維持する。React レンダラーはサブパス（react-datocms/structured-text）からインポートする。ルートの react-datocms はオプションのピア依存関係 @mux/mux-player-react を静的にインポートします
8. 変数 — 動的な値はすべて GraphQL 変数を使用し、文字列補間は行わない
9. 構造化テキスト — 関連するすべてのサブフィールド（value、blocks、links、inlineBlocks）を含める。省略するとデータが通知なしに失われます。それぞれに専用のコールバックを使用してレンダリングする（inlineBlocks → renderInlineRecord ではなく renderInlineBlock）
10. Fetch の統合 — フレームワーク標準の fetch、タグ付け、カスタム処理が必要ですか？ buildRequestHeaders() / buildRequestInit() を使用する
11. 型生成 — gql.tada または graphql-codegen を使用していますか？ プロジェクトの graphql() 関数を使用し、スカラーのマッピングを確認する
12. gql.tada フラグメント — 合成配列には、すべての ...Fragment の展開を反映する。プロジェクトのマスキング設定に従う（references/fragment-patterns.md を参照）

スキル間のルーティング

このスキルでは、GraphQL CDA による読み取りを扱います。次の条件に該当する場合は、対応するスキルに案内してください。

条件	案内先
DAST の構造または検証	datocms-structured-text — ドキュメントモデル
DAST の走査・編集、Markdown/HTML のインポート、または形式のエクスポート	datocms-structured-text — 編集または変換
コンテンツ、スキーマ、アップロード、Webhook の変更、スクリプト（REST クエリを含む）	datocms-cma
アプリの接続：ドラフトモードのエンドポイント、Web プレビュー、Content Link オーバーレイ、リアルタイムサブスクリプション、キャッシュタグの無効化（再検証、CDN のパージ）	datocms-frontend-integrations
プラグインの構築	datocms-plugin

この連携のクエリ側は引き続きここで扱います：includeDrafts、contentLink / baseEditingUrl / _editingUrl、rawExecuteQuery による x-cache-tags の読み取り。

DAST のタスクに限り、専門スキルを読み込んでください。通常の GraphQL 選択はここで扱います。関連するスキルの参照資料が見つからない場合は、datocms/agent-skills からそのスキルをインストールするか、バンドル全体を更新してください。