datocms-frontend-integrations

DatoCMS 前端集成技能

共享的前端集成套件：针对单项或混合功能进行实现、局部补丁、框架比较和配套参考资料加载。

这里涵盖 Structured Text 组件和渲染器回调，包括传递给 renderBlock 的已解析 record。只有在用户要求检查、转换、转码或验证文档时，才加载文档专家；常规渲染器示例无需读取配套资料。

仍有占位内容时报告 scaffolded；只有实现不再依赖未解决的项目特定值时，才报告 production-ready。

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

如果上下文已明确，则跳过。只有在无法根据先前上下文回答问题时，才重新检查。

静默检查：

1. 框架 — package.json：next → Next.js App Router，nuxt → Nuxt，@sveltejs/kit → SvelteKit，astro → Astro，@remix-run/* 或 @react-router/dev → Remix / React Router 框架模式（采用 React 参考资料；修改现有 loaders/路由模块），否则推断 React/Vue/其他
2. UI 技术栈 — Dato 渲染库：React（react-datocms）、Vue（vue-datocms）、SvelteKit/Svelte（@datocms/svelte）、不使用 React 的 Astro（@datocms/astro）
3. 现有 Dato 助手 — @datocms/cda-client、查询封装、图像/Structured Text 助手、环境变量
4. 现有集成标记 — 草稿模式端点、preview-links、Content Link、实时订阅、缓存标签转发、搜索路由、robots/sitemap
5. 文件结构 — src/ 或根目录下的 app 目录。参考资料使用 src/ 路径；不使用 src/ 的 Next.js → app/、lib/datocms/；SvelteKit 和 Astro 默认使用 src/（kit.files.src、srcDir）；Nuxt 参考资料展示根目录下的 lib/、composables/ — 相对于 srcDir（~）：Nuxt 4 → 若存在则使用 app/，否则使用根目录；server/ 保留在根目录（references/nuxt.md › 文件结构）
6. Starter 约定标记（gql.tada 项目）— package.json 中有 gql.tada、存在 lib/datocms/gqlUrlBuilder/ 文件夹、项目有包裹 <StructuredText /> 的 <Text> 封装组件、block / inline-record / link-to-record 组件旁有同目录的 fragments.ts。存在这些标记表示项目遵循 references/url-builders.md + datocms-cda/references/fragment-patterns.md 中的模式。

停止条件

• 框架不明确 → 询问用户
• 已存在集成 → 默认检查并就地修改
• 只有在明显不兼容、已损坏或用户明确要求重写时，才询问是否要完全替换

步骤 2：分类并路由

归类为：

类别	选择时机
草稿模式设置	草稿 Cookie、启用/停用端点或草稿 CDA 令牌切换
Web 预览设置	Preview-links 端点、路由映射、Visual 标签页支持
响应式图像	Dato 图像渲染助手或组件选择
Structured Text 渲染	Structured Text 查询形状或渲染器接线
视频播放器	Dato / Mux 视频播放集成
SEO 与 Meta 标签	_seoMetaTags、favicon 标签、canonical 接线
实时更新	实时预览订阅或 <QueryListener /> 接线
可视化编辑 / Content Link	点击编辑覆盖层和支持 stega 的渲染
站点搜索	React / Vue 小组件或底层 Search API 接线
Robots 与站点地图	robots.txt、sitemap 路由、爬虫安全规则
缓存标签	细粒度失效或标签转发模式

可以同时适用多个类别。

可视化编辑 = 草稿模式 + Web 预览 + Content Link；只有在用户提出要求时才包括实时功能。只有在用户希望单独使用覆盖层/stega 时，才仅使用 Content Link。套件默认设置、Vercel 冲突规则、插件移交字段：references/visual-editing-concepts.md。

问题

默认情况下不提问。

只有在仓库无法解答、因此受阻时才提问：

• 缺少用于预览/站点地图的模型到路由映射
• 缺少缓存提供程序或清除适配器的选择
• 存在多个互相竞争的渲染器，修补错误的渲染器会有风险

否则继续操作，并指出尚未确定的值，而不是停滞不前。

第 3 步：加载参考资料

阅读 references/ 中的相关章节；对于较长的文件，先预览其内容。

对于缓存标签相关工作，请阅读所选框架参考资料中的 缓存标签（可选） 章节，包括针对现有查询辅助函数的定向修补。仅阅读 Core 章节不足以了解细粒度失效机制。对于手动 CDN 收集/清除，还需加载 references/cache-tag-adapters.md；Next.js 查询 ID 映射或原生缓存提供程序则跳过该适配器文件。

组件概念参考资料

先加载概念文件（共享 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

设置基础

对于混合功能设置工作，请加载以下资料：

• references/draft-mode-concepts.md
• 一份框架参考资料：
  • references/nextjs.md
  • references/nuxt.md
  • references/sveltekit.md
  • references/astro.md
• 可选概念参考资料：
  • references/web-previews-concepts.md
  • references/content-link-concepts.md
  • references/realtime-concepts.md

React 参考资料

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

Vue 参考资料

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

Svelte 参考资料

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

Svelte / SvelteKit 站点搜索工作请使用 references/site-search-api.md。

Astro 参考资料

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

Astro 站点搜索工作请使用 references/site-search-api.md。对于 Astro 视频，请直接使用 Mux Web 组件（references/video-player-concepts.md › 不带 React 集成的 Astro），或者在项目已使用 React 集成时使用该集成。

gql.tada 入门约定参考

当项目使用 gql.tada，且任务需要添加或扩展块、内联记录、记录链接、可路由模型或页面查询时加载：

• references/url-builders.md — 各模型的 URL 构建器和 buildUrlFromGql() 分派器
• ../datocms-cda/references/fragment-patterns.md — 掩码规范、readFragment() 边界、片段组合和页面查询规则

当项目使用普通的 executeQuery 字符串或使用手工构造类型的代码生成时，不要加载，因为这些模式不适用。

通用搜索和爬取参考

适用于与框架无关、不基于组件或针对爬虫的场景：

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

第 4 步：生成或修补代码

遵循已加载的参考和通用规则：

工作流规则

• 遵循现有抽象，默认就地修补
• 进行有针对性的更改；除非现有代码无法使用，否则不要整体重写

安全和环境规则

• 所有密钥都从环境变量读取
• 新增运行时环境变量：在 .env.example 和仓库本地、已加入 git 忽略的环境文件中添加占位条目；复用现有名称；绝不提交真实值。CLI/CMA 令牌除外（CLI 通过 login 和 link 进行身份验证）
• 在草稿模式或预览链接流程需要时，验证专用的预览/Webhook 密钥环境变量；若仓库已有命名方式，则保留
• 使用 isRelativeUrl() 验证重定向
• 草稿模式停用端点不得要求身份验证

查询包装器规则

• 共享辅助函数：框架参考中的 ## Core 查询辅助函数——在草稿模式启用前使用仅查询已发布内容的变体；文档类型遵循仓库中的约定（gql.tada 使用 TadaDocumentNode，代码生成使用 TypedDocumentNode，否则使用 query: string）。客户端选项： client-and-config.md
• 为支持草稿的查询添加或保留 includeDrafts 选项
• 根据该选项，在已发布内容和草稿 CDA 令牌之间切换
• 对支持草稿的包装器模式，默认设置 excludeInvalid: true，除非任务明确要求在架构工作期间包含无效记录
• 仅在草稿或可视化编辑场景中启用仓库现有的 contentLink 模式（'v1' 或 'vercel-v1'）
• 只要查询选择了 _editingUrl，无论读取的是已发布内容还是草稿，都要提供公开的 baseEditingUrl

框架规则

• 使用检测到的框架原生环境变量和重定向 API
• 子路径导入：@datocms/astro/*；react-datocms/<feature>（根级 barrel 需要可选的 @mux/mux-player-react）
• 使用已加载参考中适用于该框架的组件或辅助 API，不要凭记忆套用其他框架的模式

TypeScript 规则

• 不要使用 as unknown as
• 避免不必要的类型断言
• 仅导入类型时，优先使用 import type { ... }
• 尽可能让 TypeScript 自行推断

依赖规则

• 仅在任务确实需要时安装缺失的包
• 生成的代码所导入的包必须列为直接 dependencies，即使 Dato 包已将其引入也不例外（严格的 pnpm）；@types/* 和 datocms CLI 列为 devDependencies
• React 视频使用 @mux/mux-player-react
• Vue 或 Svelte 视频使用 @mux/mux-player
• 基于组件的 React / Vue 站内搜索使用 @datocms/cma-client-browser

搜索和爬取安全规则

• 使用明确指定的搜索索引 ID
• 浏览器中使用权限最小化的公开搜索令牌
• 站点地图仅输出到配置的公开域名
• 将 Dato 爬虫的 Allow 规则放在任何兜底 Disallow: / 之前

如果客户专属的值（路由映射、提供方详情、索引 ID）仍未确定，请留下清晰的占位符，并明确指出缺少哪些输入，不要将工作描述为已完全就绪。

第 5 步：验证

加载 references/verification-checklists.md，仅检查与你实际执行的工作相关的部分。

至少验证以下内容：

• 安全性、令牌处理、重定向验证、环境变量的使用
• 查询结构、封装器选项、框架特定的组件 API
• 依赖选择和导入路径
• 仅草稿行为是否始终仅限草稿
• 是否明确指出任何剩余的占位符或客户特定映射

跨技能路由

DAST 结构/验证 → document model；内容遍历/转换 → editing；Markdown/HTML 导入和与框架无关的导出 → conversion，这些内容均由 datocms-structured-text 负责。仅在处理这些任务时加载；组件连接以及查询/渲染适配器仍由此处负责。缺少同级参考资料 → 从 datocms/agent-skills 安装该技能，或更新完整套件。

当任务超出此套件的适用范围时，使用配套技能：

条件	路由至
引导式多部分设置、新建站点，或用户不确定需要哪种结果	datocms-setup
为 CDA 编写或优化 GraphQL 查询	datocms-cda
gql.tada 片段编写规范（屏蔽、组合、页面查询）	datocms-cda（../datocms-cda/references/fragment-patterns.md）
通过 REST 进行程序化内容管理、架构变更、迁移脚本、访问控制或 webhook 创建	datocms-cma
构建 DatoCMS 插件	datocms-plugin