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