Sanity Studio v3 is here. Find out more on our blog →

Environment variables

Use environment variables to configure the studio and expose values to the JavaScript environment

In certain cases, you will want to configure the Sanity Studio build configuration without modifying sanity.json. Common use cases are:

  • Targeting different datasets, or projects from the same code base in continuous integration workflows
  • Configuring different styling depending on the environment to give better visual cues between staging and production
  • Make schemas, structure, or other configuration behave differently depending on the studio’s environment

The Sanity Studio comes with some predefined variables that you can override by defining them when you run Studio and access inside Studio code. You can also add your own variables to the Studio environment with the SANITY_STUDIO_ prefix, and you can use so-called “dot env” (.env) files to more easily manage environment variables when developing locally.

Reserved variable names

There are certain environment variables with predefined behavior. Note that these will not inherit the values from sanity.json and will be undefined until they are explicitly set.

  • SANITY_STUDIO_API_PROJECT_ID - Sets the project ID for the current build. This overrides the sanity.json property api.projectId. This environment variable has higher precedence than any env configuration defined in sanity.json.
  • SANITY_STUDIO_API_DATASET - Sets the dataset for the current build. This overrides the sanity.json property api.dataset. This environment variable has higher precedence than any env configuration defined in sanity.json.
  • SANITY_STUDIO_PROJECT_BASEPATH - Sets the base path for Studio's router and paths, for when you are hosting the studio yourself on a non-root path. Overrides the sanity.json property project.basePath.
  • SANITY_STUDIO_PROJECT_NAME - Sets the configured Sanity project name, used in places like the Studio document title and in the default Studio navigation bar. Overrides the sanity.json property


These environment variables do not override the configuration for the experimental spaces feature. We're working on figuring out how to combine the two in a seamless manner.

You can retrieve the currently targeted dataset—even when using spaces—from the client:

import sanityClient from 'part:@sanity/base/client'
const client = sanityClient.withConfig({apiVersion: `2022-01-10`})
const {dataset} = client.clientConfig

Example: Overriding the dataset

To override the dataset defined in sanity.json and build the studio using a dataset named “staging”:

SANITY_STUDIO_API_DATASET=staging sanity build

Bundled variables

Any other environment variables that are prefixed with SANITY_STUDIO_ will be available inside the javascript bundle and can be accessed from code as process.env.SANITY_STUDIO_YOUR_ENV_VAR


Important: Since the values of these variables will be built into a static javascript file that is (usually) readable without any authentication, be careful not to put secret API keys and authentication tokens here.

Please note that the environment variables are not actually exposed as an object in the javascript runtime - instead, any references to process.env.SANITY_STUDIO_* will be replaced at build time with the value of that environment variable.

For instance, if your code contains:
const configValue = process.env.SANITY_STUDIO_MY_CONFIG_VALUE and the value of that environment variable is set to Movies Unlimited, the actual code that is built will read const configValue = "Movies Unlimited"

This means that attempting to destructure process.env will not yield the correct values.

Example: Using environment variables to alter Studio’s logo

If you have added a custom Studio logo, you can alter the logo component to output “STAGING” to give your authors a visual cue of which Studio they are in.

import React from 'react'

const dataset = process.env.SANITY_STUDIO_API_DATASET

const Logo = () => {
  if(dataset === "staging") {
    return (
  return (
    // ... an svg graphic, omitted here for brevity ...

export default Logo

Dot env files (.env)

For your convenience, you can also define environment variables through a so-called “dot env” file. These files should be put in your Sanity Studio's root folder (alongside sanity.json) and suffixed with the targeted environment. For instance, a development configuration would be named .env.development while a production version would be .env.production

The environment is defined by the value of the SANITY_ACTIVE_ENV environment variable. If not defined, it will default to development when running the sanity start command, while it will use production when running sanity build and sanity deploy.

Note that only environment variables that begin with SANITY_STUDIO_ will be included in the JavaScript bundle and can be accessed from Studio code.

These files are also automatically loaded when running scripts through the sanity exec command. This command will use the environment defined by SANITY_ACTIVE_ENV, falling back to NODE_ENV, and if neither is defined it will use development.

Please note that you shouldn't commit .env.* files to your source control and rather use options for setting the environment variables provided by your host or continuous integration provider.

Was this article helpful?