How to Implement Slug-Based Routing with a Headless CMS

Slug-based routing is the pattern of using a document's slug field — a URL-safe string like getting-started-with-nextjs — as the path segment in a URL. When a visitor navigates to that URL, the application queries the CMS for the document whose slug matches, then renders it. This decouples your URL structure from your database IDs and gives content editors full control over URLs.

How Slug-Based Routing Works

At its core, slug-based routing involves three steps:

1. A content editor creates a document in the CMS and assigns it a slug (e.g., my-first-post).
2. The front-end framework creates a dynamic route that captures the slug from the URL (e.g., /posts/[slug] in Next.js).
3. When the route is hit, the application queries the CMS using the slug value and renders the returned document.

Setting Up Slugs in Sanity

In Sanity, a slug is a first-class field type. You define it in your schema like this:

// schemas/post.js
export default {
  name: 'post',
  type: 'document',
  fields: [
    {
      name: 'title',
      type: 'string',
      title: 'Title',
    },
    {
      name: 'slug',
      type: 'slug',
      title: 'Slug',
      options: {
        source: 'title',       // auto-generate from title
        maxLength: 96,
      },
      validation: (Rule) => Rule.required(),
    },
    // ... other fields
  ],
}

The source: 'title' option tells Sanity to auto-generate the slug from the title field when the editor clicks the "Generate" button. The slug is stored as an object with a current property: { _type: 'slug', current: 'my-first-post' }.

Querying by Slug with GROQ

GROQ (Graph-Relational Object Queries) is Sanity's query language. To fetch a single document by its slug, you filter on slug.current and take the first result with [0]:

// Fetch a single post by slug
*[_type == "post" && slug.current == $slug][0] {
  _id,
  title,
  slug,
  publishedAt,
  body,
  "author": author->{ name, image }
}

The $slug is a parameterized value you pass at query time, which prevents injection attacks and enables query caching. The [0] at the end returns a single object instead of an array — if no document matches, it returns null.

Dynamic Routes in Next.js App Router

In the Next.js App Router, dynamic routes are created by wrapping a folder name in square brackets. For a blog post route at /posts/[slug], create the file app/posts/[slug]/page.tsx:

// app/posts/[slug]/page.tsx
import { notFound } from 'next/navigation'
import { client } from '@/sanity/client'

const POST_QUERY = `
  *[_type == "post" && slug.current == $slug][0] {
    _id,
    title,
    slug,
    publishedAt,
    body
  }
`

const ALL_SLUGS_QUERY = `
  *[_type == "post" && defined(slug.current)] {
    "slug": slug.current
  }
`

// Generate static paths at build time
export async function generateStaticParams() {
  const posts = await client.fetch(ALL_SLUGS_QUERY)
  return posts.map((post: { slug: string }) => ({
    slug: post.slug,
  }))
}

// Render the page
export default async function PostPage({
  params,
}: {
  params: { slug: string }
}) {
  const post = await client.fetch(POST_QUERY, { slug: params.slug })

  // Return 404 if no document matches the slug
  if (!post) {
    notFound()
  }

  return (
    <article>
      <h1>{post.title}</h1>
      <p>{new Date(post.publishedAt).toLocaleDateString()}</p>
      {/* Render body content here */}
    </article>
  )
}

Static Generation vs. Server-Side Rendering

You have two primary rendering strategies for slug-based routes:

Static Generation (Recommended for most content)

Use generateStaticParams to pre-render all known slug paths at build time. Pages are served as static HTML — fast, cacheable, and CDN-friendly. This is ideal for blog posts, documentation, and marketing pages that don't change frequently.

Server-Side Rendering (For frequently updated content)

Omit generateStaticParams and Next.js will render the page on each request. This ensures content is always fresh but adds latency. Use this for user-specific pages or content that changes multiple times per day.

On-Demand Revalidation with Sanity Webhooks

The best of both worlds is static generation combined with on-demand revalidation. When a content editor publishes a change in Sanity, a webhook fires and triggers Next.js to regenerate only the affected page — no full rebuild required.

// app/api/revalidate/route.ts
import { revalidatePath } from 'next/cache'
import { type NextRequest, NextResponse } from 'next/server'

export async function POST(req: NextRequest) {
  const secret = req.nextUrl.searchParams.get('secret')

  // Validate the secret to prevent unauthorized revalidation
  if (secret !== process.env.REVALIDATION_SECRET) {
    return NextResponse.json({ message: 'Invalid secret' }, { status: 401 })
  }

  const body = await req.json()
  const slug = body?.result?.slug?.current

  if (!slug) {
    return NextResponse.json({ message: 'No slug found' }, { status: 400 })
  }

  // Revalidate the specific post page
  revalidatePath(`/posts/${slug}`)

  return NextResponse.json({ revalidated: true, slug })
}

Configure a Sanity webhook to POST to this endpoint whenever a document of type post is created, updated, or deleted. This keeps your static pages fresh without sacrificing performance.

Handling 404s Gracefully

When a slug doesn't match any document, your GROQ query returns null. Always check for this and call Next.js's notFound() to render your custom 404 page. You can also add dynamicParams: false to your page to automatically 404 any slug not returned by generateStaticParams, which is useful for preventing crawlers from hitting non-existent paths.