@sanity/template-validator

Sanity Template Validator

A validation utility for Sanity.io template repositories. Use it as a dependency in your projects or as a GitHub Action to ensure your Sanity templates meet the required standards.

Features

• Validates Sanity.io template structure and requirements
• Supports monorepo detection and validation
• Can be used as a Node.js dependency, GitHub Action, or CLI tool
• Validates environment variables and configuration files
• TypeScript support with full type definitions
• Local directory validation support

Installation

npm install @sanity/template-validator
# or
yarn add @sanity/template-validator
# or
pnpm add @sanity/template-validator

Usage

As a CLI Tool

The package includes a CLI tool that can validate local directories:

# Install globally
npm install -g @sanity/template-validator

# Validate current directory
sanity-template-validate

# Validate specific directory
sanity-template-validate path/to/template

# Using Npx
npx @sanity/template-validator

Adding as a Dev Dependency

The recommended way to use the validator in your template project is to add it as a dev dependency and create a validation script:

• Add to your project:

npm install --save-dev @sanity/template-validator

• Add a script to your package.json:

{
  "scripts": {
    "validate": "sanity-template-validate"
  }
}

• Run the validation:

npm run validate

As a Node.js Dependency

import {validateLocalTemplate, validateRemoteTemplate} from '@sanity/template-validator'

// Validate a local directory
async function validateLocal() {
  const result = await validateLocalTemplate('/path/to/template')

  if (result.isValid) {
    console.log('Template is valid!')
  } else {
    console.error('Validation failed:', result.errors)
  }
}

// Validate a remote repository
async function validateRemote() {
  const baseUrl = 'https://raw.githubusercontent.com/owner/repo/branch'
  const result = await validateRemoteTemplate(baseUrl)

  if (result.isValid) {
    console.log('Template is valid!')
  } else {
    console.error('Validation failed:', result.errors)
  }
}

// Advanced usage with FileReader
import {LocalFileReader, getMonoRepo} from '@sanity/template-validator'

async function advancedValidation() {
  const fileReader = new LocalFileReader('/path/to/template')
  const packages = await getMonoRepo(fileReader)
  // Use packages for further processing
}

As a GitHub Action

name: Validate Template
on: push

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Validate Sanity Template
        uses: sanity-io/template-validator@v2

API Reference

validateLocalTemplate

Validates a local Sanity template directory.

async function validateLocalTemplate(directory: string): Promise<ValidationResult>

Parameters:

• directory: Path to the template directory

validateRemoteTemplate

Validates a remote Sanity template repository.

async function validateRemoteTemplate(
  baseUrl: string,
  headers?: Record<string, string>,
): Promise<ValidationResult>

Parameters:

• baseUrl: The base URL to the raw repository content
• headers: Custom headers for API requests (optional)

Returns:

type ValidationResult = {
  isValid: boolean
  errors: string[]
}

File Readers

The package provides two file reader classes for advanced usage:

class LocalFileReader implements FileReader {
  constructor(basePath: string)
  readFile(filePath: string): Promise<{exists: boolean; content: string}>
}

class GitHubFileReader implements FileReader {
  constructor(baseUrl: string, headers?: Record<string, string>)
  readFile(filePath: string): Promise<{exists: boolean; content: string}>
}

getMonoRepo

Helper function to detect monorepo configuration.

async function getMonoRepo(fileReader: FileReader): Promise<string[] | undefined>

Validation Rules

A valid Sanity template must meet the following criteria:

For Single-Package Repositories:

• Must have a valid package.json with 'sanity' dependency
• Must have sanity.config.js/ts/tsx and sanity.cli.js/ts
• Must have one of: .env.template, .env.example, .env.local.template, or .env.local.example

For Monorepos:

• Each package must have a valid package.json
• At least one package must include 'sanity' in dependencies
• At least one package must have Sanity configuration files
• Each package must have appropriate environment template files

Environment Files Must Include:

• SANITY_PROJECT_ID or SANITY_STUDIO_PROJECT_ID
• SANITY_DATASET or SANITY_STUDIO_DATASET

GitHub Action Inputs

Input	Description	Required
directory	The directory to validate. Use this if you have multiple templates in a repository.	No
token	GitHub token for accessing and validating private repositories.	No

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT © Sanity.io

Support

• Create an issue
• Sanity Community