sanity-singletons

Sanity Singletons

A "singleton" is a document with a fixed id that can be created exactly once. Common examples: site settings, navigation, footer content. Studio supports singletons as a first-class primitive via the document.singletons configuration registry plus a small set of Structure Tool helpers.

Requires sanity 6.17.0 or later. Check the installed version in the lockfile before using this API. On older Studios, either upgrade first or use the userland pattern (fixed documentId in a custom structure, plus manual newDocumentOptions and duplicate filtering) described in sanity-best-practices → studio-structure.

When to use this skill

• A developer asks how to create a "settings document" or "singleton".
• A studio configuration needs a document.singletons registry entry.
• Structure Tool needs to render a singleton as a list item or document pane.
• You're migrating an existing userland singleton implementation to the first-class API.
• You're migrating from a third-party singleton plugin such as sanity-plugin-singleton-management (or its predecessor sanity-plugin-singleton-tools).

Registering a singleton

Singletons are registered in configuration, not on the schema type. A singleton definition binds a definition id to a document id and a schema type:

import {defineConfig, defineSingleton} from 'sanity'

export default defineConfig({
  schema: {
    types: [/* siteSettings and campaign are ordinary document types */],
  },
  document: {
    singletons: [
      // String shorthand — expands to
      // {id: 'siteSettings', documentId: 'siteSettings', schemaType: 'siteSettings'}
      'siteSettings',

      // Definition object. `defineSingleton` is an optional typed identity
      // helper; a plain object literal works too. `id` is omitted here, so it
      // inherits each `documentId`.
      defineSingleton({
        documentId: 'springCampaign',
        schemaType: 'campaign',
        title: 'Spring campaign', // optional display metadata
        initialValue: {season: 'spring'}, // optional per-singleton initial value
      }),
      defineSingleton({
        documentId: 'summerCampaign',
        schemaType: 'campaign',
        title: 'Summer campaign',
        initialValue: {season: 'summer'},
      }),
    ],
  },
})