Sanity Best Practices

SanityOfficialPublished by Sanity

Skill
Tool integration
Software development
MIT
No issues found

From the author

Sanity development best practices for schema design, GROQ queries, TypeGen, Visual Editing, images, Portable Text, Studio structure, localization, migrations, Sanity Functions, webhooks, Blueprints, and framework integrations such as Next.js, Nuxt, Astro, Remix, SvelteKit, Angular, Hydrogen, the App SDK, and Studios or apps running in the Sanity Dashboard (defineApplication). Use this skill whenever working with Sanity schemas, defineType or defineField, GROQ or defineQuery, content modeling, Presentation or preview setups, Sanity-powered frontend integrations, event-driven content automation, documentEventHandler, defineDocumentFunction, defineMediaLibraryAssetFunction, @sanity/functions, @sanity/blueprints, sanity.blueprint.ts, event-driven content automation, or when reviewing and fixing a Sanity codebase.

— the description by Sanity

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a comprehensive collection of best practices, architectural patterns, and integration guides for the Sanity ecosystem. It covers the full development lifecycle, including schema design, GROQ query optimization, TypeGen configuration, and framework-specific integrations like Next.js, Angular, and Remix. It also includes guidance on infrastructure management via Blueprints, content automation with Sanity Functions, and building custom applications with the Sanity App SDK.

What it does

Provides standardized patterns for Sanity schema design and content modeling.
Offers integration guides for major frontend frameworks and the Sanity App SDK.
Defines best practices for GROQ query performance and type safety with TypeGen.
Outlines rules for media handling, including video asset management.
Details configuration for Sanity Studio structure and Visual Editing.
Explains infrastructure-as-code workflows using Sanity Blueprints.

When to use it

When starting a new Sanity project or onboarding team members.
When integrating Sanity with frameworks like Next.js, Astro, or Angular.
When optimizing GROQ queries or implementing type-safe data fetching.
When designing complex content schemas or implementing localization.
When setting up live previews, Visual Editing, or custom Studio structures.
When automating content workflows or managing infrastructure via Blueprints.

Advantages

Maintained by Sanity, ensuring alignment with current platform standards.
Reduces technical debt by enforcing consistent schema and query patterns.
Provides clear decision matrices for complex topics like video and localization.
Includes framework-specific guidance to accelerate frontend integration.
Promotes maintainable project structures and type-safe development workflows.

Usage examples

“What are the best practices for handling video in Sanity?”: The skill advises against using standard file assets for production video due to bandwidth costs, recommending the Sanity Media Library with Mux for Enterprise plans or dedicated services like Mux, YouTube, or Vimeo for others.
“How do I set up TypeGen for an Angular monorepo?”: The skill provides a configuration example for studio/sanity.cli.ts to point TypeGen at the Angular source files, ensuring generated types are correctly integrated into the Angular project.
“What is the recommended way to structure singleton documents?”: The skill recommends using explicit document IDs for singleton documents and controlling them via the Studio Structure, while letting Sanity generate IDs for all other document types.
“How should I fetch data in a React app using the App SDK?”: The skill mandates wrapping data-fetching components in Suspense, using documentId as a React key, and preferring useDocuments and useDocumentProjection over raw GROQ hooks.

Install

Download the skill as a ZIP:
https://autogineer.com/agent-skills/sanity-io/sanity-best-practices/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip sanity-best-practices.zip -d .agents/skills

Documentation by Sanity

Sanity Best Practices

Comprehensive best practices and integration guides for Sanity development, maintained by Sanity. Use the quick reference below to load only the one or two topic files that match the task.

When to Apply

Reference these guidelines when:

