API Reference

import seofields from 'sanity-plugin-seofields'
import type { SeoFieldsPluginConfig } from 'sanity-plugin-seofields'

// Usage
seofields(config?: SeoFieldsPluginConfig)

import { buildSeoMeta } from 'sanity-plugin-seofields/next'

const metadata = buildSeoMeta({
  seo: data.seo,              // Sanity SEO object (or null/undefined)
  baseUrl: 'https://example.com',
  path: '/about',
  defaults: {
    title: 'My Site',
    siteName: 'My Site',
    twitterSite: '@mysite',
    ogImage: 'https://example.com/og-default.png',
  },
  imageUrlResolver: (img) => urlFor(img).width(1200).url(),
})

// Returns: { title, description, keywords, robots, openGraph, twitter, alternates, other }

import { SeoMetaTags } from 'sanity-plugin-seofields/next'
import type { SeoMetaTagsProps } from 'sanity-plugin-seofields/next'

interface SeoMetaTagsProps {
  data?: Partial<SeoFields> | null       // Raw Sanity SEO object
  baseUrl?: string                       // e.g. "https://example.com"
  path?: string                          // e.g. "/about"
  defaults?: SeoMetaDefaults             // Fallback values
  imageUrlResolver?: (img) => string     // Resolve Sanity image refs
}

interface SeoFieldsPluginConfig {
  // Sanity Content Lake API version used by the SEO preview's GROQ
  // fetches and the SEO Health Dashboard. Default: '2024-01-01'.
  // Replaces healthDashboard.apiVersion (deprecated in v1.6.1).
  apiVersion?: string

  // Enable/disable SEO preview (default: false)
  seoPreview?: boolean | {
    prefix?: (document: SanityDocument) => string

    // Static or function-based suffix appended after the SERP title.
    // The same resolved suffix is included in Meta Title validation length checks.
    titleSuffix?: string | ((document: SanityDocument) => string)

    // GROQ query whose result becomes the suffix.
    // Takes priority over titleSuffix when both are set, and is also used by
    // Meta Title validation feedback.
    titleSuffixQuery?: string

    // Match the parent title color (#1a0dab, weight 500) instead of
    // the default muted gray (#70757a, weight 400). Default: false.
    titleSuffixInheritColor?: boolean
  }

  // Base URL for preview generation
  baseUrl?: string

  // Customize field titles and descriptions
  fieldOverrides?: {
    [fieldKey: string]: {
      title?: string
      description?: string
    }
  }

  // Hide fields on specific document types
  fieldVisibility?: {
    [documentType: string]: {
      hiddenFields: string[]
    }
  }

  // Hide fields globally
  defaultHiddenFields?: string[]

  // Group seoFields into tabbed sections in the Studio
  fieldGroups?: Array<{
    name: string
    title: string
    default?: boolean
    fields: string[]
  }>

  // Enable or configure the SEO Health Dashboard tool.
  // Set false to disable. Defaults to true (enabled with defaults).
  healthDashboard?: boolean | {
    tool?: { title?: string; name?: string }
    toolTitle?: string
    content?: {
      icon?: string
      title?: string
      description?: string
      loadingLicense?: string
      loadingDocuments?: string
      noDocuments?: string
    }
    showTypeColumn?: boolean
    showDocumentId?: boolean
    query?: {
      types?: string[]
      requireSeo?: boolean
      groq?: string
    }
    /** @deprecated Use root-level apiVersion instead (v1.6.1) */
    apiVersion?: string
    licenseKey?: string
    typeDisplayLabels?: Record<string, string>
    typeColumnMode?: 'badge' | 'text'
    titleField?: string | Record<string, string>
    previewMode?: boolean
    export?: boolean | { enabled?: boolean; formats?: Array<'csv' | 'json'> }
    compactStats?: boolean
    structureTool?: string
  }
}

// Main entry
import type {
  SeoFields,          // Full SEO object shape
  OpenGraphSettings,  // openGraph sub-object
  TwitterCardSettings,// twitter sub-object
  RobotsSettings,     // robots sub-object
  MetaAttribute,      // individual metaAttribute item
  SanityImage,
  SanityImageWithAlt,
} from 'sanity-plugin-seofields'

// /next entry
import type {

  BuildSeoMetaOptions,  // Options for buildSeoMeta()
  SeoMetaDefaults,      // defaults sub-object
  SeoMetadata,          // Return type of buildSeoMeta()
  SeoMetaTagsProps,     // Props for <SeoMetaTags>
  SeoFieldsInput,       // Permissive input type (accepts Sanity codegen output)
} from 'sanity-plugin-seofields/next'