@sanity/template-validator NPM

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