Setting up a new Sanity project or onboarding
Integrating Sanity with a frontend framework (Next.js, Nuxt, Astro, Remix, SvelteKit, Hydrogen)
Writing GROQ queries or optimizing performance
Designing content schemas
Implementing Visual Editing and live preview
Working with images, Portable Text, or page builders
Configuring Sanity Studio structure
Setting up TypeGen for type safety
Implementing localization
Migrating content from other systems
Building custom apps with the Sanity App SDK
Developing or deploying a Studio or app in the Sanity Dashboard
Managing infrastructure with Blueprints
Automating content workflows with Sanity Functions or webhooks

Global Rules

Let Sanity generate _id values for ordinary documents. Do not create deterministic UUIDs, slug-derived IDs, or legacy-system IDs when creating documents.
Model relationships with reference fields, then resolve related documents with GROQ lookups, source-key fields, or returned _id values from created documents.
Use explicit document IDs mainly for singleton documents controlled by Studio Structure, including localized singletons such as homePage-en.

Video

Do not store or serve video from Sanity file assets for production playback. File assets are delivered as raw downloads with no transcoding or adaptive streaming, and video traffic drives very high bandwidth usage and unexpectedly large bills.
On Enterprise plans with the video add-on, use Sanity Media Library for video: uploads are transcoded and streamed adaptively via Mux. Model video fields with defineVideoField() from sanity/media-library and play them with @mux/mux-player-react using the asset's playback ID.
On other plans, use a dedicated video service: install sanity-plugin-mux-input to upload and manage videos in your Mux account from the Studio, or host video on a platform such as YouTube or Vimeo and store only the embed URL in Sanity.
Small clips and short previews in a file field are acceptable, but any user-facing video at scale must go through Media Library or a streaming service.

Quick Reference

Integration Guides

get-started - Interactive onboarding for new Sanity projects
nextjs - Next.js App Router, Live Content API, standalone Studio
nuxt - Nuxt integration with @nuxtjs/sanity
angular - Angular integration with @sanity/client, signals, resource API
astro - Astro integration with @sanity/astro
remix - React Router / Remix integration
svelte - SvelteKit integration with @sanity/svelte-loader
hydrogen - Shopify Hydrogen with Sanity
project-structure - Standalone Studio and monorepo patterns
app-sdk - Custom applications with Sanity App SDK
dashboard - Studios and apps in the Sanity Dashboard: defineApplication, local dev, deploys, Dashboard hooks
blueprints - Infrastructure as Code: blueprint files, stacks, plan/deploy workflow, error recovery, CI deploys
functions - Automating content workflows with Sanity Functions and webhooks

Topic Guides

groq - GROQ query patterns, type safety, performance optimization
schema - Schema design, field definitions, validation, deprecation patterns
visual-editing - Presentation Tool, Stega, overlays, live preview
page-builder - Page Builder arrays, block components, live editing
portable-text - Rich text rendering and custom components
image - Image schema, URL builder, hotspots, LQIP, Next.js Image
studio-structure - Desk structure, singletons, navigation
typegen - TypeGen configuration, workflow, type utilities
seo - Metadata, sitemaps, Open Graph, JSON-LD
localization - i18n patterns, document vs field-level, locale management
migration - Content import overview (see also migration-html-import)
migration-html-import - HTML to Portable Text with @portabletext/block-tools

How to Use

Start with the single framework or topic guide that best matches the request, then read additional references only when the task crosses concerns. Use these reference files for detailed explanations and code examples:

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

Each reference file contains:

Comprehensive topic or integration coverage
Incorrect and correct code examples
Decision matrices and workflow guidance
Framework-specific patterns where applicable

Files

