Home › Sanity › Sanity Studio + GROQ AGENTS.md

Sanity Studio + GROQ AGENTS.md

AGENTS.md for Sanity projects: schema types with defineType, typed GROQ queries via TypeGen, Portable Text, previews, and safe content migrations.

AGENTS.mdSanity

Copy AGENTS.md

How to use

Save this as AGENTS.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

Note: Review and test before use. Provided as is, without warranty. See Terms.

# AGENTS.md: Sanity (Studio + frontend)

## Commands
- Studio dev: `npx sanity dev` · deploy (only when asked): `npx sanity deploy`
- Types: `npx sanity schema extract && npx sanity typegen generate` after any schema or query change
- Migrations: `npx sanity migration create` then `npx sanity migration run <id>` (dry run by default; add `--no-dry-run` only when asked)

## Code map
- `schemaTypes/` (or `sanity/schemaTypes/`): one file per document/object type, exported from `index.ts`.
- `sanity.config.ts`, `sanity.cli.ts` at the Studio root. Frontend queries in `lib/queries.ts` (or `sanity/lib/queries.ts`).

## Schema rules
- Use `defineType`, `defineField`, `defineArrayMember` for every type so TypeScript and TypeGen work.
- Every document has `title`, a `slug` with `options.source`, `validation` rules for required fields, and a `preview` config.
- Use references for shared entities (authors, categories) instead of duplicating objects.
- Images use `type: 'image'` with `options.hotspot: true` and a required `alt` field.
- Renaming or removing fields breaks existing content: write a migration instead of deleting the field.

## Query rules
- Write GROQ with the `defineQuery` helper so TypeGen produces result types; project only the fields you need (`{_id, title, "slug": slug.current}`).
- Pass parameters (`$slug`), never string-interpolate user input into GROQ.
- Use the CDN (`useCdn: true`) for public reads; use a token-authenticated client only on the server, and never ship tokens to the browser.
- Render Portable Text with `@portabletext/react` (or the framework's equivalent) and explicit components for custom blocks.
- Use `next-sanity`'s `sanityFetch` with tags / Live Content API for revalidation when the frontend is Next.js.

## Done
Studio builds (`npx sanity build`), typegen is up to date with no type errors, and the frontend build passes.