Configuration API

The Configuration API in Sanity Studio v3 is the primary mechanism that allows you to customize the studio. Because the configuration is written as plain JavaScript (or TypeScript!) it allows for composability and logic to take place in your studio’s core setup.

The root configuration of your studio is created by supplying either a single workspace configuration object or an array of the same type to the defineConfig-function, and returning the result as the default export of the configuration file – typically found at the root of your project in a file named sanity.config.js|ts.

// The absolute minimum viable studio configuration
import { defineConfig } from 'sanity'

export default defineConfig({
  projectId: '<project-id>',
  dataset: 'production',
})

The following table shows all the top-level properties available for configuring and customizing a single workspace studio.

• RequiredprojectIdstring

  The ID of the Sanity project to use for the studio

• Requireddatasetstring

  The name of the dataset to use for the studio

• authobject | AuthConfig

  Lets you implement custom authentication by providing a configuration object. Read more about configuring auth providers.

• documentobject | DocumentPluginOptions

  Accepts custom components for document actions and badges, as well as a custom productionUrl resolver and default configuration for new documents. Read more about the document API.

• formobject | SanityFormConfig

  Extensions / customizations to the studio forms. Accepts configurations for image and file asset sources as well as custom components to override the default studio rendering. Read more about the form API.

• pluginsarray | PluginOptions[]

  Studio plugins - takes an array of plugin declarations that can be called with or without a configuration object. Read more about plugins.

• toolsarray | Tool[]

  Studio tools – takes an array of tool declarations that can be called with or without a configuration object. Read more about the tool API.

• schemaobject | SchemaPluginOptions

  Schema definition - takes an array of types and an optional array of templates (initial value templates). While defining a schema is not required, there are few things inside the studio that works without one. Read more about the schema API.

• studioobject | StudioComponentPluginOptions

  Accepts a components object which will let you override the default rendering of certain bits of the studio UI. Read more about studio components.

• themeobject | StudioTheme

  Accepts a theme configuration object. Read more about theming.

• i18nobject | LocalePluginOptions

  Accepts a config object for localizing the studio UI. Read more about studio localization.

• Requirednamestring

  Name of the workspace - by convention in lowercase/camelCase

• RequiredbasePathstring

  URL base path to use, for instance /myWorkspace

• Requiredtitlestring

  Title of the workspace

• subtitlestring

  Subtitle to show under the name of the workspace

• iconReact.ComponentType

  React component to use as icon for this workspace

// A more plausible minmalist configuration
import { defineConfig } from 'sanity'
import { structureTool } from 'sanity/structure'
import { schemaTypes } from './schemas'


export default defineConfig({
  title: 'My cool project',
  projectId: '<project-id>',
  dataset: 'production',
  plugins: [structureTool()],
  schema: {
    types: schemaTypes,
  },
})

import {defineConfig} from 'sanity'
import {structureTool} from 'sanity/structure'
import {visionTool} from '@sanity/vision'
import {LaunchIcon, RobotIcon} from '@sanity/icons'
import {schemaTypes} from './schemas'

export default defineConfig([
  {
    name: 'my-prod-space',
    title: 'My production workspace',
    basePath: '/production',
    icon: LaunchIcon,
    projectId: '<project-id>',
    dataset: 'production',
    plugins: [structureTool()],
    schema: {
      types: schemaTypes,
    },
  },
  {
    name: 'my-staging-space',
    title: 'My staging workspace',
    basePath: '/staging',
    subtitle: 'The world is a stage',
    icon: RobotIcon,
    projectId: '<project-id>',
    dataset: 'staging',
    plugins: [structureTool(), visionTool({defaultApiVersion: '2022-10-21'})],
    schema: {
      types: schemaTypes,
    },
  },
])