The Challenge

We decided to migrate our CMS from Contentful to Sanity, this to achieve substantial reductions in our monthly operational costs. While Contentful's pricing model had become misaligned with our content requirements, Sanity's structure allows us to maintain predictable, fixed operational expenses regardless of scale. Although the migration required a significant upfront investment in developer resources, this strategic move has positioned us for long-term cost efficiency and better aligns our infrastructure costs with our business needs.

When building dynamic page builders with Sanity CMS, developers face a fundamental type safety problem. Sanity's TypeGen generates types based on raw data storage format, including unresolved references and internal system metadata. However, your frontend components need clean, resolved data structures.

This creates a critical mismatch between generated types and actual runtime data, forcing developers to choose between type safety and maintainability.

Understanding the Problem

The Page Builder Context

Modern content management demands flexibility. In our system, Sanity CMS powers a modular page builder that gives content creators complete creative freedom:

• Component Library: Pre-built, reusable components (team lists, content sections, CTAs)

• Drag & Drop Interface: Content creators arrange components in any order

• Dynamic Configuration: Each component's content and settings are fully customizable

• Unlimited Combinations: Every page becomes unique and unpredictable

This flexibility creates two levels of technical complexity:

1. Multi-level Nesting: Components contain other components (e.g., TeamMemberList → TeamMemberItem → Link)

2. Runtime Uncertainty: Pages don't know which components will be present until runtime

TypeGen Limitations

Sanity's TypeGen has two critical limitations for page builders:

1. Incomplete Nested Types (Schema based generation)

When dealing with nested components, TypeGen generates internalGroqTypeReferenceTo markers instead of actual resolved types:

export type TeamMemberList = {
  _id: string;
  _type: 'teamMemberList'; 
  _createdAt: string; 
  _updatedAt: string; 
  _rev: string; 
  title: string; 
  teamList?: Array<{ 
     _ref: string; 
     _type: 'reference'; 
     _weak?: boolean; 
     _key: string; 
     [internalGroqTypeReferenceTo]?: 'teamMemberItem'; 
   }>; 
};

Your frontend receives resolved data, but TypeScript doesn't understand the relationship between references and actual content.

2. System Field Pollution (Schema based generation)

Generated types include Sanity's internal system fields (_createdAt, _rev, _weak, etc.) that your frontend components don't need and shouldn't handle.

GROQ Query Limitations (Query based generation)

When using conditional queries like _type == "accordion" => @->{ ... }, TypeGen cannot determine which specific component type will be returned at runtime. This creates union type ambiguity where TypeScript loses track of nested data structures.

The Solution: Advanced Type Transformation

Our solution leverages TypeScript's advanced type system to automatically transform raw Sanity types into clean, fully-typed objects that match your actual runtime data.

Key Benefits

• Type Safety: Compile-time guarantees for clean data structures

• Zero Runtime Overhead: Pure compile-time type transformation

• Developer Experience: Work with predictable, clean APIs

• Automatic Reference Resolution: No more dealing with _ref objects

• Preserved Relationships: Maintains semantic meaning while improving usability

Implementation Deep Dive

Step 1: Define System Keys to Remove

type SanitySystemKeys =
  | '_id'
  | '_createdAt'
  | '_updatedAt'
  | '_rev'
  | '_ref'
  | '_weak'
  | '_key';

This union type acts as a "blacklist" of internal Sanity properties that should be excluded from our clean frontend types.

Step 2: Reference Detection

type IsSanityReference<T> = T extends { _type: 'reference'; _ref: string }
  ? true
  : false;

This conditional type serves as a type-level predicate, identifying which properties represent Sanity references that need resolution.

Step 3: Reference Type Extraction

type ExtractReferenceType<T> = T extends {
  [internalGroqTypeReferenceTo]?: infer U;
}
  ? U extends keyof ReferenceTypeMap
    ? ReferenceTypeMap[U]
    : never
  : never;

This type performs three critical operations:

1. Extracts the reference key using infer U

2. Maps to actual types via ReferenceTypeMap lookup

3. Returns resolved type instead of reference placeholder

Step 4: Optional Property Preservation

type IsOptional<T, K extends keyof T> = unknown extends Pick<T, K> ? true : false;

This utility maintains the optional/required nature of properties during transformation—essential for preserving the original API contract.

Step 5: The Core Transformation Engine

export type SanityClean<T> = T extends (infer U)[]
  ? SanityClean<U>[]
  : IsSanityReference<T> extends true
    ? SanityClean<ExtractReferenceType<T>>
    : T extends object
      ? {
          [K in keyof T as K extends SanitySystemKeys
            ? never
            : K]: IsSanityReference<T[K]> extends true
            ? IsOptional<T, K> extends true
              ? SanityClean<ExtractReferenceType<T[K]>> | undefined
              : SanityClean<ExtractReferenceType<T[K]>>
            : SanityClean<T[K]>;
        }
      : T;

This recursive conditional type orchestrates the entire transformation:

Array Handling

T extends (infer U)[] ? SanityClean<U>[] :

Recursively cleans each array element while preserving array structure.

Reference Resolution

