⚠️ THIS IS A MAINTENANCE RELEASE OF A PREVIOUS MAJOR VERSION OF SANITY

We recommend updating to Sanity Studio v3 which provides exceptional flexibility and an unparalleled developer experience. The core packages for Sanity Studio v2 will only receive critical bug fixes until Dec 7th, 2023

Please head over to the documentation for Sanity Studio v3 to learn more.

You can find migration guides from Studio v2 here.

Installation and upgrading

Upgrade the v2 version of the Command Line Interface (CLI) with:

npm install --global @sanity/cli@v2

Upgrade Sanity Studio with:

sanity upgrade

📓 Full changelog

Installation and upgrading

To initiate a new Studio without installing the CLI globally:

npx create-sanity@latest

To upgrade a v3 Studio:

npm install sanity@latest

✨ Highlights

• Adds getClient() method to reference filter context

🐛 Notable bugfixes

• Invalid references can now be removed from array inputs
• Validation error will now appear when missing a _ref in array of items
• Removes convert to reference button when converting array of references to singular reference
• patch.execute() now reflects that the second argument is optional

📓 Full changelog

Installation and upgrading

To initiate a new Studio without installing the CLI globally:

npx create-sanity@latest

To upgrade a v3 Studio:

npm install sanity@latest

🐛 Notable bugfixes

• General search performance improvements on larger studios (containing thousands of fields)
• Desk Structure is now able to auto-generate IDs from non-ascii source values (for instance cyrillic characters)
• Allows fractional section of a number to have leading zeros (thanks @pauloborges!)
• Fixes studio authentication when using a custom API hostname
• Makes schemas in Shopify online storefront template compatible with GraphQL deployments
• Fixes an issue of document type icons not showing up in array fields
• Fixes a bug where opening a reference field dropdown would not trigger a defined filtering function
• Restores functionality of the "Open in new tab" function for arrays of references
• Fixes issue where clicking a document reference while still loading would result in an invalid link and cause the studio to crash
• Fixes several issues that might occur when dealing with duplicate document IDs across workspaces
• Fixes an issue that might cause the studio to crash when trying to view history in a dataset copied with the --skip-history flag

📓 Full changelog

⚠️ THIS IS A MAINTENANCE RELEASE OF A PREVIOUS MAJOR VERSION OF SANITY

We recommend updating to Sanity Studio v3 which provides exceptional flexibility and an unparalleled developer experience. The core packages for Sanity Studio v2 will only receive critical bug fixes until Dec 7th, 2023

Please head over to the documentation for Sanity Studio v3 to learn more.

You can find migration guides from Studio v2 here.

Installation and upgrading

Upgrade the v2 version of the Command Line Interface (CLI) with:

npm install --global @sanity/cli@v2

Upgrade Sanity Studio with:

sanity upgrade

🐛 Notable bugfixes

• Fixes issue where clicking a document reference while still loading would result in an invalid link and cause the studio to crash
• Fixes an issue that might cause the studio to crash when trying to view history in a dataset copied with the --skip-history flag

📓 Full changelog

Installation and upgrading

To initiate a new Studio without installing the CLI globally:

npx create-sanity@latest

To upgrade a v3 Studio:

npm install sanity@latest

🐛 Notable bugfixes

• Fixes an issue where the accept option for file and image schema types would not be respected by the image and file picker, only new uploads
• Fixes dialog closing behavior in the studio to be more consistent
• Improves readability of date and datetime diffs in the review changes panel
• Fixes an issue where the first focusable element in a document was not focused when opening the document
• Fixes an issue where form dialogs were not closing as esxpected when navigating to a new document
• Fixes an issue where the selected sort option in the document list was not highlighted in the UI
• Fixes an issue where the correct default fieldgroup was not set in an array of objects
• Fixes an issue where opening a browser from the CLI tool on Windows might cause the login process to crash
• Adds missing options in mobile sidebar menu
• Fixes a regression from v3.4.0 in the Portable Text Editor that could corrupt text when typing fast and toggling text decorators (I.e. bold or italic) while typing
• Fixes a regression from v3.4.0 in the Portable Text Editor where it sometimes would error when toggling between different versions in the History View

📓 Full changelog

Installation and upgrading

To initiate a new Studio without installing the CLI globally:

npx create-sanity@latest

To upgrade a v3 Studio:

npm install sanity@latest

✨ Highlights

Improved .env/environment variable handling

Over the past few releases we have been addressing some inconsistencies in how environment variables can be used. This release greatly improves how "dotenv" (.env) files are handled. To summarize the new behavior of environment variables and dotenv files from this release (v3.5.0) and onward:

• All environment variables with the SANITY_STUDIO_ prefix is exposed to the bundle, and is available through process.env.SANITY_STUDIO_.... While they are theoretically also available under import.meta.env, it is not recommended to use them this way since it’s behavior specific to Vite, and thus not available under the same location in Node.js and other environments.
• We now load both .env, .env.local, .env.<mode> and .env.<mode>.local files from the studio root folder. This is consistent with Vite’s behavior.
• The .env files are loaded in the following order:
  • .env
  • .env.local
  • .env.<mode>
  • .env.<mode>.local
