# Sanity Core Examples

> Client setup, GROQ queries, error handling, and TypeGen patterns. See [SKILL.md](../SKILL.md) for core concepts.

**Schemas:** See [schemas.md](schemas.md). **Rich content:** See [rich-content.md](rich-content.md). **Mutations:** See [mutations.md](mutations.md).

---

## Pattern 1: Client Setup — Public Reads

### Good Example — Typed Client with API Version

```typescript
// lib/sanity-client.ts
import { createClient } from "@sanity/client";

const PROJECT_ID = process.env.SANITY_PROJECT_ID!;
const DATASET = process.env.SANITY_DATASET!;
const API_VERSION = "2025-02-19";

export const client = createClient({
  projectId: PROJECT_ID,
  dataset: DATASET,
  apiVersion: API_VERSION,
  useCdn: true, // Edge-cached for public reads
});
```

**Why good:** `apiVersion` pins API behavior to a known date, `useCdn: true` serves cached responses from CDN edge, named constants for config values, named export

### Bad Example — Missing API Version

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

// BAD: No apiVersion, hardcoded values
const client = createClient({
  projectId: "abc123",
  dataset: "production",
});
```

**Why bad:** Missing `apiVersion` uses legacy API behavior that may change without warning, hardcoded project ID prevents environment switching, no `useCdn` defaults to `false` (always hitting origin)

---

## Pattern 2: Client Setup — Authenticated / Preview

### Good Example — Token-Based Client for Preview Mode

```typescript
// lib/sanity-preview-client.ts
import { createClient } from "@sanity/client";

const PROJECT_ID = process.env.SANITY_PROJECT_ID!;
const DATASET = process.env.SANITY_DATASET!;
const API_VERSION = "2025-02-19";
const API_TOKEN = process.env.SANITY_API_TOKEN!;

// Preview client: sees drafts, no CDN cache
export const previewClient = createClient({
  projectId: PROJECT_ID,
  dataset: DATASET,
  apiVersion: API_VERSION,
  useCdn: false, // Must be false when using token
  token: API_TOKEN,
  perspective: "previewDrafts", // Include draft documents
});
```

**Why good:** `useCdn: false` required with tokens (CDN ignores auth), `perspective: 'previewDrafts'` returns draft documents overlaid on published, server-only token kept in environment variable

### Good Example — Dual Client Pattern

```typescript
// lib/sanity-clients.ts
import { createClient } from "@sanity/client";

const PROJECT_ID = process.env.SANITY_PROJECT_ID!;
const DATASET = process.env.SANITY_DATASET!;
const API_VERSION = "2025-02-19";

// Public reads — CDN cached
export const client = createClient({
  projectId: PROJECT_ID,
  dataset: DATASET,
  apiVersion: API_VERSION,
  useCdn: true,
});

// Preview reads — fresh, includes drafts (server-only)
export const previewClient = createClient({
  projectId: PROJECT_ID,
  dataset: DATASET,
  apiVersion: API_VERSION,
  useCdn: false,
  token: process.env.SANITY_API_TOKEN!,
  perspective: "previewDrafts",
});

// Choose client based on preview mode
export function getClient(preview = false) {
  return preview ? previewClient : client;
}
```

**Why good:** Separate clients for public and preview, factory function selects the right client, preview token never sent to CDN, shared config for consistency

---

## Pattern 3: GROQ Queries — Filters and Projections

### Good Example — Parameterized Query with defineQuery

```typescript
import { defineQuery } from "groq";

// List query: multiple documents
const POSTS_QUERY = defineQuery(`
  *[_type == "post" && published == true]{
    _id,
    title,
    "slug": slug.current,
    "authorName": author->name,
    "excerpt": pt::text(body)[0...200],
    publishedAt
  } | order(publishedAt desc) [0...10]
`);

// Detail query: single document by slug
const POST_BY_SLUG_QUERY = defineQuery(`
  *[_type == "post" && slug.current == $slug][0]{
    _id,
    title,
    body,
    publishedAt,
    "author": author->{
      name,
      "imageUrl": image.asset->url
    },
    "categories": categories[]->{ _id, title },
    "relatedPosts": *[
      _type == "post"
      && _id != ^._id
      && count(categories[@._ref in ^.^.categories[]._ref]) > 0
    ][0...3]{ _id, title, "slug": slug.current }
  }
`);

