How to set up a staging or development environments with Sanity

I redesigned my portfolio recently and switched from using Contentful to Sanity to manage my website content. After I did some major content edits, I quickly realized that I had completely forgotten to setup a development environment and accidentally pushed some work-in-progress content to my production site 😅 I was able to fix it quickly but I still think it’s a good practice to always have a test environment setup, even on your own sites, to test major content and code changes without accidentally breaking something on the main production site.

To get a test environment up and running with Sanity, we’ll need to create an additional dataset for the test content and configure the Sanity configuration files to use the appropriate dataset for the current environment. We will also need an additional branch of the site for code changes that should not be pushed to the main production site. Additional branches are also important when considering using webhooks to automatically deploy changes to the staging or production site.

Alright, let’s get into it.

Setup a development/staging dataset

Assuming you already have a production dataset, let’s create a new dataset named dev or staging. We’ll then import the data from the production dataset to your newly created dataset. You can do that either in your Sanity dashboard under “Datasets” or using the commands below:

sanity dataset create dev

sanity dataset export production ~/production.tar.gz

sanity dataset import production.tar.gz dev

Create an environment variable for your development/staging environment

To ensure the correct dataset is used for the environment, we can use environment variables to load the correct dataset. We will be creating two files in your project root folder:

.env.development

.env.production

In each of these files, set SANITY_STUDIO_API_DATASET equal to the appropriate data set.

# .env.development
SANITY_STUDIO_API_DATASET=development

# .env.production
SANITY_STUDIO_API_DATASET=production

Configure Sanity configuration files

Next, we need to update our Sanity configuration files to set up an additional workspace for the new dataset and switch to correct the dataset for the environment.

// sanity.config.ts

const isProduction = process.env.NODE_ENV === "production";

export default defineConfig({
  name: "site",
  title: isProduction ? "Production Workspace" : "Dev Workspace",
  projectId: process.env.NEXT_PUBLIC_SANITY_PROJECT_ID || '',
  dataset: isProduction ? "production" : "development",
  basePath: "/studio",
  ...
});

// sanity.client.ts

import { createClient, type ClientConfig } from "@sanity/client";

const isProduction = process.env.NODE_ENV === "production";

const config: ClientConfig = {
  projectId: process.env.NEXT_PUBLIC_SANITY_PROJECT_ID,
  dataset: isProduction ? "production" : "development",
  ...
};

...

// sanity.cli.js
import { defineCliConfig } from "sanity/cli";

export default defineCliConfig({
  api: {
    projectId: process.env.NEXT_PUBLIC_SANITY_PROJECT_ID || '',
  },
  graphql: [
    {
      id: "production",
      workspace: "production",
    },
    {
      id: "development",
      workspace: "development",
    },
  ],
});

Test out that you have everything set up by making changes to your dev dataset and checking that those changes are reflected on your dev/staging site when running your site locally. If you are seeing the changes then everything's working correctly!

If you go to your Sanity Studio for your new environment, you should also see that the workspace is now "Dev Workspace" (or whatever you call yours).

Keeping your datasets in sync

As far as I know, the only way to keep your datasets in sync in Sanity is to overwrite them occasionally by completely replacing the content in your dev/staging dataset with the content from the production dataset.

To update your dev/staging dataset with your production dataset, we will essentially do the same thing we did when we created the new dataset by copying the production dataset and dropping it in the dev/staging dataset.

🚨 Always be careful when messing around with your datasets! You don't want to accidentally delete something you didn't want to delete. So, always double-check your commands. 🚨

In your Sanity project directory, run the following commands:

sanity dataset export production ~/production.tar.gz

After this, we can import it into development. Find the file path where your export from above was saved to then run:

sanity dataset import <path to file>/production.tar.gz dev --replace

Also, the --replace flag will overwrite the development dataset. Always double-check that is what you are trying to do. Use --missing flag if you just want to add any missing content that's not in the development dataset.

It's kind of annoying to have to do this manually so I'm definitely on the lookout for a way to automatically sync content between the datasets. But, for now, this works fine!

How to set up a staging or development environments with Sanity

Setup a development/staging dataset

Create an environment variable for your development/staging environment

Configure Sanity configuration files

Keeping your datasets in sync

Contents