Beyond the Basics: A Developer’s Guide to Architecting Sanity v5

When you transition from a traditional CMS to a composable, decoupled architecture, the initial freedom can feel overwhelming. Sanity gives you a blank canvas, but without a strict engineering philosophy, that canvas can quickly turn into a chaotic, unmaintainable mess of schemas and circular references. With the release of Sanity v5 (specifically targeting the performance and API enhancements in ^5.20.0), the platform has solidified its position as a developer-first content operating system.

But out-of-the-box setups rarely cut it for enterprise applications. A common question we get from engineering teams scaling their digital platforms is exactly how we configure sanity to handle complex relational data, strict type safety, and real-time visual editing without degrading the developer experience (DX).

In this deep dive, we are opening up our internal playbooks. We will walk through our production-grade configuration strategy, focusing on multi-workspace setups, strict schema typing, and custom structure builders that keep the editorial experience flawless.

The Core sanity.config.ts Architecture

In Sanity v5, the sanity.config.ts file is the absolute command center of your Studio. While a basic setup exports a single defineConfig object, our enterprise projects almost always require a multi-workspace configuration. This allows us to serve different datasets (e.g., production, staging, sandbox) or completely different editorial interfaces from a single deployed Studio instance.

Here is a simplified version of our standard multi-workspace setup:

// sanity.config.ts
import { defineConfig } from 'sanity'
import { structureTool } from 'sanity/structure'
import { visionTool } from '@sanity/vision'
import { presentationTool } from 'sanity/presentation'
import { schemaTypes } from './schemas'
import { customStructure } from './deskStructure'

const sharedConfig = {
  schema: {
    types: schemaTypes,
  },
  plugins: [
    structureTool({ structure: customStructure }),
    visionTool(),
    presentationTool({
      previewUrl: process.env.SANITY_STUDIO_PREVIEW_URL || 'http://localhost:3000',
    }),
  ],
}

export default defineConfig([
  {
    name: 'production-workspace',
    title: 'Production Content',
    projectId: process.env.SANITY_STUDIO_PROJECT_ID!,
    dataset: 'production',
    basePath: '/production',
    ...sharedConfig,
  },
  {
    name: 'staging-workspace',
    title: 'Staging Environment',
    projectId: process.env.SANITY_STUDIO_PROJECT_ID!,
    dataset: 'staging',
    basePath: '/staging',
    ...sharedConfig,
  },
])