Skip to main content

​
defineConfig

Defines the configuration for Sanity Studio. This is the primary function used in your sanity.config.ts file to configure your studio instance.

​
Function Signature

function defineConfig<const T extends Config>(config: T): T
The defineConfig function accepts a configuration object and returns it with proper TypeScript typing. It’s a type-helper function that provides autocompletion and type-checking for your studio configuration.

​
Parameters

​
name
string
The name of the workspace. Required when using multiple workspaces. For single workspace configurations, this is optional.
​
title
string
The title of the studio displayed in the UI.
​
projectId
string
required
Your Sanity project ID. Find this in your project settings at sanity.io/manage.
​
dataset
string
required
The dataset name to use for this studio instance.
​
basePath
string
URL base path for the studio, for instance /studio. Note this is a client-side routing feature. For serving your studio from a subpath, use the basePath property in sanity.cli.ts.
​
schema
SchemaPluginOptions
Schema configuration for your content types.
​
schema.types
SchemaTypeDefinition[]
Array of schema type definitions created with defineType.
​
schema.templates
Template[]
Initial value templates for creating new documents.
​
plugins
Plugin[]
Array of plugins to enable in the studio. Plugins extend studio functionality and can provide tools, schema types, document actions, and more.
​
tools
Tool[]
Top-level tools available in the studio. Tools are React components rendered when active, with a URL route, title, name, and icon. Examples include the Structure tool and Vision tool.
​
document
DocumentPluginOptions
Document-level configuration.
​
document.actions
DocumentActionComponent[] | DocumentActionsResolver
Document actions available in the document editor (e.g., publish, delete).
​
document.badges
DocumentBadgeComponent[] | DocumentBadgesResolver
Badges displayed on documents to indicate status.
​
document.newDocumentOptions
NewDocumentOptionsResolver
Controls which document types appear in the “Create new” dialog.
​
document.productionUrl
AsyncComposableOption<string | undefined, ResolveProductionUrlContext>
Function to resolve the production URL for a document.
​
form
SanityFormConfig
Form-level configuration.
​
form.components
FormComponents
Custom form components to override default inputs, fields, and previews.
​
form.image
object
Image field configuration.
​
form.image.assetSources
AssetSource[]
Asset sources for selecting images.
​
form.image.directUploads
boolean
Whether to allow direct image uploads.
​
form.file
object
File field configuration (same structure as form.image).
​
icon
ComponentType
React component to use as the workspace icon.
​
theme
StudioTheme
Custom theme configuration for the studio.
​
apiHost
string
API hostname for requests. Used for custom CNAMEs. Must include protocol (e.g., https://sanityapi.mycompany.com).
​
auth
AuthConfig | AuthStore
Authentication configuration for the studio.

​
Return Value

​
config
Config
Returns the configuration object with proper TypeScript typing.

​
Example

​
Single Workspace

import {defineConfig} from 'sanity'
import {structureTool} from 'sanity/structure'
import {visionTool} from '@sanity/vision'

export default defineConfig({
  name: 'default',
  title: 'My Sanity Studio',
  projectId: 'your-project-id',
  dataset: 'production',
  
  plugins: [
    structureTool(),
    visionTool(),
  ],
  
  schema: {
    types: [
      // your schema types
    ],
  },
})

​
Multiple Workspaces

import {defineConfig} from 'sanity'
import {structureTool} from 'sanity/structure'

export default defineConfig([
  {
    name: 'production',
    title: 'Production',
    projectId: 'your-project-id',
    dataset: 'production',
    basePath: '/production',
    plugins: [structureTool()],
    schema: {
      types: [
        // your schema types
      ],
    },
  },
  {
    name: 'staging',
    title: 'Staging',
    projectId: 'your-project-id',
    dataset: 'staging',
    basePath: '/staging',
    plugins: [structureTool()],
    schema: {
      types: [
        // your schema types
      ],
    },
  },
])

​
With Custom Form Configuration

import {defineConfig} from 'sanity'
import {structureTool} from 'sanity/structure'
import {unsplashAssetSource} from 'sanity-plugin-asset-source-unsplash'

export default defineConfig({
  name: 'default',
  title: 'My Studio',
  projectId: 'your-project-id',
  dataset: 'production',
  
  plugins: [structureTool()],
  
  form: {
    image: {
      assetSources: [unsplashAssetSource],
      directUploads: true,
    },
  },
  
  document: {
    actions: (prev, context) => {
      // Customize document actions based on context
      if (context.schemaType === 'post') {
        return [...prev, myCustomAction]
      }
      return prev
    },
  },
  
  schema: {
    types: [
      // your schema types
    ],
  },
})

​
Source Location

packages/sanity/src/core/config/defineConfig.ts:6

Build docs developers (and LLMs) love

Get started for freeTalk to us