Set up a Gatsby project with Sanity

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 manage.sanity.io 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 #

• Blazing fast development with Gatsby and Sanity.io from Knut Melvær.
• Enable Gatsby Watchmode for Drafts from Sanity.io