Netlify deploy failing: Understanding Sanity hosting options and CI/CD setup

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:

1. 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)

2. 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

1. Install the plugin in your Gatsby project:

npm install gatsby-source-sanity

2. 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
      },
    },
  ],
}

3. Deploy your Sanity GraphQL API (required for the plugin to work):

cd your-sanity-studio-folder
sanity graphql deploy

About 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/cli

The Two Deployment Options Explained

The confusion in the docs about "serve the bundle" vs "CI/CD flow":

1. "Serve the bundle" - This refers to deploying your Sanity Studio itself (the editing interface). If you run sanity deploy, it hosts your Studio at yourname.sanity.studio. This is separate from your Gatsby site.

2. "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:

1. Host Sanity Studio on Sanity's hosting (sanity deploy from your studio folder) - it's free and easiest
2. Deploy Gatsby to Netlify with the gatsby-source-sanity plugin configured
3. 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.