• By default, sanity build and sanity deploy will use the production mode, while all other commands will default to the development mode.
  • Setting NODE_ENV to production will set the mode to production, but setting it to other values (such as test) will not change the mode.
  • To use a custom mode, you can set the SANITY_ACTIVE_ENV environment variable.
  • Both NODE_ENV and SANITY_ACTIVE_ENV must be set as a regular shell environment variable, not in .env files, since knowing which .env file to load is based on it.
• Environment variables set in the shell will override variables set in the .env files.
• The environment variables are loaded into both the browser bundle environment, and the CLI context. In other words, running scripts through sanity exec will have access to the same environment variables as the Studio bundle, and you can use environment variables in your sanity.cli.ts/sanity.config.ts files. Make sure you use process.env and not import.meta.env for cross-environment support.

Note that we encourage you to use environment variables sparingly, and define them in a single location instead of spreading them throughout the code base. This makes it easier to see which environment variables are in use, and allows you to easier transition between different environments should you need to. For instance, one might create a src/environment.ts file which re-exports the environment variables:

export const myCompanyInternalApiUrl = process.env.SANITY_STUDIO_MY_COMPANY_INTERNAL_API_URL
export const someOtherVariable = process.env.SANITY_STUDIO_SOME_OTHER_VARIABLE

Programmatic usage

Should you want to reuse the environment variable handling in other contexts (your own scripts, or using a different bundler etc), you can import and utilize the new getStudioEnvironmentVariables() method from sanity/cli:

import {getStudioEnvironmentVariables} from 'sanity/cli'

console.log(getStudioEnvironmentVariables())
// {SANITY_STUDIO_SOME_VAR: 'yourVariableValue'}

Note that .env files are not loaded by default when using this method. To do so, pass an envFile option:

import {getStudioEnvironmentVariables} from 'sanity/cli'

console.log(
  getStudioEnvironmentVariables({
    envFile: {
      mode: 'production',
      envDir: '/path/to/some-dotenv-root'
    }
  })
)

🐛 Notable bugfixes

• Fixes an issue where generation 1 GraphQL APIs would have changed pluralization rules for types ending with a number.

📓 Full changelog

Installation and upgrading

To initiate a new Studio without installing the CLI globally:

npx create-sanity@latest

To upgrade a v3 Studio:

npm install sanity@latest

Notable changes

• The studio has been upgraded to use @sanity/client v5, which boasts full Node.js ESM runtime support, a smaller footprint and much more

🐛 Notable bugfixes

• Fixed a bug that could lead to duplication of a single block in the Portable Text Editor

📓 Full changelog

Installation and upgrading

To initiate a new Studio without installing the CLI globally:

npx create-sanity@latest

To upgrade a v3 Studio:

npm install sanity@latest

Notable changes

• Added ability to mark project studio templates as typescript-only

📓 Full changelog

Installation and upgrading

To initiate a new Studio without installing the CLI globally:

npx create-sanity@latest

To upgrade a v3 Studio:

npm install sanity@latest

✨ Highlights

A custom API hostname can now be configured for the studio through the apiHost configuration parameter. Note that the configured API host must behave the same as Sanity's API. This is mostly useful for enterprise customers with custom API CNAME enabled (get in touch if you are interested in this feature).

🐛 Notable bugfixes

• Disables sorting of array items when readOnly is set
• Updates design of the presence menu to make non-clickable users appear greyed out
• Updates @sanity/schema module with a new named export – the default export is now deprecated and will give a warning when used
• Fixes behaviour so that the editing pane will now scroll the relevant field into view when validation does not pass
• Improves readability for tags array inputs in read-only mode
• Enables fetching unresolved cross-dataset references through GraphQL API

📓 Full changelog

⚠️ THIS IS A MAINTENANCE RELEASE OF A PREVIOUS MAJOR VERSION OF SANITY

We recommend updating to Sanity Studio v3 which provides exceptional flexibility and an unparalleled developer experience. The core packages for Sanity Studio v2 will only receive critical bug fixes until Dec 7th, 2023

Please head over to the documentation for Sanity Studio v3 to learn more.

You can find migration guides from Studio v2 here.

Installation and upgrading

Upgrade the v2 version of the Command Line Interface (CLI) with:

npm install --global @sanity/cli@v2

Upgrade Sanity Studio with:

sanity upgrade

📓 Full changelog

Installation and upgrading

To initiate a new Studio without installing the CLI globally:

npx create-sanity@latest

To upgrade a v3 Studio:

npm install sanity@latest

🐛 Notable bugfixes

• Fixes an issue that in some cases would prevent validation status from appearing for a document
• Fixes an issue that ignored the readOnly state for fields inside fieldsets

📓 Full changelog

⚠️ THIS IS A MAINTENANCE RELEASE OF A PREVIOUS MAJOR VERSION OF SANITY