ATTRIBUTION.mdAdded by AutoGineer873 B
LICENSELicence file added by AutoGineer1.0 KiB
SKILL.md5.4 KiB
references/angular.md18.6 KiB
references/app-sdk.md12.0 KiB
references/astro.md4.9 KiB
references/blueprints.md14.1 KiB
references/dashboard.md6.5 KiB
references/functions.md29.7 KiB
references/get-started.md21.0 KiB
references/groq.md14.4 KiB
references/hydrogen.md6.8 KiB
references/image.md3.3 KiB
references/localization.md12.0 KiB
references/migration-html-import.md5.2 KiB
references/migration.md2.7 KiB
references/nextjs.md16.3 KiB
references/nuxt.md5.9 KiB
references/page-builder.md8.2 KiB
references/portable-text.md9.8 KiB
references/project-structure.md3.5 KiB
references/remix.md8.8 KiB
references/schema.md12.4 KiB
references/seo.md8.3 KiB
references/studio-structure.md4.0 KiB
references/svelte.md10.0 KiB
references/typegen.md6.1 KiB
references/visual-editing.md8.4 KiB

references/dashboard.md

title: Sanity Dashboard Apps description: Rules for Studios and App SDK apps that run in the Sanity Dashboard, including defineApplication config (beta), app visibility, local Dashboard development, first deploys and deployment.appId, and Dashboard hooks from @sanity/sdk-react/dashboard.

Sanity Dashboard Apps

The Sanity Dashboard is where an organization's Studios and App SDK apps run. A Studio or app opts into the Dashboard beta by declaring itself with defineApplication in sanity.cli.ts. That changes how it is created, developed, and deployed. For SDK data hooks (useDocuments, useDocument, and so on), see the app-sdk rule.

Detect the Setup

Read sanity.cli.ts before running dev or deploy:

app: defineApplication({...}) → a Dashboard app (beta). Follow this rule.
app: {organizationId, entry} with no defineApplication → a classic App SDK app. Only the Visibility and Dashboard Hooks sections apply.
No app key → a classic Studio. This rule does not apply.

Boundaries

Always: Save application.id from the first deploy as deployment.appId in sanity.cli.ts
Always: Import Dashboard hooks from @sanity/sdk-react/dashboard, not @sanity/sdk-react
Always: Change slug, title, and visibility in sanity.cli.ts and redeploy; config is the source of truth
Ask first: Before converting an existing classic Studio or app to defineApplication; it opts the project into the Dashboard beta
Never: Pass --create or --external to sanity deploy for a Dashboard app (both rejected)
Never: Call the applications API directly to create or patch an app; use the CLI
Never: Set visibility: 'disabled' on an SDK app; it makes the app unreachable (hidden from the sidebar and 404 on the direct link). Use 'unlisted'.
Never: Wrap Studio components in SanityApp; Studio already provides the SDK

Create

sanity init --dashboard scaffolds a Studio or app with defineApplication. The flag is beta; if npx sanity@latest init --help does not list it, the installed CLI predates it.

# App SDK app
npx sanity@latest init --dashboard --template app-quickstart --organization <org-id> --output-path . --typescript

# Studio
npx sanity@latest init --dashboard --project <project-id> --dataset production --template clean --typescript --output-path studio

--dashboard is ignored for remote templates and Next.js projects.

Config (`sanity.cli.ts`)

App SDK app:

import { defineApplication, defineCliConfig } from 'sanity/cli'

export default defineCliConfig({
  app: defineApplication({
    title: 'Content Reviews',
    slug: 'content-reviews',
    organizationId: 'your-org-id',
    entry: './src/App.tsx',
  }),
  deployment: {
    appId: 'abc123', // added after the first deploy
  },
})

Studio:

import { defineApplication, defineCliConfig } from 'sanity/cli'

export default defineCliConfig({
  api: { projectId: 'your-project-id', dataset: 'production' },
  app: defineApplication({
    title: 'Marketing Studio',
    slug: 'marketing-studio',
    organizationId: 'your-org-id',
  }),
  deployment: {
    autoUpdates: true,
    appId: 'abc123', // added after the first deploy
  },
})

Field	Notes
`title`	Required. The name shown in the Dashboard.
`slug`	Required. The app's address in the organization: lowercase letters, numbers, and hyphens, starting with a letter and ending with a letter or number. Must be free in the organization on first deploy. Changing it and redeploying renames the address.
`organizationId`	Required. The organization whose Dashboard runs the app.
`entry`	SDK apps only; defaults to `./src/App.tsx`. Rejected on a Studio.
`visibility`	See below.

