Sanity deployment options for Netlify: serve bundle vs CI/CD flow explained

I can totally understand your confusion! Let me break this down into clear, practical steps for your Gatsby + Sanity + Netlify setup.

First, the good news: you don't need to choose between those two "hosting and deployment" options you're reading about. Those sections are actually about hosting Sanity Studio itself (the content editing interface), not about deploying your Gatsby site. Let me clarify what's happening:

What's Actually Going Wrong

Your Netlify build is failing because your Gatsby site needs to fetch content from Sanity during the build process, but it doesn't have the proper configuration yet. This is a common setup step that's separate from hosting decisions.

What You Need to Do

1. Install the Gatsby source plugin (if you haven't already):

npm install gatsby-source-sanity

2. Configure your gatsby-config.js to connect to Sanity:

module.exports = {
  plugins: [
    {
      resolve: 'gatsby-source-sanity',
      options: {
        projectId: 'your-project-id',
        dataset: 'production', // or whatever dataset you're using
        token: process.env.SANITY_TOKEN, // optional, for private datasets
        watchMode: true, // for development
      },
    },
  ],
}

3. Set up environment variables in Netlify:

• Go to your Netlify site dashboard
• Navigate to Site settings → Build & deploy → Environment
• Add these variables:
  • SANITY_PROJECT_ID: your project ID (find it in sanity.json or your Sanity dashboard)
  • SANITY_DATASET: usually "production"
  • SANITY_TOKEN: only needed if your dataset is private (create one in your Sanity project settings)

About Those Confusing Terms

CI/CD means "Continuous Integration/Continuous Deployment" - it's just a fancy way of saying "automatically build and deploy when you push code to GitHub."

"Serving the bundle" refers to hosting your Sanity Studio (the content management interface where editors create content). You have two options:

1. Host Studio on Netlify: Deploy the Studio as a separate site on Netlify
2. Host Studio on Sanity's servers: Run sanity deploy to host it at yourproject.sanity.studio

For most people, I'd recommend option 2 (sanity deploy) because it's simpler - just run that command and your Studio is hosted. Your Gatsby site remains separate on Netlify.

The @sanity/cli Dependency

When the docs mention adding @sanity/cli as a devDependency, they mean in your Sanity Studio folder (where your sanity.json file lives), not your Gatsby repo. If you initialized Sanity properly, this should already be there.

Understanding Studio Hosting

As explained in this community answer about hosting Studio on Netlify, where you host your Studio doesn't affect API requests. The Studio is just a React single-page application - your Gatsby site will still make requests to Sanity's Content Lake regardless of where the Studio lives.

Pros of hosting Studio on Sanity's servers (sanity deploy):

• Simpler setup (one command)
• No extra configuration needed
• Automatic SSL and global CDN

Pros of hosting Studio on Netlify:

• Custom domain control
• Integration with your existing deployment workflow
• Keep everything in one place

Quick Checklist

• Install gatsby-source-sanity in your Gatsby project
• Configure it in gatsby-config.js with your project ID and dataset
• Add environment variables to Netlify (especially if using a private dataset)
• Push your changes to GitHub to trigger a new Netlify build
• Deploy your Sanity Studio separately with sanity deploy (run this in your Studio folder)

The Netlify technology partner page has more details about triggering rebuilds when content changes, which you'll want to set up next using deploy hooks or Sanity Functions for more advanced automation!