Set up a Gatsby project with Sanity

Updated: Feb 17 2022

Step 1: Create new Gatsby project #

Create new folder for new Gatsby site.

mkdir gatsby-sanity-frontend

Move into that folder and create a fresh Gatsby project using the default Gatsby starter.

cd gatsby-sanity-frontend && gatsby new .

Step 2: Install Sanity dependency #

Install Gatsby Source Sanity plugin to your project.

npm install --save gatsby-source-sanity

Inside gatsby-config.js add plugin:

	resolve: 'gatsby-source-sanity',
		options: {
		projectId: '<yourProjectId>',
		dataset: '<yourDatasetName>',

You will find your projectId and dataset inside sanity.json found within your studio project.

If you chose to make your dataset private you will also need to add a permissions token like this:

	resolve: 'gatsby-source-sanity',
	options: {
		projectId: '<yourProjectId>',
		dataset: '<yourDatasetName>',	// a token with read permissions is required
		// if you have a private dataset
		token: process.env.MY_SANITY_TOKEN,

Step 3: (optional) Enable Gatsby watch mode for drafts #

Sanity has a cool feature which allows for realtime content updates in local development. So if you have your content studio and front end side-by-side in two different browser windows, you will see any changes you make to the content in the studio change in realtime in Gatsby.

To get this set up correctly

  • go to and find your project (or run the command sanity manage in the studio folder).
  • Head to Settings > API, then scroll down to the Tokens section
  • Add a new token and give it read privileges.
  • Back in the root of your /web project locate .env.development.template and rename it to .env.development.
  • Add your new token to the key: SANITY_READ_TOKEN="<token here>"
  • Inside gatsby-config.js make sure you have token: process.env.SANITY_READ_TOKEN, as one of the options in your gatsby-source-sanity plugin config.

Restart your development environment for the changes to propagate. Make some changes in your studio and watch them appear in realtime in Gatsby.

Further resources #

Reply by email

Monthly Newsletter

Once a month I curate a newletter for designers and developers interested in static sites, CSS and web performance. Check out past issues to get an idea.