Visibility

visibility controls whether the app appears in the Dashboard sidebar. Set it inside defineApplication, or as app.visibility in a classic app config (requires sanity v6.6.0+). It is applied on deploy.

default — listed in the sidebar (the default when omitted).
unlisted — hidden from the sidebar but still opens via a direct link. Not private: anyone with the link can open it.

Develop

npm run dev (sanity dev) starts a local Dashboard on the configured port (3333 by default) and serves the Studio or app on the next port (3334), loaded into that Dashboard. Open the Dashboard URL the CLI prints, not the app port.

The Dashboard needs a signed-in Sanity account, so a human must complete sign-in in the browser. --load-in-dashboard is ignored; a Dashboard app already runs in the local Dashboard.

Deploy

The first deploy creates the application from slug and title, then deploys to it. It works the same for Studios and apps:

npm run deploy -- --yes --json

Save application.id from the JSON response as deployment.appId in sanity.cli.ts.
Later deploys use the same command and update that application. Without deployment.appId, a later deploy fails because the slug is taken; the error includes the app ID to save.

--dry-run previews without creating or uploading anything.
--title overrides title for this deploy.
A first deploy cannot use --no-build, because the new app ID is built into the bundle.
A Studio also needs api.projectId. studioHost and --url do not apply; the address comes from slug.
Agent terminals may disable prompts (TERM=dumb). Use these flags rather than changing terminal settings.

Deployed apps are served at https://<organizationId>.sanity.run/applications/<appId> and Studios at https://<organizationId>.sanity.run/studios/<appId>.

Dashboard Hooks

Hooks that talk to the Dashboard are exported from @sanity/sdk-react/dashboard (App SDK v3+). They are not in the root @sanity/sdk-react export.

Hook	Use
`useNavigate`	Keep the app's router in sync with the Dashboard URL
`useNavigateToStudioDocument`	Open a document in its Studio
`useOrganizationId`	The organization selected in the Dashboard
`useApplications` / `useApplication`	Apps installed in the Dashboard
`useWindowTitle`	Set the browser tab title

import { useNavigateToStudioDocument } from '@sanity/sdk-react/dashboard'

In an SDK app, call them inside SanityApp, like any SDK hook.

In a Studio (sanity v6.10.0+), Studio mounts an SDK instance for the workspace, so SDK hooks work in tools, panes, and inputs without a provider. Add @sanity/sdk-react to the Studio's dependencies to import them. Do not add SanityApp: its auth boundary would take over the Studio UI.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by

Sanity

Publisher

Sanity (Official)

Source

sanity-io/agent-toolkit · skills/sanity-best-practices · commit 3ed3a14

Licence

MIT License (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-09

AutoGineer is not affiliated with or endorsed by Sanity or Sanity.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download sanity-best-practices.zip

From the author

AutoGineer summary

What it does

When to use it

Advantages

Usage examples

Install

Documentation by Sanity

Sanity Best Practices

When to Apply

Global Rules

Video

Quick Reference

Integration Guides

Topic Guides

How to Use

Files

references/dashboard.md

title: Sanity Dashboard Apps description: Rules for Studios and App SDK apps that run in the Sanity Dashboard, including defineApplication config (beta), app visibility, local Dashboard development, first deploys and deployment.appId, and Dashboard hooks from @sanity/sdk-react/dashboard.

Sanity Dashboard Apps

Detect the Setup

Boundaries

Create

Config (sanity.cli.ts)

Visibility

Develop

Deploy

Dashboard Hooks

Requirements and compatibility

Security

Attribution and licence

Related skills

Implement

Source Driven Development

Write Swift

Cardputer Buddy

Typescript Pro

Scala Pro

Download ZIP

Config (`sanity.cli.ts`)