mcpField
S
sanity-best-practices

sanity-best-practices

github.com/sanity-io开发19432.2k 次安装1 天前更新
代码仓库

关于 sanity-best-practices

Sanity Best Practices 是由 Sanity 维护的开发技能，涵盖项目设置、集成、内容建模和运维。主题参考文档涉及框架、GROQ、Schema 与迁移。

主要功能

  1. 01框架集成指南
  2. 02GROQ 查询与性能建议
  3. 03Schema 设计和验证实践
  4. 04Visual Editing 与实时预览指南
  5. 05本地化和迁移参考文档

适用场景

  1. 01设置 Sanity 项目
  2. 02构建前端集成
  3. 03设计 Schema 和 GROQ 查询
  4. 04规划内容本地化或迁移

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/sanity-io/agent-toolkit --skill sanity-best-practices

安装后在 Claude Code 中输入/sanity-best-practices确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
angular.md
app-sdk.md
astro.md
blueprints.md
dashboard.md
functions.md
get-started.md
groq.md
hydrogen.md
image.md
localization.md
migration-html-import.md
migration.md
nextjs.md
nuxt.md
page-builder.md
portable-text.md
project-structure.md
remix.md
schema.md
seo.md
studio-structure.md
svelte.md
typegen.md
visual-editing.md

详细介绍

Sanity 最佳实践

由 Sanity 维护的 Sanity 开发全面最佳实践和集成指南。使用以下快速参考，仅加载与任务相符的一两个主题文件。

适用场景

在以下情况下，请参考这些指南：

  • 设置新的 Sanity 项目或进行入门引导
  • 将 Sanity 集成到前端框架（Next.js、Nuxt、Astro、Remix、SvelteKit、Hydrogen）
  • 编写 GROQ 查询或优化性能
  • 设计内容模式
  • 实现 Visual Editing 和实时预览
  • 处理图像、Portable Text 或页面构建器
  • 配置 Sanity Studio 结构
  • 设置 TypeGen 以确保类型安全
  • 实现本地化
  • 从其他系统迁移内容
  • 使用 Sanity App SDK 构建自定义应用
  • 在 Sanity Dashboard 中开发或部署 Studio 或应用
  • 使用 Blueprints 管理基础设施
  • 使用 Sanity Functions 或 Webhook 自动化内容工作流

全局规则

  • 对普通文档使用 Sanity 生成的 _id 值。创建文档时，请勿创建确定性 UUID、根据 slug 生成的 ID 或旧系统中的 ID。
  • 使用 reference 字段建模关系，然后通过 GROQ 查询、来源键字段或已创建文档返回的 _id 值解析相关文档。
  • 仅在由 Studio Structure 控制的单例文档中使用显式文档 ID，包括本地化的单例文档，例如 homePage-en。

视频

  • 在生产环境中，不要将视频存储为 Sanity file 资源或通过其提供视频。文件资源以原始下载文件的形式交付，不会转码或自适应流式传输；视频流量会带来极高的带宽用量和意料之外的高额账单。
  • 对于包含视频附加功能的 Enterprise 计划，请使用 Sanity Media Library 处理视频：上传的视频会转码，并通过 Mux 进行自适应流式传输。使用 sanity/media-library 中的 defineVideoField() 对视频字段建模，并使用 @mux/mux-player-react 和资源的播放 ID 播放视频。
  • 对于其他计划，请使用专用视频服务：安装 sanity-plugin-mux-input，从 Studio 上传和管理 Mux 账户中的视频；或者将视频托管在 YouTube 或 Vimeo 等平台，并仅在 Sanity 中存储嵌入 URL。
  • 小片段和短预览可以存储在 file 字段中，但任何面向用户且规模较大的视频都必须通过 Media Library 或流媒体服务提供。

快速参考

集成指南
  • get-started - 新 Sanity 项目的交互式入门引导
  • nextjs - Next.js App Router、Live Content API、独立 Studio
  • nuxt - 使用 @nuxtjs/sanity 集成 Nuxt
  • angular - 使用 @sanity/client、signals、resource API 集成 Angular
  • astro - 使用 @sanity/astro 集成 Astro
  • remix - React Router / Remix 集成
  • svelte - 使用 @sanity/svelte-loader 集成 SvelteKit
  • hydrogen - Shopify Hydrogen 与 Sanity
  • project-structure - 独立 Studio 和 monorepo 模式
  • app-sdk - 使用 Sanity App SDK 构建自定义应用
  • dashboard - Sanity Dashboard 中的 Studio 和应用：defineApplication、本地开发、部署、Dashboard hooks
  • blueprints - 基础设施即代码：blueprint 文件、堆栈、计划/部署工作流、错误恢复、CI 部署
  • functions - 使用 Sanity Functions 和 Webhook 自动化内容工作流
主题指南
  • groq - GROQ 查询模式、类型安全、性能优化
  • schema - Schema 设计、字段定义、验证、弃用模式
  • visual-editing - Presentation Tool、Stega、叠加层、实时预览
  • page-builder - Page Builder 数组、区块组件、实时编辑
  • portable-text - 富文本渲染和自定义组件
  • image - Image schema、URL 构建器、热点、LQIP、Next.js Image
  • studio-structure - Desk 结构、单例、导航
  • typegen - TypeGen 配置、工作流、类型工具
  • seo - 元数据、站点地图、Open Graph、JSON-LD
  • localization - i18n 模式、文档级与字段级、本地化管理
  • migration - 内容导入概览（另请参阅 migration-html-import）
  • migration-html-import - 使用 @portabletext/block-tools 将 HTML 转换为 Portable Text

使用方法

先选择与请求最匹配的框架或主题指南，然后仅在任务涉及多个方面时阅读其他参考资料。使用这些参考文件查看详细说明和代码示例：

references/groq.md
references/schema.md
references/nextjs.md

每个参考文件都包含：

  • 全面的主题或集成内容
  • 错误和正确的代码示例
  • 决策矩阵和工作流指南
  • 适用时的特定框架模式

评论

支持 Markdown