Using Sanity with GraphQL in Next.js: Tutorials and Best Practices

You can absolutely use GraphQL with Sanity and Next.js! There's no fundamental reason not to, but there are some important considerations to be aware of in 2024 (and even back in 2021) that might influence your decision.

Key Limitations of Sanity's GraphQL API

The biggest thing to know is that Sanity's GraphQL API is read-only - it doesn't support mutations. This means you can query content with GraphQL, but if you need to create, update, or delete content programmatically, you'll need to use the Sanity JavaScript client for those operations.

Additionally, the GraphQL API doesn't support subscriptions, so for real-time content updates or live preview functionality, you'd need to use Sanity's Listening API or the JavaScript client with GROQ.

Why Many Developers Prefer GROQ

While GraphQL is a solid choice if you're already familiar with it, GROQ (Sanity's native query language) offers some advantages:

• More flexible projections: GROQ allows you to transform and shape data directly in your queries in ways that GraphQL requires custom resolvers for
• Better for complex content structures: Particularly when working with Portable Text (Sanity's rich text format), GROQ tends to be more straightforward
• Single tool for everything: Since mutations and subscriptions require the JS client anyway, using GROQ means you're working with one consistent approach

That said, GraphQL has its own benefits like schema introspection, type safety with code generation tools, and familiarity if your team already uses it elsewhere.

Using GraphQL with Next.js

If you want to proceed with GraphQL, here's the basic approach:

1. Deploy your GraphQL API from your Sanity project:

   sanity graphql deploy

2. Set up Apollo Client (or your preferred GraphQL client) in your Next.js app to query the endpoint at https://YOUR_PROJECT_ID.api.sanity.io/v2023-08-01/graphql/YOUR_DATASET/default

3. For draft/preview content, you'll need to pass a token with read permissions and use the appropriate Perspectives parameter in your queries. The GraphQL API does support Perspectives for accessing draft content via the overlayDrafts functionality.

4. For mutations or real-time updates, you'll still need to install @sanity/client and use it alongside your GraphQL setup

Hybrid Approach

Many developers actually use both - GraphQL with Apollo Client for data fetching in their Next.js app, and the Sanity JavaScript client with GROQ for preview subscriptions or content mutations. This gives you the best of both worlds.

Bottom Line

In 2024, the recommendation has shifted somewhat toward GROQ as the primary approach, especially with modern features like the Live Content API for real-time content delivery. But GraphQL is still fully supported and works great if it fits your workflow better - it's been out of beta since February 2020 and is described as "one of the richest API offerings in content management". The main thing is understanding the read-only limitation and planning accordingly for mutations and real-time features.