datocms-frontend-integrations

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

DatoCMS Front-End Integrations Skill

DatoCMS前端集成技能

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.

本技能是DatoCMS Web项目的通用前端集成工具包。当用户希望完整搭建某一功能时，优先使用

datocms-setup

。在以下场景中使用本技能：

涉及多个前端关注点的混合功能任务
框架对比或API形态相关问题
在现有自定义集成中进行部分修补
为其他DatoCMS技能加载配套参考资料

当本技能协助搭建与初始化相关的工作时，若仍存在占位符则标记为

scaffolded

（已搭建），仅当实现不再依赖未确定的项目特定值时，才标记为

production-ready

（可用于生产环境）。

Step 1: Detect Context (silent)

步骤1：检测上下文（静默执行）

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.

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
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
```
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
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
File structure — Determine whether the project uses
```
src/
```
or root-level app directories

若对话中已确定项目上下文（框架、UI栈、现有集成、文件结构），则跳过以下广泛检测步骤。仅当无法通过已有上下文回答问题时，才重新检查。

静默检查项目以确定其配置情况：

框架 — 读取
```
package.json
```
并检查：
- ```
next
```
  -> Next.js（App Router）
- ```
nuxt
```
  -> Nuxt
- ```
@sveltejs/kit
```
  -> SvelteKit
- ```
astro
```
  -> Astro
- ```
@remix-run/
```
  -> Remix
- 否则推断项目是否基于React、Vue或其他技术栈
UI栈 — 确定项目实际用于Dato渲染的库：
- 基于React ->
```
react-datocms
```
- 基于Vue ->
```
vue-datocms
```
- SvelteKit / Svelte ->
```
@datocms/svelte
```
- 未集成React的Astro ->
```
@datocms/astro
```
现有Dato助手 — 搜索：
- ```
@datocms/cda-client
```
- 已有的
```
executeQuery
```
  封装
- 已有的图片/结构化文本/SEO/视频/搜索助手
- 包含Dato令牌或URL的环境变量文件
现有集成标记 — 检查仓库是否已包含：
- 草稿模式端点
- 预览链接端点
- Content Link挂载
- 实时订阅使用
- 缓存标签转发或失效
- 搜索路由或搜索助手
- robots/sitemap路由
文件结构 — 确定项目是否使用
```
src/
```
目录或根级别应用目录

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

步骤2：分类与路由

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

Category	When to select
Draft Mode Setup	Draft cookies, enable/disable endpoints, or draft CDA token switching
Web Previews Setup	Preview-links endpoints, route mapping, Visual tab support
Responsive Images	Dato image rendering helpers or component selection
Structured Text Rendering	Structured Text query shapes or renderer wiring
Video Player	Dato / Mux video playback integration
SEO & Meta Tags	`_seoMetaTags` , favicon tags, canonical wiring
Real-Time Updates	Live preview subscriptions or `<QueryListener />` wiring
Visual Editing / Content Link	Click-to-edit overlays and stega-aware rendering
Site Search	React / Vue widgets or low-level Search API wiring
Robots & Sitemaps	`robots.txt` , sitemap routes, crawler-safe rules
Cache Tags	Granular invalidation or tag-forwarding patterns

Multiple categories can apply.

将用户请求分类为一个或多个类别：

类别	适用场景
草稿模式配置	草稿Cookie、启用/禁用端点、或草稿CDA令牌切换
Web预览配置	预览链接端点、路由映射、可视化标签页支持
响应式图片	Dato图片渲染助手或组件选择
结构化文本渲染	结构化文本查询形态或渲染器配置
视频播放器	Dato/Mux视频播放集成
SEO与元标签	`_seoMetaTags` 、favicon标签、规范网址配置
实时更新	实时预览订阅或 `<QueryListener />` 配置
可视化编辑/Content Link	点击编辑覆盖层和隐写感知渲染
站点搜索	React/Vue组件或底层搜索API配置
Robots与Sitemaps	`robots.txt` 、sitemap路由、爬虫安全规则
缓存标签	细粒度失效或标签转发模式

可同时适用多个类别。

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:

Category	Route
Draft Mode Setup	`datocms-setup` for `draft-mode`
Web Previews Setup	`datocms-setup` for `web-previews`
Responsive Images	`datocms-setup` for `responsive-images`
Structured Text Rendering	`datocms-setup` for `structured-text`
Video Player	`datocms-setup` for `video-player`
SEO & Meta Tags	`datocms-setup` for `seo`
Real-Time Updates	`datocms-setup` for `realtime`
Visual Editing / Content Link	`datocms-setup` for `visual-editing` when the user means the full editor flow, or `content-link` when they explicitly want only overlays/stega wiring
Site Search	`datocms-setup` for `site-search`
Robots & Sitemaps	`datocms-setup` for `robots-sitemaps`
Cache Tags	`datocms-setup` for `cache-tags`

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.

若任务明确为“端到端搭建X”，则路由至

datocms-setup

而非在本工具包中完成所有工作：

类别	路由目标
草稿模式配置	`datocms-setup` 的 `draft-mode` 任务
Web预览配置	`datocms-setup` 的 `web-previews` 任务
响应式图片	`datocms-setup` 的 `responsive-images` 任务
结构化文本渲染	`datocms-setup` 的 `structured-text` 任务
视频播放器	`datocms-setup` 的 `video-player` 任务
SEO与元标签	`datocms-setup` 的 `seo` 任务
实时更新	`datocms-setup` 的 `realtime` 任务
可视化编辑/Content Link	当用户需要完整编辑流程时，路由至 `datocms-setup` 的 `visual-editing` ；当用户明确仅需要覆盖层/隐写配置时，路由至 `content-link`
站点搜索	`datocms-setup` 的 `site-search` 任务
Robots与Sitemaps	`datocms-setup` 的 `robots-sitemaps` 任务
缓存标签	`datocms-setup` 的 `cache-tags` 任务

当任务为“从零开始端到端搭建单个功能X”时，路由至

datocms-setup

。在处理多功能任务、部分修补、框架对比，或其他技能明确依赖本参考资料时，保留在本工具包中。

若请求提及可视化编辑且明确需要完整编辑流程，则视为捆绑配置：草稿模式+预览链接+Content Link+实时更新。仅当用户明确仅需要独立的覆盖层/隐写部分时，才单独路由至

content-link

。

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.

默认不询问任何问题。

仅当安全实现被仓库无法回答的信息阻碍时才询问，例如：

预览或sitemap生成所需的模型到路由映射缺失
缓存提供者或清除适配器选择缺失
存在多个竞争渲染器，修补错误的渲染器会有风险

否则直接执行，并指出未确定的值而非停滞。

Step 3: Load References

步骤3：加载参考资料

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.

仅从本技能旁的

references/

目录读取所需内容。长文件顶部包含目录；先预览目录，再加载相关章节。

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.

Category	Concept file
Responsive Images	`references/image-concepts.md`
Video Player	`references/video-player-concepts.md`
SEO & Meta Tags	`references/seo-concepts.md`
Real-Time Updates	`references/realtime-concepts.md`
Site Search	`references/site-search-concepts.md`

先加载相关概念文件——其中包含共享GraphQL查询、字段定义和模式。然后加载框架特定文件以获取组件API和属性。

类别	概念文件
响应式图片	`references/image-concepts.md`
视频播放器	`references/video-player-concepts.md`
SEO与元标签	`references/seo-concepts.md`
实时更新	`references/realtime-concepts.md`
站点搜索	`references/site-search-concepts.md`

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
```

