@confed/sanity-types

A TypeScript types package for the Confederation College Sanity CMS backend. This package provides auto-generated TypeScript definitions for all Sanity schema types, ensuring type safety across your frontend applications and API integrations.

Quick Start

Installation

npm install @confed/sanity-types

Basic Usage

import type {Program, Event, Person} from '@confed/sanity-types'

// Use types in your components or API functions
const program: Program = {
  _id: 'program-123',
  _type: 'program',
  _createdAt: '2024-01-01T00:00:00Z',
  _updatedAt: '2024-01-01T00:00:00Z',
  _rev: 'rev-123',
  name: 'Computer Programming',
  slug: {_type: 'slug', current: 'computer-programming'},
  // ... other required fields
}

// Type-safe event handling
const handleEvent = (event: Event) => {
  console.log(event.title) // Full IntelliSense support
  console.log(event.startDate) // Type-safe date access
}

Advanced Usage

// Import multiple types
import type {
  Program,
  School,
  Campus,
  Person,
  SanityImageAsset,
  PtBasic
} from '@confed/sanity-types'

// Use with React components
interface ProgramCardProps {
  program: Program
  school?: School
}

const ProgramCard: React.FC<ProgramCardProps> = ({ program, school }) => {
  return (
    <div>
      <h2>{program.name}</h2>
      {school && <p>School: {school.name}</p>}
      {program.description && (
        <div>{/* Portable text content */}</div>
      )}
    </div>
  )
}

// Use with API functions
async function fetchProgram(id: string): Promise<Program | null> {
  const response = await fetch(`/api/programs/${id}`)
  if (!response.ok) return null
  return response.json() as Promise<Program>
}

Available Types

Content Types

• Program - Academic programs with details, requirements, and metadata
• School - Academic schools/departments within the college
• Campus - Physical campus locations
• Area - Areas of study or interest
• Person - Faculty, staff, and other individuals
• Event - College events, workshops, and activities
• NewsArticle - News and announcements
• Webpage - General web pages and content
• Testimonial - Student and stakeholder testimonials
• Credential - Academic credentials and certifications
• ProgramIntake - Program intake periods and delivery methods
• AdmissionRequirements - Program admission criteria
• Duration - Program duration and time requirements
• ProgramFile - Program-related documents and files

Navigation & Structure

• Menu - Navigation menus (header, footer, sidebar, mobile)
• MenuItem - Individual menu items with links and sub-items
• Link - Internal and external links with metadata
• Redirect - URL redirects for content migration

Content Blocks & Media

• PtBasic - Portable text content with rich formatting
• Figure - Images with accessibility features
• AccessibleImage - Accessible image components
• Button - Call-to-action buttons
• YoutubeVideo - Embedded YouTube videos

SEO & Metadata

• Seo - Search engine optimization metadata
• Slug - URL-friendly identifiers

Sanity System Types

• SanityImageAsset - Image assets with metadata
• SanityFileAsset - File assets
• SanityImageHotspot - Image hotspot coordinates
• SanityImageCrop - Image cropping data
• SanityImageMetadata - Image metadata including dimensions and palette
• Geopoint - Geographic coordinates
• MediaTag - Media tagging system

How It Works

This package uses Sanity TypeGen to automatically generate TypeScript definitions from your Sanity schema. The types are generated from:

1. Schema definitions (schema.json) - Contains all your content type schemas
2. GROQ queries - Any TypeScript/JavaScript files in the src/ directory that contain GROQ queries

Complete Workflow:

1. Schema Changes → You modify Sanity schemas
2. Local Generation → Pre-commit hook generates types automatically
3. Commit → Types and schema changes committed together
4. CI/CD Trigger → GitHub Actions workflow runs on push
5. Verification → Types regenerated in CI for verification
6. Publishing → If types changed, version bumped and published to npm
7. Sanity Deployment → Separate workflow deploys Sanity Studio (handled by .github/workflows/deploy-sanity.yml)
8. No Circular Commits → CI never commits back to your repository

The generated types provide:

• Full type safety for all your content types
• IntelliSense and autocomplete in your IDE
• Compile-time error checking for content structure
• Reference type safety for cross-referenced documents

Keeping Types Up to Date

The types in this package are automatically generated and should never be manually edited. This project is configured with automatic type generation on every commit, so types stay current automatically.

Current Status: Types are regenerated on every commit via Husky pre-commit hooks, and automatically published to npm via CI/CD when changes are detected.

Workflow:

1. Local Development: Types generated automatically before each commit
2. CI/CD: Types verified and published to npm if changes detected
3. No Circular Commits: CI never commits back to your repository

To keep them current:

1. Generate Types After Schema Changes

Whenever you modify your Sanity schemas, regenerate the types:

# From the root directory
npm run gen:types

This command runs:

• npm run schema:extract - Extracts the latest schema
• npm run typegen - Generates TypeScript definitions

2. Automatic Generation (Recommended)

Set up automatic type generation in your development workflow:

# Watch for schema changes and regenerate types
npm run typegen -- --watch

3. Pre-commit Hook (Currently Active!)

This project has Husky pre-commit hooks already configured and working. The types are automatically regenerated on every commit:

# The hook is already set up at .husky/pre-commit
# It runs: npm run gen:types

# To verify it's working, make a schema change and commit:
git add .
git commit -m "your message"
# Types will be automatically regenerated before commit

Note: The pre-commit hook is already active in this project, so you don't need to set it up manually.

4. CI/CD Integration (Automated Publishing)

This project has automated CI/CD workflows that handle different concerns:

Types Publishing (.github/workflows/publish-types.yml):

# Automatically runs on schema changes:
# - Generates types in CI for verification
# - Bumps version and publishes to npm if types changed
# - Does NOT commit back to repository (no circular commits)

Sanity Studio Deployment (.github/workflows/deploy-sanity.yml):

# Automatically deploys Sanity Studio on schema/config changes:
# - Builds the Sanity Studio
# - Deploys to Sanity hosting
# - Separate from types publishing workflow

Note: The CI workflows are separated by concern. Type generation and commits are handled locally via pre-commit hooks.

Configuration

The type generation is configured in sanity-typegen.json at the project root:

{
  "schema": "./schema.json",
  "path": ["./src/**/*.{ts,tsx,js,jsx}"],
  "generates": "./packages/sanity-types/sanity.types.ts",
  "overloadClientMethods": true
}

Troubleshooting

Types Not Updating

• Ensure you're running npm run gen:types from the project root
• Check that your schema changes are saved
• Verify the sanity-typegen.json configuration

Type Errors

• Regenerate types after schema changes
• Check that your content structure matches the schema
• Ensure all required fields are provided

Build Issues

• Clear your TypeScript cache
• Restart your development server
• Verify the package is properly linked in your workspace

Contributing

1. Never edit sanity.types.ts directly - it's auto-generated
2. Make schema changes in the appropriate schema files
3. Run npm run gen:types to update types
4. Commit both schema changes and generated types

Dependencies

• sanity - Sanity CMS framework
• @sanity/typegen - Type generation tool
• typescript - TypeScript compiler

License

This package is part of the Confederation College backend project and follows the same licensing terms.