We recommend updating to Sanity Studio v3 which provides exceptional flexibility and an unparalleled developer experience. The core packages for Sanity Studio v2 will only receive critical bug fixes until Dec 7th, 2023

Please head over to the documentation for Sanity Studio v3 to learn more.

You can find migration guides from Studio v2 here.

Installation and upgrading

Upgrade the v2 version of the Command Line Interface (CLI) with:

npm install --global @sanity/cli@v2

Upgrade Sanity Studio with:

sanity upgrade

Notable changes

• Upgrades the portable text editor to the latest compatible version
• Fixes a potential build error caused by multiple versions of RxJS

📓 Full changelog

Installation and upgrading

To initiate a new Studio without installing the CLI globally:

npx create-sanity@latest

To upgrade a v3 Studio:

npm install sanity@latest

✨ Highlights

Improve readability for document history dates

The document history timeline now displays full dates in tooltips on hover

📓 Full changelog

Installation and upgrading

To initiate a new Studio without installing the CLI globally:

npx create-sanity@latest

To upgrade a v3 Studio:

npm install sanity@latest

✨ Highlights

Date range support in global search

It's now possible to easily search for documents between two dates in the global search.

🐛 Notable bugfixes

• Fixes an issue where a configured studio-wide basePath would not be respected in build output, and workspaces would have to manually include the prefix in each workspace base path
• Enables access to studio-prefixed environment variables through process.env
• Fixes an issue where replacing the image asset in an image field would sometimes fail silently
• Fixes an issue where using React components in field titles or descriptions could crash global search

📓 Full changelog

Installation and upgrading

To initiate a new Studio without installing the CLI globally:

npx create-sanity@latest

To upgrade a v3 Studio:

npm install sanity@latest

🐛 Notable bugfixes

• fix issue in the Node.js runtime wrapper causing the groq tagged template literal to sometimes be undefined

📓 Full changelog

Installation and upgrading

To initiate a new Studio without installing the CLI globally:

npx create-sanity@latest

To upgrade a v3 Studio:

npm install sanity@latest

🐛 Notable bugfixes

• Fixes an issue where the Node.js ESM specific export for groq were missing from the package published to npm
• Fixes a potential race condition with duplicate keys when an editor deletes all the content of a portable text editor while other editors are editing the same document

📓 Full changelog

Installation and upgrading

To initiate a new Studio without installing the CLI globally:

npx create-sanity@latest

To upgrade a v3 Studio:

npm install sanity@latest

🐛 Notable bugfixes

• Fixes a regression in [email protected] that is missing a default export affecting Node.js ESM runtimes

📓 Full changelog

Installation and upgrading

To initiate a new Studio without installing the CLI globally:

npx create-sanity@latest

To upgrade a v3 Studio:

npm install sanity@latest

✨ Highlights

RxJS upgraded to v7

This is an internal change, but if you have RxJS as a dependency in your Studio project you should make sure to upgrade to v7 of RxJS in your package.json. Otherwise you may get build errors due to changes in the Observable interface between v6 and v7 (note: this is a type change only, and should not affect the runtime behavior of your studio).

If you get a build error saying something similar to:

TS2322: Type 'Observable<…>' is not assignable to type 'ObservableInput<any>'. 
  Type 'Observable<…>' is not assignable to type 'Observable<any>'. 
  The types of 'source.operator.call' are incompatible between these types. 
…

Then the solution is to upgrade the version of RxJS used in your project or library to 7.x. See the full list of breaking changes in RxJS 7

Vite upgraded to v4

This is an internal change, but theoretically there might be small changes to how assets are handled between v3 and v4. If you're using custom Vite plugins or you are loading CSS or other files, please make sure they still work after the upgrade.

Notable changes

• Reintroduces some flags for sanity graphql deploy. Note that flags will apply to all configured GraphQL APIs.

Notable bugfixes

• Fixes issue with useFormValue hook lagging one iteration behind
• Fixes issue where the uploaded images menu was inaccessible
• Fixes some incorrect typings in defineField() when using Rule.valueOfField() - thanks @fritz-c
• Adds schema validation error when defining already defined field names for image and file types
• Supports Node ESM (>=14)

📓 Full changelog

Installation and upgrading

To initiate a new Studio without installing the CLI globally:

npx create-sanity@latest

To upgrade a v3 Studio:

npm install sanity@latest

🐛 Notable bugfixes

• Fixed an issue introduced in v3.1.3 that caused the CLI to crash (#4035)

Installation and upgrading

To initiate a new Studio without installing the CLI globally:

npx create-sanity@latest

To upgrade a v3 Studio:

npm install sanity@latest

🐛 Notable bugfixes

• Fixes an issue that could give false validation errors for complex documents
• Hides restore action when revision is latest version
• Improves responsiveness of file and image inputs for narrow widths
• Restores transition effect when reordering primitive array values
• Fixes an issue with the vision tool causing the query param errors tooltip disappear behind the above panel

📓 Full changelog