The Studio configuration in v3 has moved from being defined in a sanity.json file to come from a default export in a sanity.config.js file. The most common “parts,” for schema, structure, document actions, and so on, now have dedicated entry points in the new configuration object.

This is an example of a configuration in v2:

// sanity.json
{
  "root": true,
  "project": {
    "name": "My Cool Project"
  },
  "api": {
    "projectId": "my-project-id",
    "dataset": "production"
  },
  "plugins": [
    "@sanity/base",
    "@sanity/default-layout",
    "@sanity/default-login",
    "@sanity/desk-tool"
  ],
  "parts": [
    {
      "name": "part:@sanity/base/schema",
      "path": "./schemas/schema"
    }
  ]
}

And here's that same configuration in v3:

// sanity.config.js
import {defineConfig} from 'sanity'
import {structureTool} from 'sanity/structure'
import {schemaTypes} from './schema/schema'

export default defineConfig({
  name: 'default',
  title: 'My Cool Project',
  projectId: 'my-project-id',
  dataset: 'production',
  plugins: [
    structureTool(),
  ],
  schema: {
    types: schemaTypes,
  },
})

Let’s look at what’s going on here:

• The main configuration of the Studio now lives in your project root in a file named sanity.config.js (.ts)
• A lot of the plugins (and dependencies) from v2 are removed. You can import structureTool from the sanity/structure package
• This file must export by default a valid studio configuration object. Creating a valid studio configuration is done by calling the defineConfig function. It accepts as an argument either a config object with appropriate values for connecting your project and initializing the studio or an array of these if you are setting up multiple workspaces.
• Technically only the name, projectId, and dataset properties are required, but that returns a Studio without any functionality.
• You add functionality by adding plugins to the plugins array. The most common and out-of-the-box plugin is the Structure tool — which gives you lists of documents with forms that you can edit content in.
• The Structure tool will look for schemas under the schemas property to list and render different editing for content types.
• The schema.types property accepts an array of schema objects. The call to createSchema from v2 (found by default in schemas/schema.js) is no longer necessary. The syntax for writing schemas remains largely unchanged. The exception is custom components for inputs, diff-views, and previews.

In v2, you could use the __experimental_spaces property to enable switching between datasets in a studio. In v3, this is replaced with Workspaces. Workspaces is essentially when you pass an array of configuration objects to the defineConfig function. This is a much more powerful and flexible system that also allows users of the Studio to switch quickly between projects and other configurations. See also: Migrating to Workspaces.

The new Studio APIs are fully typed with TypeScript. If your code editor supports it, you can get both autocomplete and instant feedback if you use options that aren't supported. The WorkspaceOptions interface extends PluginOptions and SourceOptions. The complete configuration object looks like this:

interface WorkspaceOptions {
  name: string
  title: string
  projectId: string
  dataset: string
  plugins?: PluginOptions[]
  schema?: SchemaPluginOptions
  document?: DocumentPluginOptions
  tools?: Tool[] | ComposableOption<Tool[], ConfigContext>
  form?: SanityFormConfig
  basePath?: string
  subtitle?: string
  icon?: React.ComponentType
  navbar?: {
    components?: {
      ToolMenu: React.ComponentType<ToolMenuProps>
    }
  }
  theme?: StudioTheme
}

These guides are under development. If you have questions or suggestions for improvement, then we want to hear from you. Get in touch via our GitHub discussions page.