How to pass initialValueTemplate to singletons in Structure Builder?

Unfortunately, initialValueTemplate() doesn't work with singleton documents in Structure Builder. This is a known limitation - when you use S.document().documentId() to create a singleton, the initial value template functionality is bypassed because you're pointing directly to a specific document ID rather than creating new documents from a template.

The core issue is that initial value templates are designed for creating new documents, but singletons by definition only exist once and are referenced by a fixed document ID. The template system never gets invoked because you're not going through the document creation flow.

Workarounds

Here are a few approaches to get initial values into your singleton:

1. Manually create the document first

Before adding the singleton to your structure, temporarily create it the normal way (through the "New document" menu) so the initial value template can apply. Then add it to your structure builder configuration.

2. Use default values in your schema

Instead of relying on initial value templates, define initialValue directly in your schema fields:

defineField({
  name: 'myField',
  type: 'string',
  initialValue: 'default value'
})

3. Create the document programmatically

Use the Sanity client to create the singleton document with your desired initial values:

import {client} from './sanityClient'

client.createIfNotExists({
  _id: 'settings',
  _type: 'settings',
  // your initial values here
  title: 'Site Settings',
  // ...
})

4. Use a migration

If you need to initialize or reset singleton values, you can write a Sanity migration to set the values programmatically.

The schema-level initialValue approach (option 2) is generally the most straightforward for singletons since it keeps your default values close to your schema definition and doesn't require manual document creation steps. As noted in the singleton document guide, you need to create the singleton document before adding it to your configuration, so combining option 1 (creating it first with a template) or option 3 (programmatic creation) with proper schema defaults gives you the best control over initial values.