/api-cms-sanity

name: api-cms-sanity
description: Structured content platform — GROQ queries, schema definitions, @sanity/client, Portable Text, image handling, real-time listeners, mutations, TypeGen

Sanity Patterns

> **Quick Guide:** Use Sanity for structured content management with GROQ queries, typed schemas via `defineType`/`defineField`, and `@sanity/client` for data fetching. Always set `apiVersion` to a dated string, use `useCdn: true` for public reads, handle draft documents explicitly, use `@sanity/image-url` for image transformations, and render rich text with `@portabletext/react`. Generate TypeScript types with `sanity typegen generate`.

---

<critical_requirements>

CRITICAL: Before Using This Skill

**(You MUST always set `apiVersion` on `createClient` to a dated string like `'2025-02-19'` — omitting it uses a legacy API that may break)**

**(You MUST use `useCdn: true` for public read queries and `useCdn: false` when using a token or needing fresh data)**

**(You MUST use parameterized GROQ queries (`$param`) for any dynamic values — never interpolate user input into GROQ strings)**

**(You MUST handle drafts explicitly — draft documents have `_id` prefixed with `drafts.` and are not returned by default with `perspective: 'published'`)**

**(You MUST use `defineQuery()` from `groq` and assign queries to named variables for TypeGen type generation)**

</critical_requirements>

---

**Auto-detection:** Sanity, sanity, @sanity/client, createClient, GROQ, groq, defineType, defineField, defineArrayMember, @sanity/image-url, urlFor, @portabletext/react, PortableText, portable text, block content, sanity.config, sanity.cli, typegen, sanity studio, content lake

**When to use:**

• Setting up `@sanity/client` with `createClient` for data fetching
• Writing GROQ queries (filters, projections, joins, ordering, slicing)
• Defining content schemas with `defineType`, `defineField`, `defineArrayMember`
• Rendering Portable Text (block content) with `@portabletext/react`
• Generating image URLs with `@sanity/image-url` (responsive images, crops, hotspots)
• Performing mutations (create, patch, delete, transactions)
• Setting up real-time listeners with `client.listen()`
• Generating TypeScript types with Sanity TypeGen

**Key patterns covered:**

• Client setup with `createClient` and `apiVersion` configuration
• GROQ query language: filters, projections, ordering, slicing, joins, references
• Schema definitions: document types, object types, arrays, references, images
• Portable Text rendering with custom components
• Image URL builder with responsive images and transformations
• Mutations: create, createOrReplace, patch, delete, transactions
• Real-time listeners via `client.listen()`
• TypeGen for type-safe GROQ queries with `defineQuery()`

**When NOT to use:**

• GraphQL-only APIs (Sanity supports GROQ primarily; use GraphQL skill if needed)
• Direct database access (Sanity is a hosted content lake, not a database)
• Non-Sanity CMS platforms (use the dedicated skill for your CMS)

**Detailed Resources:**

• For decision frameworks and quick-reference tables, see [reference.md](reference.md)

**Client & GROQ:**

• [examples/core.md](examples/core.md) — Client setup, GROQ queries, error handling, TypeGen

**Schemas:**

• [examples/schemas.md](examples/schemas.md) — defineType, defineField, document types, object types, references, images

**Rich Content:**

• [examples/rich-content.md](examples/rich-content.md) — Portable Text rendering, image URL builder, responsive images

**Mutations & Real-time:**

• [examples/mutations.md](examples/mutations.md) — Create, patch, delete, transactions, real-time listeners

---

<philosophy>

Philosophy

Sanity is a structured content platform built around a real-time content lake, GROQ (Graph-Relational Object Queries) as its query language, and Sanity Studio as a customizable editing environment.

**Core principles:**

1. **Structured content** — Content is defined by schemas (`defineType`, `defineField`) that describe shape, validation, and editorial UI. Schemas are code, not configuration files. 2. **GROQ-first querying** — GROQ lets you filter, project, join, and reshape data in a single query. Unlike REST or GraphQL, GROQ queries return exactly the shape you define in the projection. 3. **Content as data** — Rich text is stored as Portable Text (a JSON-based specification), making it renderable in any frontend framework without vendor lock-in. 4. **API versioning** — Every client must specify an `apiVersion` date string. This pins your code to a specific API behavior, preventing breaking changes from affecting production. 5. **CDN caching** — Public read queries use `useCdn: true` for edge-cached responses. Mutations and authenticated reads use `useCdn: false` for fresh data. 6. **Type generation** — Sanity TypeGen generates TypeScript types from both your schemas and GROQ queries, enabling end-to-end type safety from content model to frontend.

**When to use Sanity:**

• Content-driven websites and applications (blogs, marketing sites, documentation)
• Projects needing real-time collaborative editing in a customizable studio
• Multi-channel content delivery (web, mobile, IoT) from a single content source
• Teams wanting type-safe content queries with GROQ and TypeGen

**When NOT to use:**

• Transactional data requiring ACID guarantees (use a database)
• User-generated content at massive scale (Sanity is optimized for editorial content)
• Projects needing a self-hosted CMS (Sanity's content lake is hosted, though the Studio is open source)

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Client Setup with createClient

Configure `@sanity/client` with project ID, dataset, API version, and CDN preference. Always set `apiVersion` to a dated string and `useCdn` explicitly.

import { createClient } from "@sanity/client";

export const client = createClient({
  projectId: process.env.SANITY_PROJECT_ID!,
  dataset: