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 continous integration workflows
  • Configuring different styling depending on 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 the studio, and access inside the 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 three 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 value in the studio's sanity.json api.projectId property. This environment variable has a higher presedence than any env configuration defined in sanity.json.
  • SANITY_STUDIO_API_DATASET - Sets the dataset for the current build. This overrides the value in the studio's sanity.json api.dataset property. This environment variable has a higher presedence than any env configuration defined in sanity.json.
  • SANITY_STUDIO_PROJECT_BASEPATH - Sets the base path for the studios router and paths, for when you are hosting the studio yourself on a non-root path. Overrides the studio's sanity.json project.basePath property.

Gotcha

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.

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

Gotcha

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 projectName = process.env.SANITY_STUDIO_PROJECT_NAME and the value of that environment variable is set to Movies Unlimited, the actual code that is built will read const projectName = "Movies Unlimited"

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

Example: Using environment variables to alter the 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 (
      <div>STAGING</div>
    )
  }
  return (
    <svg>
    // ... an svg graphic, omitted here for brevity ...
    </svg>
  )
}

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.

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 continous integration provider.

Was this article helpful?