Datocms Frontend Integrations

DatoCMS Front-End Integrations Skill

Shared front-end integration bundle. Prefer datocms-setup for single feature end-to-end. Stay here for mixed-feature, framework comparison, partial patching, companion-reference loading.

Report scaffolded when placeholders remain, production-ready only when implementation no longer depends on unresolved project-specific values.

Contents

• Step 1: Detect Context
• Step 2: Classify and Route
• Step 3: Load References
• Step 4: Generate or Patch Code
• Step 5: Verify
• Cross-Skill Routing

Step 1: Detect Context (silent)

Skip if context established. Only re-inspect when question can't be answered from prior context.

Silently examine:

1. Framework — package.json: next → Next.js App Router, nuxt → Nuxt, @sveltejs/kit → SvelteKit, astro → Astro, @remix-run/ → Remix, or infer React/Vue/other
2. UI stack — Dato rendering lib: React (react-datocms), Vue (vue-datocms), SvelteKit/Svelte (@datocms/svelte), Astro without React (@datocms/astro)
3. Existing Dato helpers — @datocms/cda-client, query wrappers, image/Structured Text helpers, env vars
4. Existing integration markers — draft mode endpoints, preview-links, Content Link, real-time subscriptions, cache-tag forwarding, search routes, robots/sitemap
5. File structure — src/ or root-level app directories
6. Starter-conventions markers (gql.tada projects) — gql.tada in package.json, lib/datocms/gqlUrlBuilder/ folder, project <Text> wrapper around <StructuredText />, co-located fragments.ts next to block / inline-record / link-to-record components. Presence of these = project follows the patterns in references/url-builders.md + datocms-cda/references/fragment-patterns.md.

Stop conditions

• Framework unclear → ask user
• Integration exists → inspect and patch in place by default
• Only ask about full replacement when clearly incompatible, broken, or user explicitly requested rewrite

Step 2: Classify and Route

Categorize into:

Multiple categories can apply.

Prefer the setup orchestrator for full single-feature scaffolding

Route to datocms-setup instead of keeping all work in this bundle:

Route to datocms-setup for "set up X end-to-end from scratch" (single feature). Stay here for multi-feature, partial patching, framework comparisons, or when another skill explicitly depends on these references.

visual editing = full editorial flow (draft mode + preview links + Content Link + real-time). Route to content-link only when user explicitly wants overlay/stega in isolation.

Questions

Ask zero questions by default.

Only ask when blocked by something the repo cannot answer:

• missing model-to-route mappings for preview/sitemap
• missing cache provider or purge-adapter choice
• multiple competing renderers where patching the wrong one is risky

Otherwise proceed and call out unresolved values instead of stalling.

Step 3: Load References

Read only what is needed from references/ next to this skill. Long files include contents section at top; preview that first, then load relevant section.

Component concept references

Load concept file first (shared GraphQL queries, field definitions, patterns), then framework-specific file for component APIs/props.

Setup foundations

Load these for mixed-feature setup work:

• references/draft-mode-concepts.md
• one framework reference:
  • references/nextjs.md
  • references/nuxt.md
  • references/sveltekit.md
  • references/astro.md
  • references/remix.md
• optional concept references:
  • references/web-previews-concepts.md
  • references/content-link-concepts.md
  • references/realtime-concepts.md

React references

Vue references

Svelte references

Use references/site-search-api.md for Svelte / SvelteKit site-search work.

Astro references

Use references/site-search-api.md for Astro site-search work. For Astro video, use Mux web component directly or React integration when project already has it.

gql.tada starter-conventions references

Load when project uses gql.tada AND task adds/extends a block, inline-record, link-to-record, routable model, or page query:

• references/url-builders.md — per-model URL builders + buildUrlFromGql() dispatcher
• ../datocms-cda/references/fragment-patterns.md — masking discipline, readFragment() boundary, fragment composition, page-query rule

Don't load when project uses plain executeQuery strings or codegen with hand-shaped types — patterns don't apply.

Generic search and crawl references

Load for framework-agnostic, non-widget-based, or crawler-specific:

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

Verification reference

When implementation work is involved, load:

• references/verification-checklists.md

Step 4: Generate or Patch Code

Follow loaded references and shared rules:

Workflow rules

• Respect existing abstractions and patch in place by default
• Prefer focused setup skill when task narrows to single full scaffold
• Make targeted changes instead of full rewrites unless current code is unusable

Security and environment rules

• All secrets from environment variables
• Validate dedicated preview/webhook secret env var where draft mode or preview-links flows require it; preserve existing repo naming when present
• Use isRelativeUrl() for redirect validation
• Do not require authentication on draft-mode disable endpoints

Query-wrapper rules

• Add or preserve includeDrafts option for draft-aware querying
• Switch between published and draft CDA tokens based on that option
• Default to excludeInvalid: true for draft-aware wrapper patterns unless task explicitly needs invalid records during schema work
• Enable repo's existing contentLink mode ('v1' or 'vercel-v1') plus baseEditingUrl only in draft / visual-editing contexts

Framework rules

• Use native env and redirect APIs for detected framework
• For Astro, always use @datocms/astro/* subpath imports
• Use framework-appropriate component or helper API from loaded reference, not cross-framework pattern from memory

TypeScript rules

• No as unknown as
• Avoid unnecessary casts
• Prefer import type { ... } for type-only imports
• Let TypeScript infer where it can

Dependency rules

• Install missing packages only when task truly needs them
• Use @mux/mux-player-react for React video
• Use @mux/mux-player for Vue or Svelte video
• Use @datocms/cma-client-browser for React / Vue widget-based site search

Search and crawl safety rules

• Use explicit search index ids
• Use least-privilege public search tokens in browser
• Keep sitemap output on configured public domain only
• Order Dato crawler Allow rules before any catch-all Disallow: /

If customer-specific values (route mappings, provider details, index ids) remain unresolved, leave clear placeholders and explicitly call out missing inputs instead of presenting work as fully ready.

Step 5: Verify

Load references/verification-checklists.md and check only sections relevant to work you actually performed.

At minimum, verify:

• security, token handling, redirect validation, environment-variable usage
• query shapes, wrapper options, framework-specific component APIs
• dependency choices and import paths
• draft-only behavior stays draft-only
• any remaining placeholders or customer-specific mappings are clearly called out

Cross-Skill Routing

Use companion skills when task leaves this bundle's sweet spot: