sanity-best-practices

Original source / Raw SKILL.md

---
name: sanity-best-practices
description: Comprehensive Sanity development best practices covering GROQ performance, schema design, Visual Editing, images, Portable Text, page builders, Studio configuration, TypeGen, localization, and migrations. Use this skill when building, reviewing, or optimizing Sanity applications.
license: MIT
metadata:
  author: sanity
  version: "1.0.0"
---

# Sanity Best Practices

Comprehensive best practices guide for Sanity development, maintained by Sanity. Contains rules across 10 categories, prioritized by impact to guide schema design, query optimization, and frontend integration.

## When to Apply

Reference these guidelines when:
- 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

## Rule Categories by Priority

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | GROQ Performance | CRITICAL | `groq-` |
| 2 | Schema Design | HIGH | `schema-` |
| 3 | Visual Editing | HIGH | `visual-` |
| 4 | Images | HIGH | `image-` |
| 5 | Portable Text | HIGH | `pte-` |
| 6 | Page Builder | MEDIUM | `pagebuilder-` |
| 7 | Studio Configuration | MEDIUM | `studio-` |
| 8 | TypeGen | MEDIUM | `typegen-` |
| 9 | Localization | MEDIUM | `i18n-` |
| 10 | Migration | LOW-MEDIUM | `migration-` |

## How to Use

Read individual rule files for detailed explanations and code examples:

```
rules/groq-optimizable-filters.md
rules/schema-data-over-presentation.md
rules/_sections.md
```

Each rule file contains:
- Brief explanation of why it matters
- Incorrect code example with explanation
- Correct code example with explanation
- Additional context and references
- Framework-specific notes (when applicable)

## Framework Integration

Framework-specific guidance (Next.js, Astro, Remix, etc.) is available in the `rules/*.mdc` files in the repository root. The skill references them when relevant but doesn't duplicate content.

## Full Compiled Document

For the complete guide with all rules expanded: `AGENTS.md`


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### rules/groq-optimizable-filters.md

```markdown
---
title: Use Optimizable Filters First
description: Stack optimizable filters first to leverage indexes and avoid full dataset scans
tags: groq, performance, indexes, query-optimization
---

## Use Optimizable Filters First

GROQ uses indexes for **optimizable** filters. Non-optimizable filters scan ALL documents, causing severe performance degradation on large datasets.

**Incorrect (scans everything):**

```groq
// Comparing two attributes - cannot use index
*[salePrice < displayPrice]

// Join in filter - expensive reference resolution
*[author->name == "Bob Woodward"]
```

**Correct (uses indexes):**

```groq
// Stack optimizable filters FIRST to reduce search space
*[_type == "product" && defined(salePrice) && salePrice < displayPrice]

// Use _ref for direct comparison (no resolution needed)
*[_type == "post" && author._ref == "author-bob-woodward-id"]
```

### Optimizable Filter Patterns

| Pattern | Optimizable | Example |
|---------|-------------|---------|
| `_type == "x"` | ✅ Yes | `*[_type == "post"]` |
| `_id == "x"` | ✅ Yes | `*[_id == "abc123"]` |
| `slug.current == $slug` | ✅ Yes | `*[slug.current == "hello"]` |
| `defined(field)` | ✅ Yes | `*[defined(publishedAt)]` |
| `references($id)` | ✅ Yes | `*[references("author-123")]` |
| `field->attr == x` | ❌ No | Resolves reference for every doc |
| `fieldA < fieldB` | ❌ No | Compares two attributes |

Reference: [High Performance GROQ](https://www.sanity.io/docs/developer-guides/high-performance-groq)

```

### rules/_sections.md

```markdown
# Section Definitions

This file defines the rule categories for Sanity best practices. Rules are automatically assigned to sections based on their filename prefix.

---

## 1. GROQ Performance (groq)
Query optimization, index usage, and performance patterns. Covers optimizable filters, avoiding joins in filters, cursor pagination, and projection best practices.

## 2. Schema Design (schema)
Content modeling philosophy, field patterns, references vs objects, validation, and safe deprecation. Foundation for maintainable, scalable content architecture.

## 3. Visual Editing (visual)
Presentation Tool setup, Content Source Maps (Stega), overlays, and live preview configuration. Critical for editor experience and real-time content editing.

## 4. Images (image)
Image schema with hotspots, URL builder patterns, LQIP (blur placeholders), and Next.js Image integration.

## 5. Portable Text (pte)
Rich text rendering, custom block types, mark components, and presentation queries for live editing.

## 6. Page Builder (pagebuilder)
Flexible page composition with block arrays, component rendering patterns, and TypeScript typing.

## 7. Studio Configuration (studio)
Desk structure customization, singleton patterns, document views, and navigation organization.

## 8. TypeGen (typegen)
TypeScript type generation from schema and queries, configuration patterns, and workflow integration.

## 9. Localization (i18n)
Document-level and field-level internationalization, locale management, and querying patterns.

## 10. Migration (migration)
Content import from HTML/Markdown, image handling, and schema validation during migrations.

```