datocms-frontend-integrations（datocms 前端集成）

DatoCMS Front-End Integrations Skill

This skill is the shared front-end integration bundle for DatoCMS web projects. Prefer datocms-setup when the user wants one feature fully scaffolded end-to-end. Stay in this skill for:

• mixed-feature tasks touching multiple front-end concerns
• framework comparison or API-shape questions
• partial patching inside an existing custom integration
• companion-reference loading for another DatoCMS skill

When this skill helps scaffold setup-adjacent work, report the result as scaffolded when placeholders remain and production-ready only when the 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)

If the project context is already established in this conversation (framework, UI stack, existing integrations, file structure), skip broad detection below. Re-inspect only when a question cannot be answered from prior context.

Silently examine the project to determine setup and configuration.

1. Framework — Read package.json and check for:

- next -> Next.js (App Router) - nuxt -> Nuxt - @sveltejs/kit -> SvelteKit - astro -> Astro - @remix-run/ -> Remix - otherwise infer whether the project is React-based, Vue-based, or another stack

1. UI stack — Determine which library the project actually uses for Dato rendering:

- React-based -> react-datocms - Vue-based -> vue-datocms - SvelteKit / Svelte -> @datocms/svelte - Astro without React integration -> @datocms/astro

1. Existing Dato helpers — Search for:

- @datocms/cda-client - an existing executeQuery wrapper - existing image / Structured Text / SEO / video / search helpers - environment variable files with Dato tokens or URLs

1. Existing integration markers — Check whether the repo already has:

- draft mode endpoints - preview-links endpoints - Content Link mounting - real-time subscription usage - cache-tag forwarding or invalidation - search routes or search helpers - robots / sitemap routes

1. File structure — Determine whether the project uses src/ or root-level app directories

Stop conditions

• If the framework cannot be determined, ask the user which stack they are using.
• If a requested integration already exists, inspect it and patch in place by default.
• Only ask about full replacement when the current setup is clearly incompatible, broken, or the user explicitly asked for a rewrite.

Step 2: Classify and Route

Classify the user's request into one or more categories:

Multiple categories can apply.

Prefer the setup orchestrator for full single-feature scaffolding

If the task is clearly "set up X end-to-end", route to datocms-setup instead of keeping all work in this bundle:

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

If the request says visual editing and clearly wants the full editorial flow, treat that as the bundled setup: draft mode + preview links + Content Link + real-time updates. Only route to content-link by itself when the user explicitly wants the overlay/stega piece in isolation.

Questions

Ask zero questions by default.

Only ask when a safe implementation is blocked by something the repo cannot answer, such as:

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

Otherwise proceed directly and call out unresolved values instead of stalling.

Step 3: Load References

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

Component concept references

Load the relevant concept file first — it contains shared GraphQL queries, field definitions, and patterns. Then load the framework-specific file for component APIs and 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 the Mux web component directly or React integration when the project already has it.

Generic search and crawl references

Load these when the task is 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 the loaded references and these shared rules:

Workflow rules

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

Security and environment rules

• All secrets come from environment variables.
• Validate a dedicated preview/webhook secret environment variable 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 an 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 the task explicitly needs invalid records during schema work.
• Enable the 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 the detected framework.
• For Astro, always use @datocms/astro/* subpath imports.
• Use the framework-appropriate component or helper API from the loaded reference, not a cross-framework pattern copied from memory.

TypeScript rules

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

Dependency rules

• Install missing packages only when the 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 the browser.
• Keep sitemap output on the configured public domain only.
• Order Dato crawler Allow rules before any catch-all Disallow: /.

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

Step 5: Verify

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

At minimum, verify:

• security, token handling, redirect validation, and environment-variable usage
• query shapes, wrapper options, and 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 the task leaves this bundle's sweet spot: