Upgrading Sanity Studio from v2 to v3 is essential as v2 is no longer supported, and all future improvements are exclusive to v3. Sanity Studio v3 introduces a modern developer experience with a Vite-based build system for faster hot reloading, support for React 18, and a new TypeScript-first configuration system.

Upgrading from Sanity Studio v2 to v3 means replacing the legacy sanity.json with a modern sanity.config.js, dropping deprecated packages, refactoring part:X imports, and aligning with the new Studio APIs; all while keeping your content and editor workflows unchanged.

Sanity V2 to V3 Migration Prerequisites

Before starting the upgrade, ensure the following tools and dependencies are ready:

  • Node.js (v16+ recommended)
  • npm or yarn
  • A backup of your current sanity project (just in case!)

Step-by-Step Migration Guide

Remove Deprecated Sanity Packages

Sanity Studio v3 consolidates core functionality under a single package. You’ll need to remove older v2 packages from package.json.

Remove:

"@sanity/base",

"@sanity/core",

"@sanity/default-layout",

"@sanity/default-login",

"@sanity/desk-tool"

Run:

code
npm uninstall @sanity/base @sanity/core @sanity/default-layout @sanity/default-login @sanity/desk-tool

Install the New sanity Package

To run Sanity Studio v3, you need the latest core package. Installing it ensures your project is built on the supported and updated version.

Install the latest version of Sanity Studio:

This command fetches and installs the most recent v3 release of Sanity Studio.

code
npm install sanity@latest

Upgrade React and UI Packages (If Needed)

Sanity Studio v3 needs React 18 and the latest @sanity/ui package for full compatibility. Updating these ensures your Studio runs without version conflicts. Make sure your project uses compatible versions.

This command installs React 18, React DOM, and the Sanity UI library at versions supported by v3.

code
npm install react@^18.2.0 react-dom@^18.2.0 @sanity/ui@^1

Migrate from sanity.json to sanity.config.js

Sanity Studio v3 replaces the sanity.json configuration file with a modern JavaScript-based sanity.config.js. This new format supports TypeScript, better tooling, and direct imports for plugins. Migrating your configuration is essential to make v3 work correctly.

Example Conversion: sanity.json (v2)

code
{
code
"projectId": "your-project-id",
code
"dataset": "production",
code
"plugins": ["@sanity/desk-tool"],
code
"schema": {
code
"types": []
code
}
code
}

sanity.config.js (v3)

In v3, configuration is defined in JavaScript using defineConfig. Plugins are imported directly, and schema types are structured under the schema property.

code
import { defineConfig } from 'sanity'
code
import { deskTool } from 'sanity/desk'
code
code
export default defineConfig({
code
projectId: 'your-project-id',
code
dataset: 'production',
code
plugins: [deskTool()],
code
schema: {
code
types: [],
code
},
code
})

Replace Legacy part:X Imports

Sanity Studio v2 used the legacy parts system to extend or replace internal components. This system has been completely removed in v3. To stay compatible, you must update imports to use the new Studio APIs.

❌ Old (v2):

In v2, custom components were imported with part:X paths.

code
import CustomLogo from 'part:@sanity/base/logo'

✅ New (v3):

In v3, you import directly from the official Studio APIs and register components through provided slots. The exact replacement depends on what you were customizing; refer to the Migration Cheat Sheet for mappings.

Update Custom Components

If you’ve created custom components for fields, inputs, or views, these must now be passed through the new components property inside the schema.

Example:

code
schema: {
code
types: [
code
defineType({
code
name: 'article',
code
type: 'document',
code
fields: [
code
{
code
name: 'title',
code
type: 'string',
code
components: {
code
input: CustomTitleInput
code
},
code
},
code
],
code
}),
code
]
code
}

Update or Replace Plugins

Sanity Studio v3 requires plugins to be updated or replaced with v3-compatible versions. Using outdated plugins may break your Studio or prevent features from working.

Check if the Plugins You Use Support Studio v3: Most official and community plugins have been updated. You can confirm compatibility by browsing the Sanity Exchange.

Reinstall Compatible Versions via NPM: Once you’ve identified v3-ready plugins, reinstall them in your project to ensure they work with the updated Studio.