Netlify deploy failing: Understanding Sanity hosting options and CI/CD setup
I just commit my sanity installation to my Gatsby Github repo linked to Netlify deploy (Gatsby installation and setting with Netlify existed previously, before to discover and add Sanity to the project) (my Sanity project has been init from scratch, no template, nothing than cli).
Now, Netlify is acting bumping on the first data from Sanity as if not knowing it at all, which is logic as I haven't done anything in particular.
This blocks the Netlify deploy.
So I searched in the docs, I found the «hosting and deployment» page, but reading at it as carefully as possible, I do not understand the difference between the two options:
1. to «serve the bundle» to Github via Noode.js
2. and next paragraph «deploying a CI/CD flow» (what those abbreviations mean?) (Command Interface and ... ??)(Change Directory??).
Difficult to make a choice not understanding anything!
Then it says «create a token», I can do it, no worries, I have done one already.
But «remember to add
user Q/cli as a devDependency», why not, but you mean at the level of the Github repo probably?Probably YES.
I'll appreciate if you could precise some element of information and the pro and cons of 1) and 2).
Thank you in advance ☆
I can see you're dealing with a common confusion when first deploying a Gatsby site with Sanity to Netlify! Let me break this down clearly for you.
Understanding the Setup
First, it's important to understand that Sanity Studio (the content editing interface) and your Gatsby website (the frontend) are two separate things:
Sanity Studio - This is where you edit content. It can be hosted either:
- On Sanity's hosting at
yourname.sanity.studio(free and recommended) - On Netlify or another hosting provider (if you want a custom domain)
Gatsby Website - This is your actual website that pulls content from Sanity's API and displays it to visitors. This is what you're deploying to Netlify.
Why Your Netlify Deploy is Failing
Your Gatsby site needs to be configured to fetch data from Sanity. You need to install and configure the gatsby-source-sanity plugin in your Gatsby project.
Setting Up gatsby-source-sanity
- Install the plugin in your Gatsby project:
npm install gatsby-source-sanity- Configure it in
gatsby-config.js:
module.exports = {
plugins: [
{
resolve: 'gatsby-source-sanity',
options: {
projectId: 'your-project-id',
dataset: 'production',
apiVersion: '2023-05-03', // use today's date
// Optional: if you have a private dataset or want draft previews
token: process.env.SANITY_READ_TOKEN,
watchMode: true, // enables hot-reloading in development
overlayDrafts: true, // shows drafts in development
},
},
],
}- Deploy your Sanity GraphQL API (required for the plugin to work):
cd your-sanity-studio-folder
sanity graphql deployAbout CI/CD (Continuous Integration/Continuous Deployment)
CI/CD stands for "Continuous Integration" and "Continuous Deployment" - it's just a fancy way of saying "automatically build and deploy your site whenever you push code to GitHub." Netlify does this automatically when you connect your GitHub repo, so you don't need to worry about this terminology.
About Tokens and Environment Variables
When the docs mention creating a token and adding @sanity/cli as a devDependency:
Token: Create a read token in your Sanity project at manage.sanity.io (Settings → API → Add new token). This is only needed if your dataset is private or you want to preview draft content.
Add the token to Netlify: Go to your Netlify site settings → Environment variables → Add:
- Key:
SANITY_READ_TOKEN - Value: (paste your token)
@sanity/cli as devDependency: This should be added to your Gatsby project's
package.json, not your Studio project. You can add it with:
npm install --save-dev @sanity/cliThe Two Deployment Options Explained
The confusion in the docs about "serve the bundle" vs "CI/CD flow":
"Serve the bundle" - This refers to deploying your Sanity Studio itself (the editing interface). If you run
sanity deploy, it hosts your Studio atyourname.sanity.studio. This is separate from your Gatsby site."CI/CD flow" - This refers to automatically deploying your Gatsby website whenever you push code. Netlify handles this automatically when you connect your GitHub repo.
Recommended Approach
For your situation, I recommend:
- Host Sanity Studio on Sanity's hosting (
sanity deployfrom your studio folder) - it's free and easiest - Deploy Gatsby to Netlify with the gatsby-source-sanity plugin configured
- Set up environment variables in Netlify if you need the read token
This way, you edit content at yourname.sanity.studio, and your public website is on Netlify, automatically rebuilding when you push code changes to GitHub.
Where Studio Hosting Matters
Hosting your Studio on Netlify vs Sanity's hosting doesn't affect how your Gatsby site fetches data - both setups make API requests to Sanity's Content Lake (the database). The Studio is just an editing interface; the actual content always lives in Sanity's cloud.
The main reason to host Studio on Netlify would be if you want a custom domain for your editing interface, but Sanity's free *.sanity.studio hosting works perfectly fine for most use cases. As mentioned in this community answer, where you host your Studio is a React SPA (single page application) choice - it doesn't change the fact that API requests to Sanity still need to be made to fetch your content.
Show original thread5 replies
Was this answer helpful?
Sanity – Build the way you think, not the way your CMS thinks
Sanity is the developer-first content operating system that gives you complete control. Schema-as-code, GROQ queries, and real-time APIs mean no more workarounds or waiting for deployments. Free to start, scale as you grow.
