Index of every page on this site: llms.txt
All skills
sanity-io avatar

/sanity-singletons

@828641f official
by Sanitysanity-io/agent-toolkit201 stars
32
Run it yourself

Configure singleton documents in a Sanity Studio using the document.singletons registry. Use when a developer wants a fixed-id document (settings, navigation, footer) edited in place, hidden from the default content list, with no "create new" or "duplicate" affordances — or when migrating a userland singleton implementation or a third-party singleton plugin (e.g. sanity-plugin-singleton-management) to the first-class API.

Use this Skill: https://skilld.dev/gh/sanity-io/agent-toolkit/sanity-singletons

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈112 tokens for metadata: the name and description. ≈5.3k when used: this file.

Description uses 5.6% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈445 characters, or 5.6%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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'},
      }),
    ],
  },
})

Key facts:

  • defineSingleton produces a singleton definition, not a document schema. The schema type it references is defined separately with defineType and needs no singleton-specific configuration.
  • Multiple singletons may share a schema type (like the two campaigns above), each with its own title, icon, and initialValue (falling back to the schema type's), and a shared schema type may also back ordinary documents.
  • The definition id is the singleton's stable identity, and it is optional — it inherits documentId when omitted. Structure code references it (S.listItem().singleton('springCampaign')). Set it explicitly only to be verbose, to guard against future collisions, or to address a singleton universally when different workspaces or environments map it to different document ids.
  • A resolver function is also accepted: singletons: (prev, context) => [...prev, ...]. Resolvers only ever receive fully resolved definitions (string shorthands are expanded first).

Validation at config-resolution time (all failures aggregate into one ConfigResolutionError):

  • id: non-empty, unique across definitions (inherited ids count — an explicit id may not collide with another definition's inherited one). Used verbatim as a Structure Tool node id, so it is limited to [a-zA-Z0-9._-] and may not start with __edit__. It also may not match the name of a document type that no singleton claims, since the default content list keys both by id (the string shorthand never trips this — the type it names is claimed by the definition itself). A type claimed by a singleton with allowNonSingletonDocuments: true keeps its own list item, so it counts as unclaimed for this check.
  • documentId: non-empty, unique, published-id shaped (no drafts. / versions. prefix, only [a-zA-Z0-9._-]).
  • schemaType: must name an existing document type. Need not be unique.
  • Templates: an untagged template must not reuse a definition id (the generated singleton template claims it); at most one template may carry a given singleton tag; tags must reference registered definitions.

What Studio does automatically

  1. Generates a dedicated initial value template per singleton — tagged with the definition id via ResolvedTemplate.singleton, value from definition.initialValue ?? schemaType.initialValue — instead of the plain per-type template (unless the type opts in with allowNonSingletonDocuments), and removes tagged templates from every "create new" surface (global create menu, structure panes, reference inputs). The tagged template stays in source.templates, so opening the singleton before it exists still applies its initial value.
  2. Injects context.singleton (the definition id) into document-scoped configuration contexts — document.actions, badges, inspectors, field actions, comments.enabled, askToEdit.enabled — looked up by published document id, so drafts and release versions of the singleton match, however the document was opened (structure, intent, deep link, search).
  3. Filters the duplicate document action, after all user resolvers run, so it cannot be reintroduced via document.actions.
  4. Hides the schema type from the implicit default content list in Structure Tool (unless it opts in with allowNonSingletonDocuments), and appends the singleton itself to that list — one item per definition, after the document type lists, in registration order, each equivalent to S.listItem().singleton(id). A studio that has not configured Structure Tool needs no structure code at all. This applies only to the default structure; a structure resolver replaces it wholesale.

What Studio deliberately does not do:

  • Delete, unpublish, and discard stay available. Deleting a singleton is a legitimate "reset": structure still points at the fixed id, and editing recreates the document. To hide delete as well: document: {actions: (prev, context) => (context.singleton ? prev.filter((action) => action.action !== 'delete') : prev)}.
  • Explicit structure is never filtered. S.documentTypeList(typeName) works for singleton schema types and intentionally lists the singleton documents alongside ordinary ones.
  • No warning for "dangling" singletons. Structure resolves lazily, so Studio cannot detect a registered singleton that a custom structure never adds. (The default structure adds them all, so this only affects studios with a structure resolver.) Any heuristic short of eager resolution would misfire, because manual S.document().documentId(...).schemaType(...) wiring is supported. In a custom structure, always pair a registry entry with a structure entry.

Surfacing singletons in Structure Tool

With the default structure there is nothing to do — registered singletons are appended to the top-level content list automatically.

In a custom structure (any studio passing a structure resolver to structureTool()), add them explicitly. All helpers are keyed by definition id and throw a SerializeError for unknown ids.

Watch for this trap: S.documentTypeListItems(), the usual way to reproduce the default lists inside a custom structure, excludes singleton schema types (except those opted in with allowNonSingletonDocuments) and does not add singleton items. S.list().items([...S.documentTypeListItems()]) therefore drops every singleton. Use .singletons() alongside it:

S.list().id('__root__').title('Content').items(S.documentTypeListItems()).singletons()
// 1. Highest level: a list of singletons — a given set, or all of them.
S.list().id('singletons').title('Singletons').singletons(['siteSettings', 'springCampaign'])
S.list().id('singletons').title('Singletons').singletons()

// 2. A single list item (title/icon default from the definition, then the schema type).
S.listItem().singleton('siteSettings')

// 3. Low level: just the document pane.
S.listItem().title('Settings').id('settings').child(S.document().singleton('siteSettings'))

Composition rules:

  • Every default is overridable by normal chaining: S.listItem().singleton('siteSettings').title('Global settings'), S.document().singleton('siteSettings').documentId('override').
  • Titles are not disambiguated for you. The list item id defaults to the definition id (unique by construction), but the title falls back to the schema type's, so singletons sharing a schema type share a label. Give each definition a title — it applies everywhere the singleton is rendered, including S.list().singletons(), which has no per-item overrides.
  • S.document().singleton() pins the singleton's tagged initial value template so its initial value applies even when the type has several templates; override with .initialValueTemplate(...).
  • S.list().singletons() returns a builder without .items(). Calling .items() afterwards would replace the whole array and silently drop the singleton items, so the type forbids it. Call .items([...]) before .singletons([...]), or put S.listItem().singleton() entries inside a regular .items() array. Repeated .singletons() calls append.
  • singletons() with no argument means every registered definition (registration order, including plugin-registered ones); singletons([]) means none. Combining it with a hand-written S.listItem().singleton(id) in the same list adds that singleton twice and fails with a duplicate-id SerializeError — pass an explicit array when mixing.
  • S.documentListItem().singleton(id) renders a live document preview instead of a static title, and defaults its id to the definition's documentId (not the definition id), because a document list item's id is the document it previews. Prefer plain S.listItem() when the singleton document may not exist yet.

Shared schema types: allowNonSingletonDocuments

The rule: registering a singleton over schema type T replaces T's plain "create new" template with the singleton's tagged template, and hides T's list from the default structure. Ordinary T documents are therefore no longer creatable or listed unless you opt back in. A type used only by its singletons needs nothing more; a type that also backs ordinary documents does.

Recommended (sanity 6.24.0 or later): set the option on the singleton definition. It was added in sanity 6.24.0 and is not in 6.23.0 or earlier — check the installed version in the lockfile before using it.

document: {
  singletons: [
    'settings',
    {documentId: 'spring', schemaType: 'campaign', allowNonSingletonDocuments: true},
    {documentId: 'summer', schemaType: 'campaign', allowNonSingletonDocuments: true},
  ],
}
// defineSingleton({documentId: 'spring', schemaType: 'campaign', allowNonSingletonDocuments: true}) works the same.

With the option on (default false), campaign:

  • keeps its default "create new" template, so it stays in create menus;
  • keeps its default list item in S.documentTypeListItems() and the default structure — the list shows every campaign document, singletons included.

So neither a hand-written untagged template nor an explicit S.documentTypeListItem('campaign') is needed. The singleton documents themselves still cannot be created as new documents or duplicated. When several singletons share a schema type, setting the option on any one of them is enough (setting it on all of them, as above, is harmless and self-documenting).

Id collision: with the option on, the type keeps its own list item in the default content list, keyed by the type name. A singleton whose id (which defaults to documentId) equals the schema type name is therefore rejected with "Singleton definition ids collide with document type names". Give such a singleton a different id or documentId.

Fallback for sanity 6.23.0 and earlier: opt back in by hand. Define an explicit untagged template — any id works, including T itself, since the plain template no longer exists:

schema: {
  templates: (prev) => [
    ...prev,
    {id: 'campaign-non-singleton', title: 'Campaign', schemaType: 'campaign', value: {}},
  ],
},

and add an explicit S.documentTypeListItem(typeName) to a custom structure. The default structure is not enough on its own here: it surfaces the singletons over the shared type, but the type stays filtered, so ordinary documents of it remain unlisted while the structure looks complete. When upgrading to 6.24.0 or later, replace both with allowNonSingletonDocuments: true.

The singleton tag carries the semantics: templates with it are never create options; templates without it always are. The tag lives on ResolvedTemplate — the resolved shape in source.templates — not on the authoring Template type, so developers never set it directly. To customise a singleton's initial value via schema.templates, find the singleton's template by id (equal to the definition id) and spread it ({...template, value}) — the spread preserves the tag at runtime, keeping it out of create menus. (Setting initialValue on the definition itself is usually simpler.)

Reading singletons from plugins

  • The resolved registry is available at source.document.singletons (useSource().document.singletons).
  • Document-scoped resolvers receive context.singleton (the definition id; documentId and schemaType are already on the context).

Migrating a userland singleton setup

Typical userland implementations combine three pieces; each is subsumed by the registry:

Userland technique First-class replacement
document.newDocumentOptions filtering out the type Automatic (tagged singleton templates are never create options)
document.actions filtering duplicate Automatic (terminal, non-bypassable)
Custom structure with S.document().schemaType(x).documentId(y) Keep, or simplify to S.listItem().singleton(id)

Migration steps:

  1. Add the singleton to document.singletons (string shorthand when id, document id, and type name are all identical).
  2. Delete the manual newDocumentOptions and duplicate filtering for that type.
  3. Replace the manual structure wiring with S.listItem().singleton(id) (or keep the manual wiring — it remains fully supported; ensure the documentId/schemaType pair matches the definition so context.singleton resolves). If the only reason a custom structure existed was to surface the singletons, delete the resolver entirely and let the default structure do it.
  4. If the schema type is only used by the singleton, nothing else changes. If it's shared with ordinary documents, set allowNonSingletonDocuments: true on the singleton definition to keep them creatable and listed (sanity 6.24.0 or later — see Shared schema types). On 6.23.0 and earlier, add an explicit untagged template and S.documentTypeListItem(typeName) instead.

Migrating from sanity-plugin-singleton-management

sanity-plugin-singleton-management (a maintained fork of sanity-plugin-singleton-tools, with an identical API) marks schema types with options: {singleton: true}, registers a singletonTools() plugin that filters new-document options and document actions, and ships three structure helpers. Every piece maps directly onto the first-class API:

Plugin technique First-class replacement
options: {singleton: true} on the schema type A document.singletons entry (delete the schema option — it has no first-class meaning)
singletonTools() plugin in plugins: [...] Delete (creation and duplicate prevention are automatic)
singletonDocumentListItem({S, context, type, title, id, icon}) S.listItem().singleton(<definition id>) (title/icon defaults come from the definition, then the schema type)
singletonDocumentListItems({S, context}) S.list().singletons() (or nothing at all, if using the default structure)
filteredDocumentListItems({S, context}) ...S.documentTypeListItems() — singleton schema types are excluded automatically (unless opted in via allowNonSingletonDocuments)

Document id compatibility (the critical detail): the plugin's document id defaults to the schema type name (S.document().schemaType(type).id(id ?? type)), so a plugin singleton mySingleton edits the document mySingleton. The string shorthand (singletons: ['mySingleton']) produces exactly that document id — existing content keeps working with no data migration. If the plugin call passed an explicit id, carry it over as the definition's documentId.

Migration steps:

  1. For each schema type with options: {singleton: true}: remove the option, and register the type in document.singletons — the string shorthand when the plugin used the default id, otherwise {documentId: <the explicit id>, schemaType: <type>}.

  2. Remove singletonTools() from plugins and uninstall the package.

  3. Replace the structure helpers per the table above. The plugin passed {S, context} around; the first-class helpers need neither — they read the registry from the builder's own context.

  4. Note a deliberate behavioural difference: the plugin allowlists actions (publish, discardChanges, restore), hiding delete and unpublish. The first-class API only removes duplicate — deleting a singleton is a legitimate "reset". To preserve the plugin's stricter behaviour, add:

    document: {
      actions: (prev, context) =>
        context.singleton
          ? prev.filter(({action}) =>
              ['publish', 'discardChanges', 'restore'].includes(action as string),
            )
          : prev,
    },

    Only add this if the stricter behaviour is genuinely wanted — otherwise prefer the first-class default.

  5. If the plugin's singletonDocumentListItem was used to render multiple singletons of the same schema type (its title/id overrides), register one definition per document id — {documentId, schemaType, title} — which is the first-class model for exactly that case.

Reference

Source lives in the sanity-io/sanity monorepo:

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alertstoday3 checks · Risk SAFE
  • Gen Agent Trust Hubtoday

    This skill is a documentation-only resource for configuring Sanity Studio singletons. It contains no executable scripts, remote code patterns, or security vulnerabilities.

  • Socket1mo

    No alerts

  • Snyktoday

    Risk: LOW · No issues

Signed by skilld at 828641f. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 2 days ago

README badge

README badge for sanity-io/agent-toolkit/sanity-singletons