Tag-based revalidation

So far, the focus has been on revalidating individual post pages when a post changes. But with the current content model, more than just post-type document fields are queried—and there's more than one route where those responses are rendered.

A post-type document could contain many category references and a single author reference. Ideally, a content author editing any of these document types should impact every route where that content is rendered.

This is made possible with revalidateTag.

In this lesson, you'll remove time-based revalidation from your existing queries instead of tag-based. You now know how to implement time and path-based revalidation in the future for instances where it is applicable.

When performing a fetch, tags can be an array of strings of any value. It's a standard convention to use the Sanity document types expected to be in the response.

For the posts index, add tags for the three document types that provide data for the response. If any documents of these types change, you'll want to revalidate any page that renders them.

const posts = await sanityFetch({
  query: POSTS_QUERY,
  tags: ['post', 'author', 'category'],
})

You can be more granular for an individual post page. You don't need to revalidate every post page because one has post changed. Thankfully, the dynamic route provides us with a unique identifier for this post—its slug—so you can use it for this page's cache tags.

const post = await sanityFetch({
  query: POST_QUERY,
  params,
  tags: [`post:${params.slug}`, 'author', 'category'],
})

Once again, you will need to create an API route to accept a request from a GROQ-powered webhook and perform the revalidation.

import { revalidateTag } from 'next/cache'
import { type NextRequest, NextResponse } from 'next/server'
import { parseBody } from 'next-sanity/webhook'

type WebhookPayload = {
  tags: string[]
}

export async function POST(req: NextRequest) {
  try {
    if (!process.env.SANITY_REVALIDATE_SECRET) {
      return new Response(
        'Missing environment variable SANITY_REVALIDATE_SECRET',
        { status: 500 },
      )
    }

    const { isValidSignature, body } = await parseBody<WebhookPayload>(
      req,
      process.env.SANITY_REVALIDATE_SECRET,
      true,
    )

    if (!isValidSignature) {
      const message = 'Invalid signature'
      return new Response(JSON.stringify({ message, isValidSignature, body }), {
        status: 401,
      })
    } else if (!Array.isArray(body?.tags) || !body.tags.length) {
      const message = 'Bad Request'
      return new Response(JSON.stringify({ message, body }), { status: 400 })
    }

    body.tags.forEach((tag) => {
      revalidateTag(tag)
    })

    return NextResponse.json({ body })
  } catch (err) {
    console.error(err)
    return new Response((err as Error).message, { status: 500 })
  }
}

Once again, we have prepared a webhook template for your Project. It has most of the settings preconfigured. You'll just need to update a few that are unique to you:

You're now ready to automatically revalidate your posts index and individual post pages in your web application simply by changing a post, author, or category document in Sanity Studio.

With all the machinery in place, you can test that what you've set up works.

If it is a cache MISS, reload the page, and you should see it cached for the next request.

Almost instantly after publishing, in your terminal you should see a POST request which was automatically made from the GROQ-powered webhook:

 POST /api/revalidate/tag 200 in 3540ms

If you reload the page again, it should be cached for the next request. You should see a cache MISS in the terminal, your updated title on the post-index and the individual post page.

With that, you're all cached up with somewhere to go. Let's review it in the final lesson.