Settings Singleton Schema

Relevant source files

The following files were used as context for generating this wiki page:

• sanity/schemas/singletons/settings.ts
• sanity/plugins/settings.tsx
• sanity.config.ts
• sanity/lib/queries.ts
• app/(personal)/layout.tsx
• sanity.types.ts

The Settings Singleton Schema defines the global configuration for the personal website, encompassing shared UI elements such as navigation menus, footer content, and SEO metadata. Unlike standard document types, the Settings schema is implemented as a "singleton," ensuring that only one instance of the settings exists within the Sanity Studio content lake.

This singleton is critical for maintaining consistency across the site. It provides the data for the global Navbar and footer components rendered in the root layout, as well as the default Open Graph (OG) image used for social media sharing. Sources: sanity/schemas/singletons/settings.ts:1-60, app/(personal)/layout.tsx:48-75

Data Model Structure

The settings type is a Sanity document consisting of three primary fields: menuItems, footer, and ogImage.

Field Definitions

Field	Type	Description
menuItems	array	A list of references to home, page, or project documents used for header navigation.
footer	array	Portable Text block used for site-wide footer information.
ogImage	image	The global Open Graph image for social cards and search results, supporting hotspot cropping.

Sources: sanity/schemas/singletons/settings.ts:11-54, sanity.types.ts:258-285

Schema Relationships

The menuItems field establishes relationships between the global settings and various page-level documents.

The diagram illustrates how the Settings singleton acts as a hub for site-wide navigation by referencing distinct document types. Sources: sanity/schemas/singletons/settings.ts:18-32, sanity.types.ts:265-270

Singleton Implementation Logic

The project uses a custom plugin to transform a standard Sanity document into a singleton experience within the Studio.

Plugin Architecture

The singletonPlugin and pageStructure functions in sanity/plugins/settings.tsx modify the Studio's behavior:

1. Creation Restriction: Filters newDocumentOptions to prevent users from creating multiple instances of the Settings document.
2. Action Restriction: Disables the "duplicate" action for singleton types.
3. UI Integration: The pageStructure function maps the singleton type to a specific editor instance with a hardcoded documentId matching the schema name.

Sources: sanity/plugins/settings.tsx:7-55

Configuration Flow

The following flow shows how the singleton is registered in the main Sanity configuration.

Data Retrieval and Consumption

The application fetches settings data using GROQ queries and injects it into the global layout.

GROQ Query

The settingsQuery retrieves the footer content, menu items (dereferencing the slugs and titles of linked documents), and the OG image.

export const settingsQuery = defineQuery(`
  *[_type == "settings"][0]{
    _id,
    _type,
    footer,
    menuItems[]{
      _key,
      ...@->{
        _type,
        "slug": slug.current,
        title
      }
    },
    ogImage,
  }
`)

Sources: sanity/lib/queries.ts:45-59

Frontend Integration

In the Next.js App Router, the settingsQuery is executed within app/(personal)/layout.tsx. The resulting data is passed to the Navbar component and rendered as Portable Text in the footer element.

Technical Types

The generated TypeScript definitions provide strict typing for the settings object and query results.

export type Settings = {
  _id: string
  _type: 'settings'
  menuItems?: ArrayOf<HomeReference | PageReference | ProjectReference>
  footer?: Array<PortableTextBlock>
  ogImage?: {
    asset?: SanityImageAssetReference
    hotspot?: SanityImageHotspot
    crop?: SanityImageCrop
    _type: 'image'
  }
}

Sources: sanity.types.ts:258-285

Conclusion

The Settings Singleton Schema serves as the central configuration point for the website. By leveraging custom Sanity plugins, the project ensures a simplified authoring experience where global site attributes—navigation, footers, and SEO assets—are managed in a single, non-replicable document. This architecture effectively separates global site configuration from individual page content.