// Fetch with parameters
const post = await client.fetch(POST_BY_SLUG_QUERY, { slug: "my-post" });
```

**Why good:** `defineQuery()` enables TypeGen type inference, `$slug` parameter prevents injection, `[0]` returns single object (not array), `->` dereferences references, `pt::text()` extracts plain text from Portable Text, `^` references parent scope in subqueries

### Bad Example — String Interpolation

```typescript
// BAD: GROQ injection vulnerability
async function getPostBySlug(slug: string) {
  const query = `*[_type == "post" && slug.current == "${slug}"][0]`;
  return client.fetch(query);
}
```

**Why bad:** User-controlled `slug` value interpolated directly into GROQ string, enables GROQ injection attacks (e.g., `" || true] | order(_createdAt desc)[0]{"token": identity()}//`), always use `$param` parameters instead

---

## Pattern 4: GROQ Queries — Advanced Patterns

### Good Example — Combined Query (Multiple Results in One Fetch)

```typescript
const PAGE_QUERY = defineQuery(`{
  "settings": *[_type == "siteSettings"][0]{
    title,
    description,
    "logoUrl": logo.asset->url
  },
  "featuredPosts": *[_type == "post" && featured == true] | order(publishedAt desc) [0...3]{
    _id,
    title,
    "slug": slug.current,
    publishedAt
  },
  "categories": *[_type == "category"] | order(title asc){
    _id,
    title,
    "postCount": count(*[_type == "post" && references(^._id)])
  }
}`);

// Single fetch returns all three datasets
const pageData = await client.fetch(PAGE_QUERY);
// pageData.settings, pageData.featuredPosts, pageData.categories
```

**Why good:** Single network request for multiple related datasets, each sub-query independently filtered and projected, `count()` with subquery for computed fields, reduces page load time

### Good Example — Conditional Projections

```typescript
const CONTENT_BLOCKS_QUERY = defineQuery(`
  *[_type == "page" && slug.current == $slug][0]{
    title,
    "content": content[]{
      _type == "hero" => {
        _type,
        heading,
        "backgroundUrl": background.asset->url
      },
      _type == "textBlock" => {
        _type,
        body
      },
      _type == "gallery" => {
        _type,
        "images": images[]{
          "url": asset->url,
          alt,
          caption
        }
      }
    }
  }
`);
```

**Why good:** Conditional projections return different fields based on `_type`, polymorphic content blocks handled in a single query, each block type gets only its relevant fields

---

## Pattern 5: Error Handling

### Good Example — Consistent Fetch Error Handling

```typescript
async function fetchPosts() {
  try {
    const posts = await client.fetch(POSTS_QUERY);
    return posts;
  } catch (error) {
    // Sanity client throws on network errors and GROQ syntax errors
    const message = error instanceof Error ? error.message : "Unknown error";
    throw new Error(`Failed to fetch posts: ${message}`);
  }
}

// For single documents that might not exist
async function fetchPostBySlug(slug: string) {
  const post = await client.fetch(POST_BY_SLUG_QUERY, { slug });

  if (!post) {
    // [0] returns null when no documents match
    throw new Error(`Post not found: ${slug}`);
  }

  return post;
}
```

**Why good:** `client.fetch` throws on network/GROQ errors (not a `{ data, error }` tuple), null check for `[0]` queries that may return no results, descriptive error messages with context

### Bad Example — No Null Handling

```typescript
// BAD: Assumes document always exists
async function getPost(slug: string) {
  const post = await client.fetch(POST_BY_SLUG_QUERY, { slug });
  return post.title; // TypeError if post is null!
}
```

**Why bad:** GROQ `[0]` returns `null` if no documents match, accessing `.title` on `null` throws at runtime, must check for `null` before accessing properties

---

## Pattern 6: TypeGen Integration

### Good Example — Full TypeGen Workflow

```typescript
// sanity.cli.ts
import { defineCliConfig } from "sanity/cli";

// NOTE: default export required by Sanity CLI tooling
export default defineCliConfig({
  api: {
    projectId: "your-project-id",
    dataset: "production",
  },
  typegen: {
    enabled: true,
    path: "./src/**/*.{ts,tsx}",
    schema: "schema.json",
    generates: "./sanity.types.ts",
    overloadClientMethods: true,
  },
});
```

```typescript
// queries/post-queries.ts
import { defineQuery } from "groq";

// TypeGen finds these and generates result types
export const allPostsQuery = defineQuery(`
  *[_type == "post"]{
    _id,
    title,
    "slug": slug.current,
    publishedAt
  } | order(publishedAt desc)
`);

export const postBySlugQuery = defineQuery(`
  *[_type == "post" && slug.current == $slug][0]{
    _id,
    title,
    body,
    "author": author->{name, "imageUrl": image.asset->url}
  }
`);
```

```typescript
// lib/fetchers.ts
import type {
  AllPostsQueryResult,
  PostBySlugQueryResult,
} from "../sanity.types";
import { allPostsQuery, postBySlugQuery } from "../queries/post-queries";
import { client } from "./sanity-client";

// With overloadClientMethods: true, return types are inferred
export async function getAllPosts(): Promise<AllPostsQueryResult> {
  return client.fetch(allPostsQuery);
}

export async function getPostBySlug(
  slug: string,
): Promise<PostBySlugQueryResult> {
  return client.fetch(postBySlugQuery, { slug });
}
```

**Why good:** `overloadClientMethods: true` makes `client.fetch` aware of query types, generated types match the exact shape of GROQ projections, queries in dedicated files for organization, explicit return types for clarity

### Bad Example — Inline Queries Without defineQuery

```typescript
// BAD: TypeGen cannot type inline queries
const posts = await client.fetch(`*[_type == "post"]{ title }`);
// posts is typed as 'any' — no type safety
```

**Why bad:** TypeGen only generates types for queries assigned to named variables using `defineQuery()` or the `groq` template literal, inline strings produce `any` return type, no type safety on the result

---

_For schema definitions, see [schemas.md](schemas.md). For Portable Text and images, see [rich-content.md](rich-content.md). For mutations and real-time, see [mutations.md](mutations.md)._

# Sanity Mutations & Real-Time Examples

> Create, patch, delete, transactions, and real-time listeners. See [SKILL.md](../SKILL.md) for core concepts and [core.md](core.md) for client setup.

**Prerequisites**: Understand client setup from core examples first. Mutations require a client configured with `useCdn: false` and a write-capable API token.

---

## Pattern 1: Creating Documents

### Good Example — Create with Type Safety

```typescript
import { client } from "../lib/sanity-client";

// create() auto-generates _id if not provided
const newPost = await client.create({
  _type: "post",
  title: "New Blog Post",
  slug: { _type: "slug", current: "new-blog-post" },
  published: false,
  publishedAt: new Date().toISOString(),
});
// newPost._id is the auto-generated document ID

// createIfNotExists() — only creates if _id doesn't exist
await client.createIfNotExists({
  _id: "singleton-site-settings",
  _type: "siteSettings",
  title: "My Site",
});

// createOrReplace() — overwrites entirely if document exists
await client.createOrReplace({
  _id: "singleton-site-settings",
  _type: "siteSettings",
  title: "Updated Site Title",
  description: "New description",
});
```

**Why good:** `create()` for new documents with auto-generated IDs, `createIfNotExists()` for idempotent initialization, `createOrReplace()` for singletons that should always reflect the latest state, slug includes `_type: "slug"` as required by the schema

### Bad Example — Create with Existing ID

```typescript
// BAD: create() with an _id that already exists will error
await client.create({
  _id: "existing-doc-id",
  _type: "post",
  title: "This will fail",
});
```

**Why bad:** `create()` fails if a document with the given `_id` already exists — use `createOrReplace()` or `createIfNotExists()` for idempotent operations

---

## Pattern 2: Patching Documents

### Good Example — Various Patch Operations

```typescript
// Set fields
await client
  .patch("post-123")
  .set({
    title: "Updated Title",
    published: true,
    publishedAt: new Date().toISOString(),
  })
  .commit();

// Unset (remove) fields
await client.patch("post-123").unset(["temporaryFlag", "draftNotes"]).commit();

// Increment/decrement numeric fields
await client.patch("post-123").inc({ viewCount: 1 }).commit();
await client.patch("post-123").dec({ remainingSlots: 1 }).commit();

// Insert into an array at a specific position
await client
  .patch("post-123")
  .insert("after", "tags[-1]", [
    { _key: crypto.randomUUID(), label: "typescript" },
  ])
  .commit();

// Append to end of array
await client
  .patch("post-123")
  .append("tags", [{ _key: crypto.randomUUID(), label: "new-tag" }])
  .commit();

// Chain multiple patch operations
await client
  .patch("post-123")
  .set({ title: "New Title" })
  .inc({ revisionCount: 1 })
  .commit();
```

**Why good:** `.commit()` always called to send the mutation, `_key` included on array items (required by Sanity), `crypto.randomUUID()` generates unique keys, multiple operations chained in a single patch

### Bad Example — Missing commit()

```typescript
// BAD: Patch without .commit() does nothing!
client.patch("post-123").set({ title: "This is never sent" });
// No network request made — mutation is discarded
```

**Why bad:** Without `.commit()`, the patch is constructed but never sent to the API — this is a silent no-op

---

## Pattern 3: Deleting Documents

### Good Example — Delete by ID

```typescript
// Delete a single document
await client.delete("post-123");

// Delete with specific options
await client.delete("post-123", {
  visibility: "async", // Return immediately, sync in background
});
```

**Why good:** Simple single-document deletion by ID, `visibility` option controls when the request returns

---

## Pattern 4: Transactions (Atomic Multi-Mutation)

### Good Example — Grouped Mutations

```typescript
// All mutations in a transaction succeed or fail together
await client
  .transaction()
  .create({
    _type: "activityLog",
    action: "archived",
    documentId: "post-123",
    timestamp: new Date().toISOString(),
  })
  .patch("post-123", (p) =>
    p.set({ archived: true, archivedAt: new Date().toISOString() }),
  )
  .commit();

// Transaction with multiple deletes
const idsToDelete = ["post-1", "post-2", "post-3"];
const tx = client.transaction();
for (const id of idsToDelete) {
  tx.delete(id);
}
await tx.commit();
```

**Why good:** Transaction ensures atomicity (both log creation and archival happen or neither does), callback style for patch within transaction, batch deletes in a single atomic operation

---

## Pattern 5: Mutation Visibility Options

### Good Example — Controlling Write Consistency

```typescript
// sync (default): Waits for mutation to be committed AND indexed
// Queries immediately see the change
await client.create(doc, { visibility: "sync" });

// async: Returns after commit, indexes in background
// Faster response, but queries may not reflect the change immediately
await client.create(doc, { visibility: "async" });

// Dry run: Validates without applying
const result = await client.create(doc, { dryRun: true });
// Useful for validating mutations before executing them
```

**Why good:** `sync` for consistency-critical operations (user sees their own change), `async` for bulk operations where speed matters, `dryRun` for validation without side effects

---

## Pattern 6: Real-Time Listeners

### Good Example — Subscribe to Document Changes

```typescript
// Listen for changes to published posts
const LISTENER_QUERY = `*[_type == "post" && published == true]`;

const subscription = client.listen(LISTENER_QUERY).subscribe({
  next: (update) => {
    if (update.type === "mutation") {
      const { documentId, transition, result } = update;
      // transition: 'update' | 'appear' | 'disappear'

      switch (transition) {
        case "appear":
          // Document now matches the filter (new or newly matching)
          console.log(`New post appeared: ${documentId}`);
          break;
        case "update":
          // Existing matching document was modified
          console.log(`Post updated: ${documentId}`);
          break;
        case "disappear":
          // Document no longer matches the filter (deleted or no longer matching)
          console.log(`Post disappeared: ${documentId}`);
          break;
      }
    }
  },
  error: (err) => {
    console.error("Listener error:", err.message);
  },
});

// Cleanup: always unsubscribe when done
subscription.unsubscribe();
```

**Why good:** Observable-based subscription with error handling, `transition` field indicates what happened, cleanup via `unsubscribe()` prevents connection leaks, GROQ filter scopes to relevant documents

### Good Example — Listener with Options

```typescript
// Listen with include options
const subscription = client
  .listen(
    `*[_type == "post"]`,
    {}, // No parameters for this query
    {
      includeResult: true, // Include the full document in the event
      includePreviousRevision: false, // Don't include the previous version
      visibility: "query", // Only fire when the change is queryable
    },
  )
  .subscribe({
    next: (update) => {
      if (update.type === "mutation" && update.result) {
        // update.result contains the full document
        console.log("Updated document:", update.result.title);
      }
    },
    error: (err) => console.error(err),
  });
```

**Why good:** `includeResult: true` gives the full document without a separate fetch, `visibility: "query"` ensures the event fires only when the change is visible to queries (consistent state)

### Important Caveats

- **Projections are ignored** — `client.listen()` only uses the filter portion of a GROQ query. Projections, ordering, and slicing have no effect.
- **Reconnection** — The listener automatically reconnects on disconnection, but events during the gap may be missed. For critical use cases, combine with periodic re-fetching.
- **For production frontends** — Evaluate the newer Sanity Live Content API as a simpler alternative to raw listeners.

---

_For client setup and GROQ, see [core.md](core.md). For schema definitions, see [schemas.md](schemas.md). For Portable Text and images, see [rich-content.md](rich-content.md)._

# Sanity Rich Content Examples

> Portable Text rendering with @portabletext/react and image URL builder with @sanity/image-url. See [SKILL.md](../SKILL.md) for core concepts and [core.md](core.md) for client setup.

**Prerequisites**: Understand client setup and GROQ queries from core examples first.

---

## Pattern 1: Basic Portable Text Rendering

### Good Example — PortableText with Custom Components

```tsx
import { PortableText } from "@portabletext/react";
import type {
  PortableTextComponents,
  PortableTextBlock,
} from "@portabletext/react";
import { urlFor } from "../lib/sanity-image";

const components: PortableTextComponents = {
  types: {
    image: ({ value }) => {
      if (!value?.asset?._ref) return null;
      return (
        <figure>
          <img
            src={urlFor(value).width(800).auto("format").url()}
            alt={value.alt || ""}
            loading="lazy"
          />
          {value.caption && <figcaption>{value.caption}</figcaption>}
        </figure>
      );
    },
    code: ({ value }) => (
      <pre data-language={value.language}>
        <code>{value.code}</code>
      </pre>
    ),
    callout: ({ value }) => (
      <aside data-tone={value.tone}>
        <PortableText value={value.text} />
      </aside>
    ),
  },
  marks: {
    link: ({ children, value }) => {
      const isExternal = value.href && !value.href.startsWith("/");
      return (
        <a
          href={value.href}
          rel={isExternal ? "noopener noreferrer" : undefined}
          target={isExternal ? "_blank" : undefined}
        >
          {children}
        </a>
      );
    },
    highlight: ({ children }) => <mark>{children}</mark>,
    inlineCode: ({ children }) => <code>{children}</code>,
  },
  block: {
    h2: ({ children }) => <h2>{children}</h2>,
    h3: ({ children }) => <h3>{children}</h3>,
    blockquote: ({ children }) => <blockquote>{children}</blockquote>,
    normal: ({ children }) => <p>{children}</p>,
  },
  list: {
    bullet: ({ children }) => <ul>{children}</ul>,
    number: ({ children }) => <ol>{children}</ol>,
  },
};

function ArticleBody({ body }: { body: PortableTextBlock[] }) {
  return <PortableText value={body} components={components} />;
}
export { ArticleBody };
```

**Why good:** Custom renderers for image, code, and callout block types; external links get security attributes; images use `urlFor` for optimized delivery; null check for missing image assets; lazy loading for performance; named export

### Bad Example — Using Deprecated Package

```tsx
// BAD: @sanity/block-content-to-react is deprecated
import BlockContent from "@sanity/block-content-to-react";

// Uses old "serializers" API, unmaintained
<BlockContent blocks={body} serializers={serializers} />;
```

**Why bad:** `@sanity/block-content-to-react` is deprecated and unmaintained, replaced by `@portabletext/react` which uses "components" instead of "serializers"

---

## Pattern 2: Image URL Builder Setup

### Good Example — Reusable urlFor Helper

```typescript
// lib/sanity-image.ts
import { createImageUrlBuilder } from "@sanity/image-url";
import type { SanityImageSource } from "@sanity/image-url";
import { client } from "./sanity-client";

const builder = createImageUrlBuilder(client);

export function urlFor(source: SanityImageSource) {
  return builder.image(source);
}
```

**Why good:** `createImageUrlBuilder` reads projectId and dataset from the client config, `urlFor` returns a chainable builder, `SanityImageSource` type handles all image input formats (asset ref, full image object, URL)

### Bad Example — Manual URL Construction

```typescript
// BAD: Manually constructing image URLs
function getImageUrl(ref: string) {
  const [, id, dimensions, format] = ref.split("-");
  return `https://cdn.sanity.io/images/projectId/dataset/${id}-${dimensions}.${format}`;
}
```

**Why bad:** Hardcoded project/dataset, ignores crop and hotspot metadata, no format optimization, no responsive sizing, breaks if Sanity changes CDN URL format

---

## Pattern 3: Responsive Images

### Good Example — Responsive srcSet with Auto Format

```tsx
import { urlFor } from "../lib/sanity-image";
import type { SanityImageSource } from "@sanity/image-url";

const WIDTHS = [400, 800, 1200, 1600] as const;
const DEFAULT_WIDTH = 800;

function ResponsiveImage({
  image,
  alt,
  sizes = "(max-width: 600px) 400px, (max-width: 1200px) 800px, 1200px",
}: {
  image: SanityImageSource;
  alt: string;
  sizes?: string;
}) {
  return (
    <img
      src={urlFor(image).width(DEFAULT_WIDTH).auto("format").url()}
      srcSet={WIDTHS.map(
        (w) => `${urlFor(image).width(w).auto("format").url()} ${w}w`,
      ).join(", ")}
      sizes={sizes}
      alt={alt}
      loading="lazy"
    />
  );
}
export { ResponsiveImage };
```

**Why good:** Named constants for widths, `.auto("format")` serves WebP/AVIF when the browser supports it, `srcSet` with width descriptors for responsive delivery, `sizes` attribute guides browser selection, lazy loading, crop and hotspot metadata automatically applied when passing the full image field

---

## Pattern 4: Image Transformations

### Good Example — Common Transformation Patterns

```typescript
import { urlFor } from "../lib/sanity-image";

// Fixed-size thumbnail
const thumbnailUrl = urlFor(image).width(150).height(150).fit("crop").url();

// Aspect ratio crop
const heroUrl = urlFor(image)
  .width(1200)
  .height(400)
  .fit("crop")
  .auto("format")
  .url();

// Blur placeholder (for progressive loading)
const blurUrl = urlFor(image).width(20).blur(50).url();

// Specific format
const pngUrl = urlFor(image).width(800).format("png").url();

// Quality control
const compressedUrl = urlFor(image).width(800).quality(75).auto("format").url();
```

**Why good:** `.fit("crop")` respects hotspot when cropping, low-res blur for placeholder loading patterns, `.auto("format")` for automatic format selection, `.quality()` for size/quality tradeoff

---

## Pattern 5: Querying Portable Text as Plain Text

### Good Example — Using pt::text() in GROQ

```typescript
import { defineQuery } from "groq";

// Extract plain text from Portable Text for excerpts and search
const POSTS_WITH_EXCERPT_QUERY = defineQuery(`
  *[_type == "post" && published == true]{
    _id,
    title,
    "slug": slug.current,
    "excerpt": pt::text(body)[0...200],
    publishedAt
  } | order(publishedAt desc)
`);

// Full-text search across Portable Text content
const SEARCH_POSTS_QUERY = defineQuery(`
  *[_type == "post" && pt::text(body) match $searchTerm]{
    _id,
    title,
    "slug": slug.current,
    "excerpt": pt::text(body)[0...200]
  }
`);

const results = await client.fetch(SEARCH_POSTS_QUERY, {
  searchTerm: "typescript*",
});
```

**Why good:** `pt::text()` converts Portable Text to plain text within GROQ (no client-side processing), string slicing `[0...200]` creates excerpts server-side, `match` operator for full-text search with wildcard support, parameterized search term prevents injection

---

_For schema definitions, see [schemas.md](schemas.md). For mutations and real-time, see [mutations.md](mutations.md)._

# Sanity Schema Examples

> Schema definitions with defineType, defineField, defineArrayMember. See [SKILL.md](../SKILL.md) for core concepts and [core.md](core.md) for client setup.

**Prerequisites**: Understand client setup from core examples first.

---

## Pattern 1: Document Type with Validation

### Good Example — Complete Document Schema

```typescript
// schemas/post.ts
import { defineType, defineField, defineArrayMember } from "sanity";

export const postType = defineType({
  name: "post",
  title: "Blog Post",
  type: "document",
  fields: [
    defineField({
      name: "title",
      title: "Title",
      type: "string",
      validation: (rule) => rule.required().min(5).max(120),
    }),
    defineField({
      name: "slug",
      title: "Slug",
      type: "slug",
      options: {
        source: "title",
        maxLength: 96,
      },
      validation: (rule) => rule.required(),
    }),
    defineField({
      name: "author",
      title: "Author",
      type: "reference",
      to: [{ type: "author" }],
      validation: (rule) => rule.required(),
    }),
    defineField({
      name: "mainImage",
      title: "Main Image",
      type: "image",
      options: { hotspot: true },
      fields: [
        defineField({
          name: "alt",
          title: "Alt Text",
          type: "string",
          validation: (rule) => rule.required(),
        }),
      ],
    }),
    defineField({
      name: "categories",
      title: "Categories",
      type: "array",
      of: [
        defineArrayMember({ type: "reference", to: [{ type: "category" }] }),
      ],
    }),
    defineField({
      name: "publishedAt",
      title: "Published At",
      type: "datetime",
    }),
    defineField({
      name: "body",
      title: "Body",
      type: "array",
      of: [
        defineArrayMember({ type: "block" }),
        defineArrayMember({
          type: "image",
          options: { hotspot: true },
          fields: [
            defineField({
              name: "alt",
              title: "Alt Text",
              type: "string",
            }),
            defineField({
              name: "caption",
              title: "Caption",
              type: "string",
            }),
          ],
        }),
        defineArrayMember({
          type: "object",
          name: "code",
          title: "Code Block",
          fields: [
            defineField({
              name: "language",
              title: "Language",
              type: "string",
            }),
            defineField({ name: "code", title: "Code", type: "text" }),
          ],
        }),
      ],
    }),
  ],
  preview: {
    select: {
      title: "title",
      author: "author.name",
      media: "mainImage",
    },
    prepare(selection) {
      const { author } = selection;
      return {
        ...selection,
        subtitle: author ? `by ${author}` : "No author",
      };
    },
  },
  orderings: [
    {
      title: "Published Date, New",
      name: "publishedAtDesc",
      by: [{ field: "publishedAt", direction: "desc" }],
    },
  ],
});
```

**Why good:** `defineType`/`defineField`/`defineArrayMember` provide IDE autocomplete, validation rules enforce content quality, `hotspot: true` enables focal point cropping, alt text required on images for accessibility, body supports blocks (rich text), images, and custom code blocks, preview customizes Studio list appearance, orderings define sort options in Studio

---

## Pattern 2: Object Types (Reusable, Non-Document)

### Good Example — Reusable Object Schema

```typescript
// schemas/objects/seo.ts
import { defineType, defineField } from "sanity";

const SEO_TITLE_MAX_LENGTH = 60;
const SEO_DESCRIPTION_MAX_LENGTH = 160;

export const seoType = defineType({
  name: "seo",
  title: "SEO",
  type: "object",
  fields: [
    defineField({
      name: "metaTitle",
      title: "Meta Title",
      type: "string",
      validation: (rule) => rule.max(SEO_TITLE_MAX_LENGTH),
      description: `Max ${SEO_TITLE_MAX_LENGTH} characters for search engines`,
    }),
    defineField({
      name: "metaDescription",
      title: "Meta Description",
      type: "text",
      rows: 3,
      validation: (rule) => rule.max(SEO_DESCRIPTION_MAX_LENGTH),
      description: `Max ${SEO_DESCRIPTION_MAX_LENGTH} characters`,
    }),
    defineField({
      name: "ogImage",
      title: "Open Graph Image",
      type: "image",
      description: "Recommended: 1200x630px",
    }),
  ],
});
```

**Why good:** Object type (not document) — can be embedded in any document via `type: "seo"`, named constants for magic numbers, `description` guides editors, `rows: 3` on text field improves Studio UX

### Usage in a Document

```typescript
// In a page document
defineField({
  name: "seo",
  title: "SEO Settings",
  type: "seo", // References the object type defined above
}),
```

---

## Pattern 3: Reference Fields

### Good Example — Reference with Filtering

```typescript
defineField({
  name: "author",
  title: "Author",
  type: "reference",
  to: [{ type: "author" }],
  validation: (rule) => rule.required(),
}),

// Reference to multiple types (polymorphic)
defineField({
  name: "relatedContent",
  title: "Related Content",
  type: "array",
  of: [
    defineArrayMember({
      type: "reference",
      to: [{ type: "post" }, { type: "page" }, { type: "product" }],
    }),
  ],
}),

// Reference with filter (only show published authors)
defineField({
  name: "reviewer",
  title: "Reviewer",
  type: "reference",
  to: [{ type: "author" }],
  options: {
    filter: "active == true",
    filterParams: {},
  },
}),
```

**Why good:** Single reference with validation, polymorphic reference allows multiple target types, `options.filter` limits reference picker in Studio to matching documents

---

## Pattern 4: Image and File Fields

### Good Example — Image with Metadata

```typescript
defineField({
  name: "mainImage",
  title: "Main Image",
  type: "image",
  options: {
    hotspot: true, // Enables focal point selection in Studio
  },
  fields: [
    defineField({
      name: "alt",
      title: "Alternative Text",
      type: "string",
      validation: (rule) =>
        rule.custom((alt, context) => {
          // Require alt text when an image is set
          const parent = context.parent as { asset?: { _ref?: string } };
          if (parent?.asset?._ref && !alt) {
            return "Alt text is required when an image is set";
          }
          return true;
        }),
    }),
    defineField({
      name: "caption",
      title: "Caption",
      type: "string",
    }),
  ],
}),

// File field for downloads
defineField({
  name: "attachment",
  title: "Attachment",
  type: "file",
  options: {
    accept: ".pdf,.doc,.docx",
  },
  fields: [
    defineField({
      name: "description",
      title: "Description",
      type: "string",
    }),
  ],
}),
```

**Why good:** `hotspot: true` lets editors choose a focal point that `@sanity/image-url` respects during cropping, custom validation requires alt text only when an image is actually uploaded, file field restricts upload types with `accept`

---

## Pattern 5: Array Fields with Constraints

### Good Example — Array with Min/Max and Unique Items

```typescript
defineField({
  name: "tags",
  title: "Tags",
  type: "array",
  of: [defineArrayMember({ type: "string" })],
  validation: (rule) => rule.unique().min(1).max(10),
  options: {
    layout: "tags", // Renders as tag chips in Studio
  },
}),

// Array of objects with constrained block types
defineField({
  name: "content",
  title: "Content",
  type: "array",
  of: [
    defineArrayMember({ type: "block" }),
    defineArrayMember({
      type: "image",
      options: { hotspot: true },
    }),
    defineArrayMember({
      type: "object",
      name: "callout",
      title: "Callout",
      fields: [
        defineField({
          name: "tone",
          title: "Tone",
          type: "string",
          options: {
            list: [
              { title: "Info", value: "info" },
              { title: "Warning", value: "warning" },
              { title: "Tip", value: "tip" },
            ],
          },
        }),
        defineField({
          name: "text",
          title: "Text",
          type: "array",
          of: [defineArrayMember({ type: "block" })],
        }),
      ],
      preview: {
        select: { tone: "tone" },
        prepare({ tone }) {
          return { title: `Callout: ${tone || "default"}` };
        },
      },
    }),
  ],
}),
```

**Why good:** `.unique()` prevents duplicate tags, `layout: "tags"` improves Studio editing UX, custom inline objects (callout) have their own preview, content array mixes blocks, images, and custom types for flexible editorial experiences

---

## Pattern 6: Schema Registration

### Good Example — Registering Schemas in sanity.config.ts

```typescript
// sanity.config.ts
import { defineConfig } from "sanity";
import { structureTool } from "sanity/structure";
import { postType } from "./schemas/post";
import { authorType } from "./schemas/author";
import { categoryType } from "./schemas/category";
import { seoType } from "./schemas/objects/seo";

// NOTE: default export required by Sanity Studio
export default defineConfig({
  name: "default",
  title: "My Project",
  projectId: process.env.SANITY_PROJECT_ID!,
  dataset: process.env.SANITY_DATASET!,
  plugins: [structureTool()],
  schema: {
    types: [postType, authorType, categoryType, seoType],
  },
});
```

**Why good:** Each schema in its own file, imported and registered in config, `structureTool()` provides the default document editor, schema types array includes both document types and reusable object types

---

_For client and GROQ patterns, see [core.md](core.md). For Portable Text and images, see [rich-content.md](rich-content.md)._