IsSanityReference<T> extends true ? SanityClean<ExtractReferenceType<T>> 

Detects Sanity references and replaces them with their resolved types.

Object Transformation

T extends object ? {
  [K in keyof T as K extends SanitySystemKeys ? never : K]: // Filter system keys
  IsSanityReference<T[K]> extends true ? // Check for references
    IsOptional<T, K> extends true ? // Preserve optionality
      SanityClean<ExtractReferenceType<T[K]>> | undefined :
      SanityClean<ExtractReferenceType<T[K]>> :
    SanityClean<T[K]>; // Recursively clean non-references
} :

For objects, this:

• Filters system keys using mapped type key remapping

• Resolves references to their actual types

• Preserves optionality from the original schema

• Recurses deeply through all nested properties

Primitive Pass-through

: T;

Returns primitive types unchanged.

Step 6: Reference Type Mapping

export type ReferenceTypeMap = {
  teamMemberItem: TeamMemberItem;
  teamMemberList: TeamMemberList;
  link: Link;
  // ... additional mappings
};

This centralized mapping bridges Sanity's internal references with your TypeScript types, ensuring:

• Type Safety: References resolve to correct types

• Maintainability: All mappings in one location

• Extensibility: Easy to add new content types

Real-World Transformation Example

Before: Raw Sanity Types

export type TeamMemberList = {
  _id: string;
  _type: 'teamMemberList';
  _createdAt: string;
  _updatedAt: string;
  _rev: string;
  title: string;
  teamList?: Array<{
    _ref: string;
    _type: 'reference';
    _weak?: boolean;
    _key: string;
    [internalGroqTypeReferenceTo]?: 'teamMemberItem';
  }>;
};

export type TeamMemberItem = {
  _id: string;
  _type: 'teamMemberItem';
  _createdAt: string;
  _updatedAt: string;
  _rev: string;
  name: string;
  primaryCta?: {
    _ref: string;
    _type: 'reference';
    _weak?: boolean;
    [internalGroqTypeReferenceTo]?: 'link';
  };
};

export type Link = {
  _id: string;
  _type: 'link';
  _createdAt: string;
  _updatedAt: string;
  _rev: string;
  displayName: string;
  url: string;
  icon?: 'arrow-right-up' | 'whatsapp';
  iconPosition?: 'left' | 'right';
};

After: Clean Transformation

export type CleanTeamMemberList = SanityClean<TeamMemberList>;

// Results in:
type CleanTeamMemberList = {
  _type: 'teamMemberList';
  title: string;
  teamList?: {
    _type: 'teamMemberItem';
    name: string;
    primaryCta?: {
      _type: 'link';
      displayName: string;
      url: string;
      icon?: 'arrow-right-up' | 'whatsapp';
      iconPosition?: 'left' | 'right';
    };
  }[];
};

Transformation Results

The clean type demonstrates several key improvements:

• System fields removed: No more _id, _createdAt, _updatedAt, _rev

• References resolved: Full type definitions instead of _ref objects

• Optionality preserved: Optional fields remain optional (icon?, iconPosition?)

• Nested structure maintained: Deep resolution through multiple levels

• Type safety guaranteed: Full IntelliSense and compile-time checking

Usage in Components

With clean types, your React components become more maintainable and type-safe:

interface TeamMemberListProps {
  data: CleanTeamMemberList;
}

export function TeamMemberListComponent({ data }: TeamMemberListProps) {
  return (
    <section>
      <h2>{data.title}</h2>
      {data.teamList?.map((member, index) => (
        <div key={index}>
          <h3>{member.name}</h3>
          {member.primaryCta && (
            <a href={member.primaryCta.url}>
              {member.primaryCta.displayName}
            </a>
          )}
        </div>
      ))}
    </section>
  );
}

Impact on Development Workflow

This type transformation system fundamentally improves the developer experience:

Performance Benefits

• Zero runtime cost: All transformations happen at compile-time

• Smaller bundle size: No runtime type checking or transformation libraries

• Better tree-shaking: Cleaner types improve dead code elimination

Developer Experience

• Predictable APIs: Components work with clean, expected data structures

• Better IntelliSense: Full autocomplete for nested properties

• Compile-time safety: Catch reference resolution errors during build

• Cleaner code: No manual casting or type guards needed

Maintainability

• Centralized mapping: All reference types managed in one location

• Automatic updates: Adding new content types requires minimal changes

• Clear separation: Clean boundary between CMS data layer and application logic

Conclusion

This TypeScript type transformation approach solves the fundamental mismatch between Sanity's generated types and frontend application needs. By leveraging advanced TypeScript features, we create a zero-cost abstraction that provides clean, type-safe data structures while maintaining the flexibility of a dynamic page builder system.

The solution demonstrates how sophisticated type-level programming can solve real-world problems, creating better developer experiences without sacrificing performance or maintainability. For teams building complex, dynamic content systems with Sanity CMS, this pattern provides a robust foundation for scalable, type-safe frontend development.

Resources

• Sanity Typegen: https://www.sanity.io/docs/apis-and-sdks/sanity-typegen

• Sanity PageBuilder: https://www.sanity.io/learn/course/page-building/create-page-builder-schema-types