在处理混合功能配置工作时加载以下内容：

```
references/draft-mode-concepts.md
```

一个框架参考：

```
references/nextjs.md
```
```
references/nuxt.md
```
```
references/sveltekit.md
```
```
references/astro.md
```
```
references/remix.md
```

可选概念参考：

```
references/web-previews-concepts.md
```
```
references/content-link-concepts.md
```
```
references/realtime-concepts.md
```

React references

React参考

Category	Reference file
Responsive Images	`references/react-image.md`
Structured Text Rendering	`references/react-structured-text.md`
Video Player	`references/react-video-player.md`
SEO & Meta Tags	`references/react-seo.md`
Real-Time Updates	`references/react-realtime.md`
Visual Editing / Content Link	`references/react-content-link.md`
Site Search	`references/react-site-search.md`

类别	参考文件
响应式图片	`references/react-image.md`
结构化文本渲染	`references/react-structured-text.md`
视频播放器	`references/react-video-player.md`
SEO与元标签	`references/react-seo.md`
实时更新	`references/react-realtime.md`
可视化编辑/Content Link	`references/react-content-link.md`
站点搜索	`references/react-site-search.md`

Vue references

Vue参考

Category	Reference file
Responsive Images	`references/vue-image.md`
Structured Text Rendering	`references/vue-structured-text.md`
Video Player	`references/vue-video-player.md`
SEO & Meta Tags	`references/vue-seo.md`
Real-Time Updates	`references/vue-realtime.md`
Visual Editing / Content Link	`references/vue-content-link.md`
Site Search	`references/vue-site-search.md`

类别	参考文件
响应式图片	`references/vue-image.md`
结构化文本渲染	`references/vue-structured-text.md`
视频播放器	`references/vue-video-player.md`
SEO与元标签	`references/vue-seo.md`
实时更新	`references/vue-realtime.md`
可视化编辑/Content Link	`references/vue-content-link.md`
站点搜索	`references/vue-site-search.md`

Svelte references

Svelte参考

Category	Reference file
Responsive Images	`references/svelte-image.md`
Structured Text Rendering	`references/svelte-structured-text.md`
Video Player	`references/svelte-video-player.md`
SEO & Meta Tags	`references/svelte-seo.md`
Real-Time Updates	`references/svelte-realtime.md`
Visual Editing / Content Link	`references/svelte-content-link.md`

