DatoCMS Content Delivery API Skill

Expert at querying DatoCMS CDA (read-only GraphQL) using @datocms/cda-client. Follow steps in order.

Step 1: Detect Context

If context already established, skip broad detection. Re-inspect only when needed.

Examine project setup:

1. Read package.json for @datocms/cda-client. Not installed? npm install @datocms/cda-client

2. Find existing executeQuery or rawExecuteQuery imports to understand usage patterns.

3. Check .env, .env.local for DatoCMS API token:
   • DATOCMS_CDA_TOKEN
   • DATOCMS_READONLY_TOKEN
   • DATOCMS_API_TOKEN
   • NEXT_PUBLIC_DATOCMS_CDA_TOKEN

4. Check framework (Next.js, Astro, Remix, Nuxt, SvelteKit) to determine server vs client queries. Don’t expose tokens to browser unless using public read-only token.

5. Check type generation setup:
   • gql.tada: gql.tada in dependencies + initGraphQLTada call (typically lib/datocms/graphql.ts)
   • graphql-codegen: @graphql-codegen/cli in devDependencies + graphql.config.ts
   • Context only — match existing setup. Don’t suggest setting up type generation.

CDA only needs read-only token. If DATOCMS_API_TOKEN is also used for CMA, better suggesting a separate read-only token for CDA.

Step 2: Understand Task

Classify task:

Clear request? Proceed directly.

Step 3: Load References

Read relevant references from references/. Always load core client reference, then only relevant files.

Always load:

• references/client-and-config.md — client setup, options, error handling, limits, scalars

Load per category:

Cross-cutting:

• Filtering localized → references/localization.md
• Structured text with modular content → references/modular-content.md
• Images in blocks → references/images-and-videos.md
• Paginating filtered collection → references/pagination-and-ordering.md
• Complex nesting → references/pagination-and-ordering.md for complexity costs
• Writing/extending fragments in a gql.tada project → references/fragment-patterns.md

Step 4: Mandatory Rules to Generate Code

Client Usage

• Default: executeQuery from @datocms/cda-client (or repo’s existing wrapper around it)
• Use buildRequestHeaders() / buildRequestInit() for framework fetch integration, tagging, custom plumbing
• Use executeQueryWithAutoPagination to fetch 500+ records
• Use rawExecuteQuery only if response headers are needed (cache tags)
• Store API token in env variable — never hardcode

GraphQL Queries

• Write as template literal strings (unless project uses TypedDocumentNode / gql.tada)
• Use GraphQL variables for all dynamic values — no string interpolation
• Request only needed fields — don’t over-fetch
• Use DatoCMS custom scalars in declarations ($first: IntType, $id: ItemId)
• Prepend template string with /* GraphQL */ (comment-tagged templates) for syntax highlighting

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

Structured Text

• Query all relevant sub-fields (value, blocks, links, inlineBlocks) — omitting causes silent data loss

Error Handling

• Catch ApiError from @datocms/cda-client at appropriate boundaries
• No custom retry logic — autoRetry handles rate limits

TypeScript

• Follow strictness: no as unknown as, no unnecessary as
• Let TypeScript infer types
• Use import type { ... } for type-only imports

Step 5: Verify

Before presenting final code:

1. Token — env variable, read permissions
2. Error handling — ApiError caught at boundaries
3. Pagination — 500+ records? use executeQueryWithAutoPagination
4. Draft mode — includeDrafts intentional (not exposing unpublished in prod)
5. excludeInvalid — recommend for stable schemas. Changing schema? use filter: { _isValid: { eq: true } } instead
6. Type safety — no as to silence errors
7. Imports — CDA from @datocms/cda-client; keep generated GraphQL helpers if type-gen wired
8. Variables — all dynamic via GraphQL variables, no interpolation
9. Structured text — all relevant sub-fields included
10. Fetch integration — framework-native fetch? use buildRequestHeaders() / buildRequestInit()
11. Type generation — gql.tada or graphql-codegen? use project’s graphql() function, check scalar mappings
12. gql.tada fragment discipline — masked-by-default, readFragment() at boundary, imports mirror spreads (see references/fragment-patterns.md)

Cross-Skill Routing

This skill covers reading via GraphQL CDA. Route to companion skill for: