Migrating Environment Variables

Sanity Studio v3 uses Vite as its default bundler and development server and mostly uses its approach to environment variables. It replaces the implicit replacement of predefined variables in v2.

Sanity's development server will automatically pick up variables in your environment prefixed with SANITY_STUDIO_.

You might be used from server-side applications to access environment variables using process.env.SANITY_STUDIO_VARIABLE_NAME. Since the Studio is a static client-side application, these variables will be bundled and exposed as process.env.SANITY_STUDIO_VARIABLE_NAME. In other words, the value of these variables will be included in the app source code.

# .env
SANITY_STUDIO_PROJECT_ID=your-project-id
SANITY_STUDIO_DATASET=your-dataset-name

// sanity.config.js
import { defineConfig } from "sanity";
import { structureTool } from "sanity/structure";
import schemaTypes from "./schemas";

export default defineConfig({
  projectId: process.env.SANITY_STUDIO_PROJECT_ID,
  dataset: process.env.SANITY_STUDIO_DATASET,
  plugins: [
    structureTool(),
  ],
  schema: {
    types: schemaTypes,
  },
});

It is common practice to keep secret tokens and API keys as environment variables that are not checked into version control. This is a decent strategy for server-side applications where the runtime is protected. However, since the Studio is a client-side application, you will have to approach secrets differently. We recommend using the Sanity Secrets library that gives you hooks and UI components for handling secrets.

Sanity will read .env files by default and make its variables available for the development server. Note that you still have to follow the variable naming conventions mentioned above. We also supports env loading priorities for situations where you want to differentiate between sharing certain variables in all environments and overwriting them for production builds.

.env                # loaded in all cases
.env.local          # loaded in all cases, ignored by git
.env.[mode]         # only loaded in specified mode
.env.[mode].local   # only loaded in specified mode, ignored by git

The default "mode" for the sanity build and sanity deploy commands are production. All other commands use development by default. To override this, you can define the SANITY_ACTIVE_ENV variable (note that this variable has to be defined outside of the .env files, since it determines which files to load).