Use

references/site-search-api.md

for Svelte / SvelteKit site-search work.

类别	参考文件
响应式图片	`references/svelte-image.md`
结构化文本渲染	`references/svelte-structured-text.md`
视频播放器	`references/svelte-video-player.md`
SEO与元标签	`references/svelte-seo.md`
实时更新	`references/svelte-realtime.md`
可视化编辑/Content Link	`references/svelte-content-link.md`

处理Svelte/SvelteKit站点搜索工作时使用

references/site-search-api.md

。

Astro references

Astro参考

Category	Reference file
Responsive Images	`references/astro-image.md`
Structured Text Rendering	`references/astro-structured-text.md`
SEO & Meta Tags	`references/astro-seo.md`
Real-Time Updates	`references/astro-realtime.md`
Visual Editing / Content Link	`references/astro-content-link.md`

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.

类别	参考文件
响应式图片	`references/astro-image.md`
结构化文本渲染	`references/astro-structured-text.md`
SEO与元标签	`references/astro-seo.md`
实时更新	`references/astro-realtime.md`
可视化编辑/Content Link	`references/astro-content-link.md`

处理Astro站点搜索工作时使用

references/site-search-api.md

。对于Astro视频，直接使用Mux Web组件，或在项目已集成React时使用React集成。

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
```

当任务与框架无关、非组件化或针对爬虫时，加载以下内容：

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

Verification reference

验证参考

When implementation work is involved, load:

```
references/verification-checklists.md
```

当涉及实现工作时，加载：

```
references/verification-checklists.md
```

Step 4: Generate or Patch Code

步骤4：生成或修补代码

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.

所有机密信息均来自环境变量。
在草稿模式或预览链接流程需要时，验证专用预览/ webhook机密环境变量；若仓库已有命名则保留。
使用
```
isRelativeUrl()
```
进行重定向验证。
草稿模式禁用端点不需要身份验证。

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.

添加或保留
```
includeDrafts
```
选项以支持草稿感知查询。
根据该选项切换已发布和草稿CDA令牌。
草稿感知封装模式默认启用
```
excludeInvalid: true
```
，除非任务明确需要在架构工作期间使用无效记录。
仅在草稿/可视化编辑上下文下启用仓库现有的
```
contentLink
```
模式（
```
'v1'
```
或
```
'vercel-v1'
```
）以及
```
baseEditingUrl
```
。

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.

为检测到的框架使用原生环境变量和重定向API。
对于Astro，始终使用
```
@datocms/astro/*
```
子路径导入。
使用加载参考资料中适合框架的组件或助手API，而非从记忆中复制跨框架模式。

TypeScript rules

TypeScript规则

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

不使用
```
as unknown as
```
。
避免不必要的类型转换。
优先使用
```
import type { ... }
```
进行仅类型导入。
尽可能让TypeScript自动推断类型。

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.

仅当任务确实需要时才安装缺失的包。
React视频使用
```
@mux/mux-player-react
```
。
Vue或Svelte视频使用
```
@mux/mux-player
```
。
React/Vue组件化站点搜索使用
```
@datocms/cma-client-browser
```
。

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.

使用明确的搜索索引ID。
在浏览器中使用权限最低的公共搜索令牌。
Sitemap输出仅保留在配置的公共域名上。
Dato爬虫的
```
Allow
```
规则优先于任何通配符
```
Disallow: /
```
规则。

若仍存在客户特定值（如路由映射、提供者详情或索引ID）未确定，留下清晰的占位符并明确指出缺失的输入，而非将工作呈现为完全就绪。

Step 5: Verify

步骤5：验证

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

加载

references/verification-checklists.md

并仅检查与实际执行工作相关的章节。

至少验证以下内容：

安全、令牌处理、重定向验证和环境变量使用
查询形态、封装选项和框架特定组件API
依赖选择和导入路径
仅草稿行为保持仅草稿状态
所有剩余占位符或客户特定映射均已明确指出

Cross-Skill Routing

跨技能路由

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

Condition	Route to
Full single-feature scaffolding	`datocms-setup` with the matching recipe from Step 2
Shared CDA client wrapper or `executeQuery` baseline	`datocms-setup` for `cda-client`
Writing or optimizing GraphQL queries for the CDA	`datocms-cda`
Programmatic content management, schema changes, migration scripts, access control, or webhook creation via REST	`datocms-cma`
Building a DatoCMS plugin	`datocms-plugin-builder`

当任务超出本工具包的适用范围时，使用配套技能：

条件	路由目标
完整单功能搭建	`datocms-setup` 及步骤2中匹配的方案
共享CDA客户端封装或 `executeQuery` 基础配置	`datocms-setup` 的 `cda-client` 任务
为CDA编写或优化GraphQL查询	`datocms-cda`
通过REST进行程序化内容管理、架构变更、迁移脚本、访问控制或webhook创建	`datocms-cma`
构建DatoCMS插件	`datocms-plugin-builder`