Connecting existing Gatsby project to Sanity: gatsby-source-sanity vs GROQ client

Great question! You're on the right track thinking about gatsby-source-sanity as your main integration point. Let me break down your options and clarify the GROQ vs GraphQL situation with Gatsby.

Yes, gatsby-source-sanity is what you need

The gatsby-source-sanity plugin is indeed the standard way to connect your existing Gatsby project to your existing Sanity project. You're right to focus on its README - it gives you a clean, minimal setup without all the extra starter template code.

How gatsby-source-sanity actually works

Here's the key thing to understand: gatsby-source-sanity fetches data from Sanity and transforms it into Gatsby's GraphQL layer. The plugin makes only two API requests during the entire build process - it first fetches the GraphQL Schema Definitions from Sanity's deployed GraphQL API, then streams all accessible documents using the project's export endpoint.

So the flow is:

1. Plugin fetches from Sanity's Content Lake
2. Plugin transforms data into Gatsby nodes
3. You query those nodes with GraphQL in your Gatsby pages/components

This is actually efficient - you get to query with GraphQL in your Gatsby components (which is the standard Gatsby pattern), and the plugin handles the Sanity integration efficiently.

Can you use GROQ directly in Gatsby?

Yes! You have two options:

Option 1: Use gatsby-source-sanity (recommended for most cases)

• Handles build-time data fetching automatically
• Supports watchMode for development hot-reloading
• Supports overlayDrafts for preview functionality
• You query with GraphQL in your components
• Generates special _raw fields for Portable Text data

Option 2: Use @sanity/client directly with GROQ

• Import the JavaScript client directly in your Gatsby files
• Write raw GROQ queries using client.fetch
• Useful for client-side queries or custom build logic
• Can be used alongside gatsby-source-sanity

Example of using the client directly:

import sanityClient from '@sanity/client'

const client = sanityClient({
  projectId: 'your-project-id',
  dataset: 'production',
  apiVersion: '2023-05-03',
  useCdn: true
})

// In a Gatsby page or during build
const data = await client.fetch(`*[_type == "post"]{title, slug}`)

Is GROQ more efficient than GraphQL at build time?

Both GROQ and GraphQL are query interfaces to the same underlying Content Lake, so the performance difference at build time is minimal. GROQ is Sanity's native query language and is more expressive for certain content transformations and projections, but for Gatsby builds, the efficiency comes from how gatsby-source-sanity fetches data (just two API requests total), not which query language you use.

The real advantage of GROQ is its expressiveness and the fact that it's designed specifically for Sanity's content structure. But when using gatsby-source-sanity, you're querying Gatsby's GraphQL layer (which is already optimized), not Sanity directly during component renders.

About watchMode and cool features

The gatsby-source-sanity plugin gives you:

• watchMode: true: Sets up a listener that pushes changes from Sanity to Gatsby in real-time without additional API queries during development
• overlayDrafts: true: Preview draft content in development while only showing published content in production (requires a read token)
• Image optimization: Integration with Gatsby's image processing
• _raw fields: Special fields for accessing raw Portable Text data with reference resolution

You're not missing anything by using just this plugin - it's the recommended approach and includes all the integration features you need.

My recommendation

1. Start with gatsby-source-sanity following its README
2. Deploy your GraphQL API from your studio folder: sanity graphql deploy
3. Configure watchMode: true in development for live updates
4. Add overlayDrafts: true with a read token for draft previews
5. Use GraphQL in your Gatsby components (standard Gatsby pattern)
6. Only reach for @sanity/client with GROQ if you need client-side queries or custom build-time logic that doesn't fit the source plugin pattern

This gives you a clean, minimal setup between your existing projects while maintaining all the powerful features. You'll understand exactly what's happening without the extra template code you don't need.