DEV Community: Nayan Kyada

How I wire Sanity CMS multilingual content to Next.js with next-intl

Nayan Kyada — Tue, 09 Jun 2026 08:06:52 +0000

Sanity CMS multilingual support with next-intl in the Next.js App Router is one of those setups where each piece works fine in isolation but the wiring between them is fiddly. This post documents exactly how I connect the two on production projects: schema design, GROQ query patterns per locale, and the slug uniqueness trap that bites every team at least once.

What each tool is actually responsible for

Before touching code, get the responsibilities straight. Sanity's document internationalisation plugin handles content storage — it creates one document per locale with a shared _id prefix (e.g. page.en, page.fr). next-intl handles routing and message delivery — locale segments in the URL, useTranslations, and the [locale] dynamic segment. Neither tool knows about the other by default. Your job is the bridge layer.

Schema design for translated fields

Install the plugin first:

npm i @sanity/document-internationalization

Then configure it in sanity.config.ts:

// sanity.config.ts
import { defineConfig } from 'sanity'
import { documentInternationalization } from '@sanity/document-internationalization'

export default defineConfig({
  // ...project, dataset, plugins you already have
  plugins: [
    documentInternationalization({
      supportedLanguages: [
        { id: 'en', title: 'English' },
        { id: 'fr', title: 'French' },
        { id: 'de', title: 'German' },
      ],
      schemaTypes: ['page', 'post'],
    }),
  ],
})

Now design your schema. Keep language-neutral fields (like category references or publish date) on a shared document type, and put all translatable fields on the locale document.

// schemas/post.ts
import { defineType, defineField } from 'sanity'

export const post = defineType({
  name: 'post',
  title: 'Post',
  type: 'document',
  fields: [
    defineField({
      name: 'language',
      type: 'string',
      readOnly: true,
      hidden: true,
    }),
    defineField({
      name: 'slug',
      type: 'slug',
      // Critical: scope uniqueness to language — see pitfalls section
      options: {
        source: 'title',
        isUnique: async (slug, context) => {
          const { document, getClient } = context
          const client = getClient({ apiVersion: '2024-01-01' })
          const id = document._id.replace(/^drafts\./, '')
          const params = { draft: `drafts.${id}`, published: id, language: document.language, slug }
          const query = `!defined(*[!(_id in [$draft, $published]) && language == $language && slug.current == $slug][0]._id)`
          return await client.fetch(query, params)
        },
      },
    }),
    defineField({ name: 'title', type: 'string' }),
    defineField({ name: 'body', type: 'array', of: [{ type: 'block' }] }),
  ],
})

The plugin injects the language field automatically after you register it in schemaTypes, but I define it explicitly anyway so TypeGen picks it up without surprises.

GROQ query patterns for locale

With document internationalisation, each locale document has the language embedded. Query pattern is straightforward — always filter by language:

// Fetch a single post by slug and locale
*[
  _type == "post"
  && language == $locale
  && slug.current == $slug
  && !(_id in path("drafts.**"))
][0] {
  _id,
  title,
  slug,
  language,
  body[]
}

For listing pages where you need alternate-locale URLs (canonical alternates for SEO hreflang), fetch all language variants via the _translations metadata reference the plugin adds:

// Get all locale versions of a document to build hreflang
*[
  _type == "translation.metadata"
  && references($id)
][0] {
  translations[]-> {
    language,
    slug
  }
}

That second query is what I use to build the alternates.languages object in Next.js metadata.

Wiring to next-intl in the App Router

Assume you already have next-intl set up with the [locale] segment under app/[locale]/. The integration point is the route handler that fetches Sanity content — pass the locale segment directly into GROQ.

// app/[locale]/blog/[slug]/page.tsx
import { getTranslations } from 'next-intl/server'
import { client } from '@/sanity/client'
import type { Metadata } from 'next'

interface Props {
  params: Promise<{ locale: string; slug: string }>
}

const postQuery = `
  *[
    _type == "post"
    && language == $locale
    && slug.current == $slug
    && !(_id in path("drafts.**"))
  ][0] {
    _id,
    title,
    slug,
    language,
    body[]
  }
`

const translationsQuery = `
  *[
    _type == "translation.metadata"
    && references($id)
  ][0] {
    translations[]-> {
      language,
      "slug": slug.current
    }
  }
`

export async function generateMetadata({ params }: Props): Promise<Metadata> {
  const { locale, slug } = await params
  const post = await client.fetch(postQuery, { locale, slug })
  if (!post) return {}

  const meta = await client.fetch(translationsQuery, { id: post._id })
  const languages: Record<string, string> = {}
  for (const t of meta?.translations ?? []) {
    languages[t.language] = `/${t.language}/blog/${t.slug}`
  }

  return {
    title: post.title,
    alternates: { languages },
  }
}

export default async function PostPage({ params }: Props) {
  const { locale, slug } = await params
  const t = await getTranslations({ locale, namespace: 'Blog' })
  const post = await client.fetch(postQuery, { locale, slug })
  if (!post) return <p>{t('notFound')}</p>

  return (
    <article>
      <h1>{post.title}</h1>
      {/* render body with Portable Text */}
    </article>
  )
}

The key line is language == $locale in GROQ. $locale comes from the URL segment — next-intl validates it against your locales config in i18n/routing.ts before the route even renders, so you will never receive an invalid value here.

The slug uniqueness pitfall

This is the one that causes silent bugs. By default Sanity's slug uniqueness check queries across all documents of that type, ignoring language. So /en/blog/welcome and /fr/blog/welcome are both valid — same slug, different locale documents. But if an editor accidentally creates a French post with an English slug and then an English post with the same value, the default validator blocks the second one.

The custom isUnique function in the schema above scopes the uniqueness check to language. That means slugs must be unique within a locale, not globally. That is usually correct — you want /en/blog/bienvenue and /fr/blog/bienvenue to be independent.

If your design requires the same slug across locales (so the URL path is identical for every language and only the locale prefix changes), add an explicit validation rule to enforce matching slugs across translations. I rarely do this because it breaks editorial flexibility, but it is a valid pattern for highly structured content.

One more trap: generateStaticParams must loop over all locales and call Sanity for each, otherwise builds silently skip locale variants:

// app/[locale]/blog/[slug]/page.tsx (continued)
export async function generateStaticParams() {
  const locales = ['en', 'fr', 'de']
  const allParams: { locale: string; slug: string }[] = []

  for (const locale of locales) {
    const slugs = await client.fetch<{ slug: string }[]>(
      `*[_type == "post" && language == $locale && defined(slug.current)]{ "slug": slug.current }`,
      { locale }
    )
    for (const { slug } of slugs) {
      allParams.push({ locale, slug })
    }
  }

  return allParams
}

Skipping this results in all locale pages being server-rendered on first request with no static fallback, which silently degrades performance without throwing any errors.

Fallback content strategy

When a translation does not exist yet, decide early: 404, redirect to the default locale, or show the default locale content with a banner. I default to a 404 via notFound() because it prevents thin-content indexation. The GROQ query returns null if no document exists for that locale + slug combination, and a null check at the top of the page component calls notFound(). Simple, safe, and does not require any extra query logic.

How I build a custom Sanity document actions publishing workflow

Nayan Kyada — Mon, 08 Jun 2026 09:11:44 +0000

Sanity's default publish button works fine for simple sites. The moment you have a team — editors, legal reviewers, marketing leads — the default action becomes a liability. Anyone can publish anything, instantly, with no record of who approved what. Custom Sanity document actions are how you fix that.

This post covers three patterns I've shipped on real projects: an approval gate that blocks publish until a reviewer signs off, a Slack notification on publish, and a scheduled release trigger using the Sanity Releases API. All three share the same plugin shape, so once you understand one, the others fall into place.

How document actions work in Sanity Studio

Document actions are React components returned from a plugin that plugs into config.document.actions. Each action receives a DocumentActionProps object — document ID, type, current draft, published state — and returns an object describing a button label, optional dialog, and onHandle callback.

You register them in sanity.config.ts:

// sanity.config.ts
import { defineConfig } from 'sanity'
import { approvalAction } from './plugins/approvalAction'
import { slackPublishAction } from './plugins/slackPublishAction'

export default defineConfig({
  // ...projectId, dataset, schema
  document: {
    actions: (prev, context) => {
      if (context.schemaType !== 'article') return prev
      // Replace the default PublishAction with your own, keep the rest
      return prev.map((action) =>
        action.action === 'publish' ? approvalAction : action
      ).concat(slackPublishAction)
    },
  },
})

The prev array contains Sanity's built-in actions — publish, unpublish, delete, duplicate. You can replace, wrap, or append.

Pattern 1: approval gate before publish

The goal: editors click "Request approval", which sets a metadata field on the document. Only users in a reviewer role see the real publish button — everyone else sees a disabled state.

I store approval state in the document itself using a _approvalStatus field (a string field hidden from the default form via hidden: () => true). The action reads it from the current draft, then either shows "Request approval" or the real publish trigger.

// plugins/approvalAction.ts
import { useCurrentUser, useDocumentOperation } from 'sanity'
import type { DocumentActionComponent, DocumentActionProps } from 'sanity'

export const approvalAction: DocumentActionComponent = (
  props: DocumentActionProps
) => {
  const { id, type, draft, published } = props
  const { patch, publish } = useDocumentOperation(id, type)
  const user = useCurrentUser()

  const isReviewer = user?.roles?.some((r) => r.name === 'reviewer')
  const approvalStatus = (draft ?? published)?._approvalStatus as
    | string
    | undefined
  const isApproved = approvalStatus === 'approved'

  if (isReviewer && isApproved) {
    return {
      label: 'Publish (approved)',
      tone: 'positive',
      onHandle: () => {
        patch.execute([{ set: { _approvalStatus: 'published' } }])
        publish.execute()
        props.onComplete()
      },
    }
  }

  if (isReviewer && !isApproved) {
    return {
      label: 'Approve',
      tone: 'caution',
      onHandle: () => {
        patch.execute([{ set: { _approvalStatus: 'approved' } }])
        props.onComplete()
      },
    }
  }

  // Editor path
  return {
    label: approvalStatus === 'approved' ? 'Awaiting publish' : 'Request approval',
    disabled: approvalStatus === 'approved',
    tone: 'default',
    onHandle: () => {
      patch.execute([{ set: { _approvalStatus: 'pending' } }])
      props.onComplete()
    },
  }
}

A few things worth noting. useDocumentOperation gives you patch and publish as separate operations — you can sequence them. useCurrentUser is safe to call in a document action because Studio already hydrates auth before actions render. The roles array reflects the roles you've configured in manage.sanity.io.

Pattern 2: Slack notification on publish

I do this via a thin Sanity Studio action that calls a Next.js route handler (or any HTTPS endpoint) right after publish.execute(). The route handler sends to Slack's incoming webhook URL stored in an environment variable, so the token never lives in the Studio bundle.

The action itself is simple — wrap the existing PublishAction rather than replace it:

// plugins/slackPublishAction.ts
import { useDocumentOperation, useClient } from 'sanity'
import type { DocumentActionComponent, DocumentActionProps } from 'sanity'

export const slackPublishAction: DocumentActionComponent = (
  props: DocumentActionProps
) => {
  const { id, type, draft } = props
  const { publish } = useDocumentOperation(id, type)

  return {
    label: 'Publish + notify Slack',
    tone: 'positive',
    disabled: publish.disabled,
    onHandle: async () => {
      publish.execute()
      try {
        await fetch('/api/notify-publish', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({
            documentId: id,
            type,
            title: (draft as { title?: string } | null)?.title ?? 'Untitled',
          }),
        })
      } catch (err) {
        console.error('Slack notify failed', err)
      }
      props.onComplete()
    },
  }
}

The /api/notify-publish route handler on the Next.js side validates a shared secret in the Authorization header, then calls Slack's webhook. Keeping the webhook URL server-side means it doesn't leak through the Studio bundle, which is public.

Pattern 3: scheduled release via the Sanity Releases API

Sanity's content releases API (available on Growth and Enterprise plans as of 2026) lets you bundle documents into a named release and schedule it for a future publish date. You can trigger this from a custom action rather than the Releases panel.

The key call is POST /v2021-06-07/releases to create a release, then PUT the document into it via the releases mutation API. I expose a dialog in the action to let the editor pick a date:

// plugins/scheduleReleaseAction.ts
import { useState } from 'react'
import { useClient } from 'sanity'
import type { DocumentActionComponent, DocumentActionProps } from 'sanity'

export const scheduleReleaseAction: DocumentActionComponent = (
  props: DocumentActionProps
) => {
  const { id, type, draft } = props
  const client = useClient({ apiVersion: '2024-05-23' })
  const [dialogOpen, setDialogOpen] = useState(false)
  const [publishAt, setPublishAt] = useState('')

  return {
    label: 'Schedule release',
    tone: 'default',
    dialog: dialogOpen && {
      type: 'dialog',
      header: 'Schedule this document',
      content: (
        <div style={{ padding: '1rem' }}>
          <input
            type="datetime-local"
            value={publishAt}
            onChange={(e) => setPublishAt(e.target.value)}
          />
          <button
            onClick={async () => {
              const releaseId = `scheduled-${id}-${Date.now()}`
              // 1. Create the release
              await client.request({
                url: `/releases`,
                method: 'PUT',
                body: {
                  id: releaseId,
                  metadata: {
                    title: `Scheduled: ${(draft as { title?: string } | null)?.title ?? id}`,
                    releaseType: 'scheduled',
                    intendedPublishAt: new Date(publishAt).toISOString(),
                  },
                },
              })
              // 2. Add the document to the release
              await client.request({
                url: `/data/mutate/${client.config().dataset}`,
                method: 'POST',
                body: {
                  mutations: [{
                    createOrReplace: {
                      ...(draft as object),
                      _id: `versions.${releaseId}.${id}`,
                    },
                  }],
                },
              })
              setDialogOpen(false)
              props.onComplete()
            }}
          >
            Schedule
          </button>
        </div>
      ),
    },
    onHandle: () => setDialogOpen(true),
  }
}

The versions.{releaseId}.{documentId} ID convention is how Sanity's releases system identifies document versions — using the wrong prefix will silently create a loose document instead of a release member, so get that string right.

Wiring up roles and access control

Custom actions are only as secure as your Sanity role configuration. An action can check useCurrentUser client-side, but a determined editor can still call the Sanity API directly. For hard enforcement — especially on the approval gate — back it up with a Sanity access control rule or a webhook that validates _approvalStatus before indexing in your front-end.

For most agency projects the client-side check is good enough: editors aren't adversarial, they just need guardrails. For regulated industries (legal, pharma, finance), add a server-side check in your revalidation webhook that refuses to push a document live if _approvalStatus !== 'approved'.

What I'd change in hindsight

The approval status field living inside the document schema pollutes your content model. A cleaner approach — which Sanity's own review features lean toward — is a separate reviewRequest document that references the content document. That keeps editorial state out of content state. I've done it both ways and the separate document model wins for anything beyond a two-person team.

How I write advanced GROQ queries with joins, coalesce, and array flattening in Sanity

Nayan Kyada — Sun, 07 Jun 2026 08:06:38 +0000

Advanced GROQ queries in Sanity go well beyond *[_type == "post"]. Once you're pulling real content graphs — references across multiple document types, optional fields, nested arrays — naive queries balloon payloads and hurt RSC render times. Here's how I handle the patterns that come up most in production.

Why payload size actually matters in groq advanced queries and joins in Sanity

Every byte GROQ returns travels from Sanity's CDN to your Next.js server, gets deserialized, and then (in RSC) is serialized again into the RSC payload sent to the browser. I instrument every query with console.time / console.timeEnd during development and log the stringified response size:

// lib/sanity/query-debug.ts
export async function timedFetch<T>(queryFn: () => Promise<T>, label: string): Promise<T> {
  console.time(label);
  const result = await queryFn();
  const bytes = new TextEncoder().encode(JSON.stringify(result)).length;
  console.timeEnd(label);
  console.log(`[${label}] payload: ${(bytes / 1024).toFixed(1)} kB`);
  return result;
}

With that wrapper in place I can compare before/after on every query I refactor. Numbers below come from a real e-commerce content site with ~4 000 documents.

Inline joins: resolving references without separate round-trips

Sanity references are stored as {_ref: "doc-id"}. GROQ can dereference them inline using ->, avoiding the N+1 pattern you'd get by fetching references separately in TypeScript.

This query fetches blog posts and resolves their author and category references in one round-trip:

// Before — naive, 41 kB payload
*[_type == "post" && defined(slug)] {
  _id,
  title,
  slug,
  author,
  category
}

// After — inline join with projection, 8.3 kB payload
*[_type == "post" && defined(slug)] | order(publishedAt desc) [0..19] {
  _id,
  title,
  "slug": slug.current,
  "author": author-> {
    name,
    "avatar": image.asset->url
  },
  "category": category-> {
    title,
    "slug": slug.current
  },
  publishedAt
}

The naive version sent every field on every document including Portable Text blocks, image asset metadata, and internal Sanity fields. Projecting explicitly and dereferencing inline cut the payload from 41 kB to 8.3 kB — 80% reduction for a list of 20 posts.

For deeply nested references (e.g., a post → author → company), chain -> twice:

"company": author->company-> { name, website }

Sanity resolves this in the same query; there's no extra HTTP call.

coalesce: graceful fallbacks across optional fields

coalesce() returns the first non-null value in its argument list. I use it constantly for multi-locale fallbacks and optional overrides.

// pages/[slug] query — 12 kB payload
*[_type == "page" && slug.current == $slug][0] {
  _id,
  // Prefer SEO title override; fall back to main title
  "title": coalesce(seo.title, title),
  // Prefer SEO description; fall back to excerpt; fall back to empty string
  "description": coalesce(seo.description, excerpt, ""),
  // Prefer hero image; fall back to author avatar
  "heroImage": coalesce(
    heroImage.asset->url,
    author->image.asset->url
  ),
  "publishedAt": coalesce(publishedAt, _createdAt)
}

Without coalesce I'd handle these fallbacks in TypeScript with ?? chains — which works, but means sending both fields over the wire even when only one is needed. coalesce evaluates server-side so you get one field back, not two.

Array flattening with `[]` and `array::unique`

When documents contain arrays of references — a curated homepage with multiple section blocks each containing an array of post references — you end up with a nested array structure that's awkward to work with in React.

// sections[]->posts[]->slug gives you [[slug1,slug2],[slug3]] — nested
// Flatten with array notation
*[_type == "homepage"][0] {
  "allPostSlugs": sections[].posts[]->slug.current
}

Groq automatically flattens sections[].posts[] into a single array. Combine with array::unique to deduplicate:

*[_type == "homepage"][0] {
  "featuredTags": array::unique(sections[].posts[]->tags[]->title)
}

Payload comparison on a homepage with 6 sections × 8 posts × 4 tags each: nested structure was 9.1 kB after JSON serialization; flattened unique array was 0.4 kB.

Conditional projections based on document subtype

Some schemas use a _type discriminator inside an array — think a blocks array that can hold textBlock, videoBlock, or ctaBlock. You want different fields for each type without fetching everything.

// components/[slug] page query
*[_type == "landingPage" && slug.current == $slug][0] {
  _id,
  title,
  "blocks": blocks[] {
    _type,
    _key,
    // Only on textBlock
    _type == "textBlock" => {
      "content": body[]
    },
    // Only on videoBlock
    _type == "videoBlock" => {
      "playbackId": muxVideo.asset->playbackId,
      caption
    },
    // Only on ctaBlock
    _type == "ctaBlock" => {
      heading,
      "href": link.url,
      label
    }
  }
}

The _type == "videoBlock" => { ... } syntax is a GROQ conditional projection. Fields inside only appear on matching items — the response for a textBlock item won't include playbackId at all. On a landing page with 12 mixed blocks, this pattern reduced the blocks payload from 22 kB to 6.4 kB compared to projecting all fields on every block.

Combining everything: a realistic product page query

Here's a composite query I use on a product detail page that combines joins, coalesce, conditional projections, and flattening:

// groq/product-page.groq — measured at 14.2 kB for a product with 3 variants, 6 related
*[_type == "product" && slug.current == $slug][0] {
  _id,
  "title": coalesce(seo.title, name),
  "description": coalesce(seo.description, shortDescription, ""),
  "slug": slug.current,
  "brand": brand-> { name, "logo": logo.asset->url },
  "images": images[].asset-> {
    _id,
    url,
    "lqip": metadata.lqip,
    "dimensions": metadata.dimensions
  },
  "variants": variants[] {
    _key,
    sku,
    price,
    "label": coalesce(label, sku),
    inStock
  },
  "relatedProducts": relatedProducts[0..5]-> {
    _id,
    name,
    "slug": slug.current,
    price,
    "thumbnail": images[0].asset-> {
      url,
      "lqip": metadata.lqip
    }
  },
  "allCategories": array::unique(categories[]->title)
}

A naive *[_type == "product"][0] on this same document returns 89 kB — every variant history, all draft metadata, full Portable Text for the long description. The shaped query above returns 14.2 kB and contains exactly what the page component needs.

A note on GROQ vs client-side filtering

I've seen teams fetch broad queries and filter/transform in TypeScript. It works at small scale but means your server component waits for more bytes than necessary, and you're paying Sanity's CDN egress on data you throw away. Push all filtering, projection, and aggregation into GROQ — that's what it's for. The CDN cache key is the query + params, so a tighter query is also a more cacheable query.

The pattern I follow: write the TypeScript type first (what does the component actually need?), then write a GROQ query that produces exactly that shape. If you're using Sanity TypeGen, the generated types will enforce the match at compile time — a useful double-check that your projection isn't sneaking in extra fields.

Next.js partial prerendering PPR in production: what actually works

Nayan Kyada — Sat, 06 Jun 2026 07:30:05 +0000

Next.js partial prerendering (PPR) is the most interesting rendering primitive the framework has shipped in years. The pitch is simple: render a static shell at build time, stream dynamic holes at request time. In production, though, the story has more friction than the docs let on.

What PPR actually solves

The problem PPR targets is real. Before PPR, you had an ugly fork in the road: either mark the entire route dynamic = 'force-dynamic' and lose every caching benefit, or commit to fully static and hack around personalized content with client-side fetches that tank your LCP.

PPR dissolves that fork. The HTML shell — nav, hero, structured content — ships from the edge cache in under 50 ms. <Suspense> boundaries containing dynamic content (cart count, user greeting, live stock level) resolve server-side and stream in milliseconds later. The browser paints something useful immediately, then progressively fills in the rest.

For pages that are 80% static and 20% personalized, this is the right model. Marketing landing pages with a logged-in nav, product detail pages with live inventory, blog posts with a recommended-articles widget — all fit naturally.

Enabling PPR and what changes in your data fetching

As of Next.js 15, PPR is still opt-in per layout or page:

// app/products/[slug]/page.tsx
export const experimental_ppr = true;

export default async function ProductPage({ params }: { params: { slug: string } }) {
  // This fetch runs at build/revalidation time — static shell
  const product = await getProduct(params.slug);

  return (
    <main>
      <ProductHero product={product} />
      {/* Dynamic boundary — resolves at request time */}
      <Suspense fallback={<InventorySkeletonUI />}>
        <LiveInventory productId={product._id} />
      </Suspense>
    </main>
  );
}

The catch is inside LiveInventory. Any fetch() call there must opt out of caching explicitly, otherwise Next.js may still treat it as static:

// app/products/[slug]/_components/LiveInventory.tsx
import { connection } from 'next/server';

export async function LiveInventory({ productId }: { productId: string }) {
  // Signals to Next.js: this component runs at request time
  await connection();

  const res = await fetch(`https://inventory-api.example.com/stock/${productId}`, {
    cache: 'no-store',
  });
  const { available } = await res.json();

  return <span>{available} in stock</span>;
}

connection() is the explicit signal that replaces the older cookies() / headers() trick for opting a component into dynamic rendering. Without it, if your fetch has any cache hit, Next.js may hoist the component into the static shell — and you'll silently serve stale personalized data.

Where PPR breaks down in production

Fallback quality matters enormously. The static shell is what users see first. If your Suspense fallback is a raw blank div, CLS will spike when dynamic content streams in. You need accurate skeleton dimensions — ideally matching the known content size from your static data. For Sanity-powered content where image dimensions are in the query response, this is tractable. For unknown user data it's harder.

Cold starts on edge functions still bite you. The dynamic portions run as edge functions. If your origin — a Sanity CDN query, an inventory API — isn't also edge-fast, the streaming advantage shrinks. I've seen pages where the static shell renders in 40 ms but the dynamic stream takes 800 ms because the downstream API isn't geographically close. PPR didn't help; it just moved the latency into a loading spinner.

Not all Suspense boundaries are PPR boundaries. This tripped me up early. Client components wrapped in Suspense are still client-side only. PPR only applies when the component inside Suspense is a Server Component that calls connection() or uses dynamic APIs. If you drop a client component in there expecting server-side streaming, you get CSR — same as before, just with extra routing ceremony.

Route segment config conflicts. If any parent layout sets dynamic = 'force-dynamic', PPR is silently disabled for that subtree. I spent an afternoon debugging why a page wasn't getting the PPR treatment only to find a middleware-adjacent layout with a leftover force-dynamic from six months earlier. The framework gives you no warning.

Page patterns that benefit most

I'd use PPR on these patterns without hesitation:

Long-form content pages (blog, docs, product details) where 90% of the HTML is static and you have one or two personalized widgets bolted on.
Category / listing pages where filters and facets are URL-driven (static) but cart state or "saved" indicators are user-specific.
Homepage with a CMS hero — the content block is fully static from Sanity, but a promotional banner keyed to the user's region streams in dynamically.

I'd avoid PPR, or approach it carefully, on:

Fully personalized dashboards where less than 30% of the page is static. The overhead of splitting isn't worth it; just use dynamic rendering end to end.
Pages where accurate fallback skeletons are impossible — if you don't know the shape of the content, your CLS will get worse, not better.
Any route where a parent layout is already dynamic — until Next.js gives clearer conflict warnings, the debugging cost is too high.

My honest take

PPR is a good idea that isn't fully baked yet in the production tooling. The rendering model is correct. The developer experience — diagnosing why a component ended up static versus dynamic, debugging silent config conflicts, reasoning about connection() versus cookies() — still requires too much tribal knowledge.

If you're building a Sanity-powered marketing site, the shell-plus-dynamic model maps well onto how Sanity content is structured: structured document fields go in the static shell, real-time or user-specific widgets go behind Suspense. For that use case I'd adopt PPR today. For anything with more complex dynamism, I'd wait until the observability tooling catches up.

How I use @next/bundle-analyzer to find and fix Next.js bundle size bloat

Nayan Kyada — Fri, 05 Jun 2026 08:29:43 +0000

Next.js bundle size analysis is one of those tasks that feels optional until your Lighthouse score tanks and a client asks why the page takes four seconds to load. This post walks through the exact process I used on a recent content site: installing @next/bundle-analyzer, reading the treemap output, and cutting 210 kB from the client bundle in an afternoon.

Setting up @next/bundle-analyzer

Install the package and wrap your Next.js config:

// next.config.ts
import type { NextConfig } from 'next'
import bundleAnalyzer from '@next/bundle-analyzer'

const withBundleAnalyzer = bundleAnalyzer({
  enabled: process.env.ANALYZE === 'true',
  openAnalyzer: true,
})

const nextConfig: NextConfig = {
  // your existing config
}

export default withBundleAnalyzer(nextConfig)

Run the analysis with:

ANALYZE=true next build

This opens two HTML treemaps in your browser: one for the client bundle, one for the server bundle. The client treemap is almost always where the problem lives.

Reading the treemap output

The treemap groups chunks by size. Bigger rectangle = more bytes in the client bundle. The first thing I look at is whether I can see node_modules chunks that are larger than my own application code. On the project in question, I immediately spotted three problems.

Problem 1 — date-fns fully included (47 kB). The codebase imported format and parseISO from date-fns/index.js rather than the subpath exports. Webpack bundled the entire library.

Problem 2 — lucide-react barrel import (89 kB). A UI component file had import { Calendar, Clock, ChevronDown, ... } from 'lucide-react'. That barrel import forced the bundler to include every icon in the package — 1,000+ icons the app did not need.

Problem 3 — unsplit vendor chunk with @radix-ui/react-dialog and @radix-ui/react-popover (74 kB combined). Both components were imported in a layout that wrapped every page, so they were never code-split — they landed in the main client chunk alongside first-paint code.

Total before: ~412 kB first-load JS (gzipped: 118 kB). Target: under 200 kB gzipped.

Fix 1: subpath imports for date-fns

The fix is a one-line change per import site:

// Before (pulls in full date-fns barrel)
import { format, parseISO } from 'date-fns'

// After (subpath imports — only these two functions bundled)
import { format } from 'date-fns/format'
import { parseISO } from 'date-fns/parseISO'

If you have many files, an ESLint rule like no-restricted-imports can enforce subpath imports across the codebase. After this change the date-fns contribution to the client chunk dropped from 47 kB to 3.1 kB.

Fix 2: individual icon imports from lucide-react

Lucide ships individual modules under lucide-react/dist/esm/icons/. Import from there directly:

// Before — barrel import, bundles every icon
import { Calendar, Clock, ChevronDown } from 'lucide-react'

// After — individual imports
import Calendar from 'lucide-react/dist/esm/icons/calendar'
import Clock from 'lucide-react/dist/esm/icons/clock'
import ChevronDown from 'lucide-react/dist/esm/icons/chevron-down'

If this pattern is too verbose across a large codebase, create a thin re-export file at src/components/icons/index.ts that centralises the individual imports. That way call sites keep the same import shape and you fix the barrel in one place.

After switching: 89 kB → 7.4 kB. The three icons the app actually used weigh about 2.5 kB each.

Fix 3: lazy-load Radix primitives that are not on the critical path

The dialog and popover were used in a header navigation component that appeared on every page — but neither is visible on first paint. Wrapping them in dynamic with ssr: false moves them out of the main chunk:

// src/components/nav/search-dialog.tsx
import dynamic from 'next/dynamic'

const SearchDialog = dynamic(
  () => import('@/components/nav/search-dialog-inner'),
  { ssr: false, loading: () => null }
)

export default SearchDialog

The search-dialog-inner file contains the Radix Dialog import and everything that depends on it. Next.js now splits this into a separate chunk that only loads when the component is first rendered — which for most users means after the first user interaction.

The Radix chunk (74 kB combined) moved entirely out of the main bundle. It still loads, but lazily, and it no longer blocks the initial parse.

Before and after numbers

Metric	Before	After	Delta
First-load JS (raw)	412 kB	201 kB	−211 kB
First-load JS (gzip)	118 kB	58 kB	−60 kB
LCP (mobile, Slow 4G)	4.1 s	2.6 s	−1.5 s
Lighthouse Performance	61	84	+23 pts

The LCP improvement came almost entirely from main-thread parse time dropping — the browser was spending ~400 ms parsing JavaScript that had nothing to do with the first-paint content.

What to check on every project

When I do a bundle analysis pass on a new project, I look for these signals in the treemap:

Any single node_modules rectangle larger than 30 kB that isn't a polyfill or charting library
Icon library rectangles (lucide-react, react-icons, heroicons) — they are almost always barrel-imported
Date and utility libraries (date-fns, lodash, ramda) not using subpath imports
Radix or other UI primitive libraries in the main chunk when they are not needed on first paint
Duplicate copies of React or a library (two rectangles for the same package name means a version conflict somewhere in your dependency tree)

The @next/bundle-analyzer treemap makes all of this visible in under ten minutes. Running it before every major dependency upgrade catches regressions before they reach production.

How I rotate Sanity draft mode secrets at the edge without redeploying Next.js

Nayan Kyada — Thu, 04 Jun 2026 08:38:16 +0000

Sanity draft mode preview on Next.js App Router works fine when your secret is baked into an environment variable — until a client accidentally pastes the preview URL into a Slack channel and you have to redeploy to rotate it. Vercel Edge Config solves that: you update a single key in the dashboard and the new secret is live in under a second, no rebuild required. Here is exactly how I wire it up.

Why the standard env-var approach breaks down

The Next.js docs show a route handler that reads SANITY_PREVIEW_SECRET from process.env and sets the draft-mode cookie. That works for a single developer. It breaks down in two ways on real projects:

Secret leaks are sticky. Rotating a process.env value means a new Vercel deployment, which takes 60–90 seconds even with Turbopack. During that window the old secret still works on the live deployment.
You cannot audit access. Every stakeholder shares one secret. You cannot tell which link a leaked URL came from.

Edge Config is a key-value store that is distributed to Vercel's edge network. Reads add roughly 1–2 ms of latency and require no cold start because the data is pushed to the edge ahead of the request. Updating a value takes effect globally in under a second without a deploy.

Setting up Edge Config

In the Vercel dashboard: Storage → Create → Edge Config. Add one key:

SANITY_PREVIEW_SECRET = "<random 32-char string>"

Then connect the store to your project (Settings → Integrations on the store page). Vercel injects EDGE_CONFIG as a connection string environment variable automatically.

Install the SDK:

npm install @vercel/edge-config

The preview route handler

Create app/api/preview/route.ts. This runs on the Node.js runtime by default; I keep it there rather than the edge runtime so I can use the full Next.js draftMode() API without any caveats.

// app/api/preview/route.ts
import { draftMode } from 'next/headers'
import { redirect } from 'next/navigation'
import { NextRequest, NextResponse } from 'next/server'
import { get } from '@vercel/edge-config'

export async function GET(req: NextRequest) {
  const { searchParams } = req.nextUrl
  const incomingSecret = searchParams.get('secret')
  const slug = searchParams.get('slug') ?? '/'

  // 1. Read the current secret from Edge Config — ~1-2 ms, no redeploy needed
  const validSecret = await get<string>('SANITY_PREVIEW_SECRET')

  if (!incomingSecret || incomingSecret !== validSecret) {
    return new NextResponse('Invalid preview secret', { status: 401 })
  }

  // 2. Validate the slug looks like a real path before redirecting
  if (!/^\/[a-z0-9/_-]*$/i.test(slug)) {
    return new NextResponse('Invalid slug', { status: 400 })
  }

  // 3. Enable draft mode — Next.js sets __prerender_bypass cookie (HttpOnly, SameSite=None, Secure)
  const draft = await draftMode()
  draft.enable()

  // 4. Redirect to the requested page
  redirect(slug)
}

To disable preview, add a matching disable handler:

// app/api/disable-preview/route.ts
import { draftMode } from 'next/headers'
import { redirect } from 'next/navigation'

export async function GET() {
  const draft = await draftMode()
  draft.disable()
  redirect('/')
}

Reading draft mode in a page and avoiding content leaks

This is where most implementations go wrong. If you forget the draftMode() check and unconditionally fetch from the Sanity CDN with perspective: 'previewDrafts', you will serve draft content to every visitor whenever the draft-mode cookie is absent but the GROQ query still runs the wrong perspective.

// app/[slug]/page.tsx  (simplified)
import { draftMode } from 'next/headers'
import { client } from '@/lib/sanity/client'

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

export default async function PostPage({ params }: { params: { slug: string } }) {
  const { isEnabled } = await draftMode()

  const post = await client
    .withConfig({
      // perspective switches between published CDN and draft API
      perspective: isEnabled ? 'previewDrafts' : 'published',
      // draft fetches must bypass the CDN so editors see live changes
      useCdn: !isEnabled,
      // only pass the token when actually in draft mode
      token: isEnabled ? process.env.SANITY_API_READ_TOKEN : undefined,
    })
    .fetch(query, { slug: params.slug })

  if (!post) return <div>Not found</div>

  return <article>{post.title}</article>
}

Key constraints:

perspective: 'published' + useCdn: true — fast, cached, no token needed for published content.
perspective: 'previewDrafts' + useCdn: false — bypasses CDN, hits the Sanity API directly, requires a read token scoped to draft access.
The read token (SANITY_API_READ_TOKEN) lives in Vercel environment variables, not Edge Config. It is a long-lived credential; the preview secret is what you rotate frequently.

Cookie security and same-site issues

Next.js sets the __prerender_bypass cookie with SameSite=None; Secure. This means it only works over HTTPS. Local development over http://localhost will silently fail. Fix this by either:

Using https://localhost via a tunnelling tool (ngrok, Cloudflare Tunnel), or
Running next dev --experimental-https which generates a self-signed cert automatically.

Also, the bypass cookie has no expiry by default — it persists for the browser session. If you want it to expire after, say, 2 hours for security, you cannot do that from the route handler directly (Next.js owns the cookie). The practical workaround: issue your own short-lived session cookie alongside it and check both in middleware.

Secret rotation in production

To rotate the secret: open Vercel → Storage → your Edge Config store → edit SANITY_PREVIEW_SECRET. Change the value, save. Within one second, all preview links using the old secret return 401. No deployment, no downtime for public visitors, no cache flush required.

For multi-client setups I sometimes store an array of secrets and accept any of them with a short overlap window, then remove the old one 30 minutes later. That gives editors time to finish a session after rotation without getting locked out mid-review.

Wiring Sanity Studio to the preview URL

In your Sanity Studio config, set the preview URL to point at your route handler:

// sanity.config.ts
import { defineConfig } from 'sanity'
import { presentationTool } from 'sanity/presentation'

export default defineConfig({
  // ...
  plugins: [
    presentationTool({
      previewUrl: {
        previewMode: {
          enable: '/api/preview',
        },
      },
    }),
  ],
})

The Presentation tool appends ?secret=...&slug=... automatically when editors click the eye icon, so you do not need to hard-code secrets in the Studio config.

The pattern above — Edge Config for the rotating secret, a scoped read token for the Sanity API, and a strict perspective check in every page — is the combination that keeps draft content off your public CDN while still giving editors a fast, reliable preview link they can share with stakeholders without you having to babysit deployments.

How I wire Mux video into a Next.js + Sanity CMS upload workflow

Nayan Kyada — Wed, 03 Jun 2026 09:13:36 +0000

Wiring a Mux video upload workflow into a Sanity + Next.js site sounds straightforward until you hit the details: signed URLs expiring mid-session, poster images that tank LCP, and the Mux plugin's schema colliding with your TypeGen setup. This post walks through the exact steps I use on production sites — plugin config, GROQ projection, signed URL generation in a route handler, and pulling a Mux thumbnail as a next/image source to protect LCP.

Why Mux instead of storing video in Sanity assets

Sanity's asset pipeline is built for images and files, not adaptive bitrate video. Uploading a 200 MB .mp4 directly bloats your dataset, gives you zero transcoding, and means the browser downloads the original rather than a codec-optimised stream. Mux solves all three: it transcodes on ingest, serves HLS via its own CDN, and gives you a stable asset ID you can store in Sanity as a reference object. The Sanity Mux plugin (sanity-plugin-mux-input) wraps this into a custom input component so editors upload from Studio without touching the Mux dashboard.

Installing and configuring the Mux plugin

Install the plugin and Mux's Node SDK:

npm install sanity-plugin-mux-input @mux/mux-node

Then register it in your Sanity config. The plugin needs your Mux token ID and secret — store them in Sanity's secret management so they never touch the client bundle:

// sanity.config.ts
import { defineConfig } from 'sanity'
import { muxInput } from 'sanity-plugin-mux-input'

export default defineConfig({
  name: 'default',
  projectId: process.env.NEXT_PUBLIC_SANITY_PROJECT_ID!,
  dataset: process.env.NEXT_PUBLIC_SANITY_DATASET!,
  plugins: [
    muxInput({
      mp4_support: 'standard', // enables static MP4 rendition for fallback
    }),
  ],
  schema: { types: [] },
})

The plugin reads your Mux credentials from Sanity's secrets document (it prompts on first load inside Studio). That keeps the token out of process.env on the client side.

Add a mux.video typed field to the schema for any document that needs video:

// schemas/post.ts
import { defineField, defineType } from 'sanity'

export const post = defineType({
  name: 'post',
  title: 'Post',
  type: 'document',
  fields: [
    defineField({ name: 'title', type: 'string' }),
    defineField({ name: 'slug', type: 'slug', options: { source: 'title' } }),
    defineField({
      name: 'video',
      title: 'Video',
      type: 'mux.video',
    }),
  ],
})

When an editor uploads a file, the plugin posts it to Mux via a direct upload URL (no bytes go through Sanity's servers), then writes the resulting playbackId and assetId back into the document. That stored object is what you query in GROQ.

GROQ projection for Mux video data

The mux.video type stores a nested object. Project only what you need:

// queries/post.groq (used by sanity-typegen)
*[_type == "post" && slug.current == $slug][0] {
  title,
  "video": video.asset->{
    playbackId,
    assetId,
    "status": data.status,
    "duration": data.duration,
    "aspectRatio": data.aspect_ratio
  }
}

The -> dereference follows the reference Sanity stores to the mux.videoAsset document. data.status tells you whether Mux has finished transcoding — useful for showing a placeholder in the UI before the asset is ready.

Serving signed playback URLs from a route handler

For public marketing pages you can use unsigned playback. For gated content — course lessons, client deliverables — you need signed URLs. Generate them server-side in a Next.js route handler so the signing key never reaches the browser:

// app/api/video-token/route.ts
import { NextRequest, NextResponse } from 'next/server'
import Mux from '@mux/mux-node'

const mux = new Mux({
  tokenId: process.env.MUX_TOKEN_ID!,
  tokenSecret: process.env.MUX_TOKEN_SECRET!,
})

export async function GET(req: NextRequest) {
  const playbackId = req.nextUrl.searchParams.get('playbackId')
  if (!playbackId) {
    return NextResponse.json({ error: 'Missing playbackId' }, { status: 400 })
  }

  const token = await mux.jwt.signPlaybackId(playbackId, {
    type: 'video',
    expiration: '1h',
    // Add your own auth check here before signing
  })

  // Cache the token at the edge — it's valid for 1 h
  return NextResponse.json(
    { token },
    {
      headers: {
         'Cache-Control': 'private, max-age=3300', // slightly under 1 h
      },
    }
  )
}

The client fetches this token, then appends ?token=<jwt> to the Mux stream URL passed to @mux/mux-player-react. Keep the signing key in server-only env — prefix it without NEXT_PUBLIC_.

Generating a poster image for LCP

Mux exposes a thumbnail endpoint at https://image.mux.com/{playbackId}/thumbnail.webp. You can pass time=4 to grab a frame at 4 seconds instead of frame 0 (which is often a black frame on cuts). Feed that URL directly to next/image with priority for above-the-fold video heroes:

// components/VideoHero.tsx
import Image from 'next/image'

type Props = {
  playbackId: string
  aspectRatio: string // e.g. "16:9"
  title: string
}

export function VideoHero({ playbackId, aspectRatio, title }: Props) {
  const [w, h] = aspectRatio.split(':').map(Number)
  const posterUrl = `https://image.mux.com/${playbackId}/thumbnail.webp?time=4&width=1280`

  return (
    <div style={{ aspectRatio: `${w}/${h}` }} className="relative w-full overflow-hidden">
      <Image
        src={posterUrl}
        alt={title}
        fill
        sizes="100vw"
        priority
        className="object-cover"
      />
    </div>
  )
}

Using fill with a parent that has aspect-ratio set avoids the layout shift you get when the browser doesn't know the image dimensions upfront. Because aspectRatio comes straight from the Mux asset metadata in the GROQ query, you don't have to hardcode anything — CLS stays at zero. Pass priority when the poster is the largest contentful element; omit it for below-the-fold videos.

For the actual player, swap the Image out for @mux/mux-player-react once the user interacts, or lazy-load the player component behind a dynamic import so it doesn't inflate your main bundle:

import dynamic from 'next/dynamic'
const MuxPlayer = dynamic(() => import('@mux/mux-player-react'), { ssr: false })

This keeps the initial JS payload small — the Mux player is around 50 kB gzipped — while still delivering the poster immediately via SSR.

Handling upload status in the editor

One workflow detail that trips up editors: Mux transcoding takes 10–60 seconds after upload. During that window the status field is preparing, not ready, and the playback URL 404s. I add a document-level validation rule that prevents publishing if video.asset.data.status !== 'ready':

defineField({
  name: 'video',
  type: 'mux.video',
  validation: (Rule) =>
    Rule.custom(async (value, context) => {
      if (!value?.asset?._ref) return true // optional field
      const asset = await context.getClient({ apiVersion: '2024-01-01' })
        .fetch(`*[_id == $id][0]{ "status": data.status }`, {
          id: value.asset._ref,
        })
      return asset?.status === 'ready' ? true : 'Video is still transcoding. Wait for "ready" before publishing.'
    }),
})

Editors see an inline warning rather than publishing a broken page. Once Mux webhooks fire and the asset document updates, the Studio re-validates and clears the warning automatically.

How I configure Sanity image URL auto=format with next/image to serve WebP and AVIF

Nayan Kyada — Tue, 02 Jun 2026 08:52:34 +0000

The question of who converts the image — Sanity's CDN or Next.js's image optimiser — comes up on almost every project. Get it wrong and you are double-encoding a JPEG to WebP twice, paying bandwidth twice, and caching the result under two different keys. The phrase sanity image url webp avif automatic format nextjs is exactly the decision point: one of them should own format negotiation, not both.

What `auto=format` actually does on the Sanity CDN

When you append ?auto=format to a Sanity image URL, Sanity's CDN reads the Accept header from the incoming request and returns the best format the browser supports — WebP or AVIF if available, JPEG/PNG as a fallback. The transformation is done at Imgix (which powers Sanity's asset pipeline), cached at the edge, and served with a long Cache-Control header keyed to the full URL including query parameters.

This is fast and costs nothing extra on Sanity's free or Growth plans. The CDN URL looks like this:

// lib/sanity-image-url.ts
import imageUrlBuilder from '@sanity/image-url'
import { client } from './sanity-client'

const builder = imageUrlBuilder(client)

export function urlFor(source: SanityImageSource) {
  return builder.image(source)
}

// Usage — note: NO auto=format yet
const src = urlFor(post.coverImage)
  .width(1200)
  .height(630)
  .fit('crop')
  .url()
// → https://cdn.sanity.io/images/<projectId>/<dataset>/...jpg?w=1200&h=630&fit=crop

The Accept header is what triggers format selection. A direct <img> or a fetch() from a server component will carry Accept: image/avif,image/webp,*/* in modern browsers and Chromium-based crawlers. The CDN responds with AVIF or WebP accordingly.

Why you should not combine `auto=format` with `next/image` as an external image

next/image works by proxying images through /_next/image?url=...&w=...&q=.... When Next.js receives a request to that endpoint it:

Fetches the origin URL (your Sanity CDN URL)
Runs Sharp locally (or on the Vercel image optimiser) to resize and re-encode
Serves the result with its own cache headers

If your Sanity URL already has auto=format, the /_next/image proxy fetches a WebP from Sanity, then Sharp re-encodes that WebP into another WebP (or AVIF). You have now paid for two encode passes and the quality is slightly degraded because lossy-to-lossy re-encoding accumulates artefacts. The cache key at /_next/image is the full origin URL string, so ?auto=format in that URL means every format+width combination gets its own cache entry — which is fine but pointless if Next.js is doing the format work anyway.

The fix is to pick a lane:

Lane A – let Sanity CDN do it: Use a raw <img> tag (or next/image with unoptimized), append auto=format and q=80 directly on the Sanity URL, and skip Next.js image optimisation entirely.
Lane B – let next/image do it: Strip auto=format from the Sanity URL, configure remotePatterns for cdn.sanity.io, and let Next.js handle format negotiation and resizing.

For most content sites I default to Lane B because it gives me sizes, fill, and priority props without extra plumbing, and Vercel's image cache is already warm on the same edge network. The trade-off is that every unique w value in sizes produces a separate cached variant at /_next/image.

Lane B setup: next/image without double-encoding

// next.config.ts
import type { NextConfig } from 'next'

const config: NextConfig = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'cdn.sanity.io',
        pathname: '/images/**',
      },
    ],
    // Vercel supports avif by default; on self-hosted you need Sharp >= 0.33
    formats: ['image/avif', 'image/webp'],
    // Match Sanity's default quality to avoid surprise
    quality: 80,
  },
}

export default config

// components/sanity-image.tsx
import Image from 'next/image'
import { urlFor } from '@/lib/sanity-image-url'
import type { SanityImageSource } from '@sanity/image-url/lib/types/types'

interface Props {
  image: SanityImageSource & { alt?: string }
  width: number
  height: number
  priority?: boolean
  className?: string
}

export function SanityImage({ image, width, height, priority, className }: Props) {
  // Build the Sanity URL WITHOUT auto=format and WITHOUT width/height
  // next/image owns resizing; Sanity CDN just serves the original at base quality
  const src = urlFor(image)
    .fit('max') // avoid upscaling on Sanity side
    .url()      // no .width() call here — next/image handles that

  return (
    <Image
      src={src}
      alt={image.alt ?? ''}
      width={width}
      height={height}
      priority={priority}
      className={className}
      // Sanity metadata already carries real dimensions; pass them
      // so next/image does not need to probe the origin
    />
  )
}

Notice that I am not calling .width() on the builder when passing to next/image. If you set ?w=1200 on the Sanity URL and then next/image requests ?url=...%3Fw%3D1200&w=800, Sharp will first decode a 1200-wide image and resize down to 800 — wasted decode work. Omitting the width on the Sanity side means the CDN serves the original (or near-original) and Sharp receives clean pixels.

When to use Lane A instead

Lane A (Sanity CDN owns everything, unoptimized on next/image or plain <img>) makes more sense when:

You are self-hosting Next.js without Sharp or a paid image service
The images are served from a CMS preview route where you cannot add remotePatterns (draft content domains sometimes differ)
You need auto=format&dpr=2 for high-DPI but do not want to enumerate 2x srcset entries manually

In that case, build the full URL with quality and format on the Sanity side and pass unoptimized to avoid the proxy:

// Lane A — Sanity CDN handles format, quality, and DPR
const src = urlFor(image)
  .width(800)
  .auto('format')
  .quality(80)
  .url()

// next/image with unoptimized bypasses /_next/image entirely
<Image src={src} alt={alt} width={800} height={533} unoptimized />

The Accept header is still sent because Vercel's edge (or any modern CDN in front of your Next.js origin) forwards it, and Sanity's CDN will serve AVIF or WebP as appropriate.

Cache key hygiene

One operational gotcha: if you switch between Lane A and Lane B mid-deployment, your old /_next/image cache entries (keyed on URLs with auto=format) and your new ones (keyed on URLs without it) coexist under different keys. On Vercel you can flush the image cache from the project settings. On self-hosted deployments the cache lives in .next/cache/images and is wiped by a full redeploy anyway. Make the lane decision once per project and commit it to an ADR so the next developer does not mix them.

The short rule: auto=format and next/image optimisation are both format negotiation — they are additive overhead, not complementary. Pick one, strip the other, and your payloads stay small without any double-encoding tax.

How to evaluate a Sanity CMS development services proposal before you sign

Nayan Kyada — Mon, 01 Jun 2026 09:40:11 +0000

A Sanity CMS development services proposal lands in your inbox as a PDF or Notion doc. It might look thorough, but the details that actually protect you — scope limits, staging access, payment triggers — are often buried or missing entirely. This post walks through what those details should look like, drawn from a proposal I sent to a mid-size e-commerce brand earlier this year.

What a Sanity CMS development services proposal actually covers

A proposal worth signing has five parts: scope definition, milestone plan, payment schedule, staging promise, and a change-order policy. If any of those are vague or absent, you are carrying risk the developer should own.

Here is the milestone structure from the proposal I referenced:

Milestone	Deliverable	Payment trigger	Target date
Kickoff	Signed contract, repo created, Sanity project provisioned	30% upfront invoice	Day 1
Schema draft	All document types defined, content model doc shared	Client review sign-off	Week 2
Staging live	Full site running on staging URL, editor can log in	30% progress invoice	Week 4
Content QA	Client populates real content, punch-list collected	Client sign-off on QA doc	Week 6
Production launch	DNS switched, redirects verified, Core Web Vitals baseline	40% final invoice	Week 8

Every row has a concrete deliverable, a named trigger for payment, and a target date. There is no row that says "development complete" without explaining what complete means.

The staging URL on day one — why this matters

One promise I put in every proposal is a staging URL within 24 hours of contract signing. Not a design mockup, not a Figma link — an actual URL where someone on your team can open a browser and see a running Next.js site connected to a real Sanity project.

This sounds like a small thing. It is not. It establishes that the developer has wired up the stack before, that the repo is real, and that you can verify progress at any point without scheduling a call. If a proposal does not name a staging domain and does not commit to a timeline for it, ask why.

For reference, the staging environment in that proposal ran on Vercel preview deployments, with a fixed subdomain (staging.clientbrand.com) set up via Vercel's custom domain on the preview branch. The Sanity Studio was deployed alongside it at staging.clientbrand.com/studio. On day one the client's marketing director could log into the Studio, create a test document, and see it rendered on the frontend — even though the site was empty. That single capability killed about five rounds of "how is it going?" emails.

Scope guardrails: what a good change-order policy looks like

Scope creep on a CMS build is predictable. Somebody sees the Studio and wants a new content type. A third-party integration appears that was not in the original brief. A legal team asks for a cookie consent layer three days before launch.

A good proposal names these situations explicitly and sets a handling process. The policy I use reads roughly like this:

Any work not listed in the deliverables table is out of scope.
Out-of-scope requests are estimated within 48 hours and presented as a separate line item.
The client approves or declines in writing before work begins.
Timeline extensions caused by out-of-scope additions are added to the project calendar and reflected in a revised milestone table.

What this does not say is "we will accommodate reasonable requests at no extra charge." That phrase is a trap. It sounds flexible and client-friendly, and it is the sentence that causes most freelance project disputes. If you see it in a proposal, ask for a definition of "reasonable."

Red flags to look for in a proposal

These are patterns I have seen in competing proposals clients have shared with me when asking for a second opinion:

Lump-sum deliverable with no milestones. "Build a Sanity CMS site: $12,000" with no breakdown means you have no payment leverage and no checkpoints. If the project stalls at week six, you have already paid most of it.

Hourly rate with no cap. Hourly billing on a fixed-scope CMS build transfers all estimation risk to you. A capable developer should be able to scope a standard content site to a fixed or capped price.

No mention of content migration. If your current site has hundreds of pages, ask specifically whether migrating existing content is included. It usually is not, and it is usually the most time-consuming part of the project.

Staging "available upon request." This means the developer does not have a repeatable deployment workflow. Staging should be automatic and always-on, not something you have to ask for.

Handoff described as "training available." Training your team on how to use the Studio they paid to have built should be included, not an upsell. Ask for a specific handoff session and ask whether documentation is part of the deliverable.

What to ask before you sign

Three questions cut through most proposal ambiguity:

Which items in this proposal have you delivered on a previous project, and can I see a reference or case study?
If the project runs two weeks over your estimate, what happens to the price?
Who owns the Sanity project and the Vercel account — me or you — and when is that transfer documented?

The third question matters more than most buyers realise. A developer who provisions a Sanity project under their own account and a Vercel team under their own billing creates a dependency that survives the engagement. You want those accounts in your name from day one, with the developer added as a collaborator — not the other way around.

A proposal that answers these questions clearly before you ask them is a good sign. One that requires three follow-up emails to pin down the answers is telling you something about how the project will be managed.

Sanity CMS Pricing 2026: Free Plan Limits, Growth & Enterprise

Nayan Kyada — Sun, 31 May 2026 07:56:41 +0000

Sanity CMS pricing in 2026 follows a SaaS tier model — Free, Growth, and Enterprise — and the limits that push you from one tier to the next are specific enough that you can scope a budget before writing a single line of code. This guide walks through each plan's concrete numbers, the metrics that actually trigger an upgrade, and a straightforward decision matrix by team size and traffic.

One important caveat up front: Sanity adjusts its pricing periodically. Everything below reflects publicly available information as of May 2026. Treat the numbers here as a working model for scoping, then verify the exact figures on Sanity's official pricing page before signing anything.

What the Free plan actually gives you

The Free plan is genuinely useful for small projects. It is not a crippled trial — it runs in production for low-traffic sites indefinitely. The limits that matter are:

Datasets: 2 per project (typically one production, one staging)
Non-admin users: 2 (beyond the project owner)
API CDN requests: 500,000 per month
Bandwidth: 10 GB per month
Assets stored: 20 GB

What you lose on Free is mostly around collaboration and workflow features. Scheduled publishing is not available. Role-based access control (RBAC) is limited — you get Admin and Editor, no custom roles. Sanity AI Assist, the in-studio AI writing assistant, is not included. History retention for content revisions is capped. For a solo developer running a personal site or a small brochure site with one or two editors, none of those gaps matter.

The request limit is where Free projects most commonly hit a wall. 500,000 CDN API requests sounds like a lot until you realise that a page cached for 60 seconds on a site with 10,000 monthly visitors can burn through that budget faster than expected, especially if revalidation is aggressive or preview mode is in use.

Growth plan: per-seat pricing and what you unlock

Growth is the plan most commercial projects land on. As of 2026, Growth is priced at $15 per seat per month (billed monthly) or around $12 per seat per month on an annual plan. A "seat" in Sanity's model means a non-read-only user — someone who logs into Sanity Studio and creates or edits content.

Growth increases the included usage significantly:

Datasets: 5 per project (more available as add-ons)
Non-admin users: included seats scale with your subscription
API CDN requests: 1,000,000 per month included, then metered
Bandwidth: 100 GB per month included, then metered
Assets stored: 100 GB included

Growth also unlocks the features that content teams actually care about: scheduled publishing, expanded revision history, and access to Sanity AI Assist. RBAC with custom roles is available on Growth, which matters the moment a client wants their marketing team to edit blog posts but not touch product data.

Overage pricing on Growth is metered — you pay per additional 100k API requests and per additional GB of bandwidth. These charges are real and can surprise teams that do not monitor usage. Set up usage alerts in the Sanity dashboard as soon as you move to Growth.

Enterprise: when it becomes necessary

Enterprise is not a published price — it is negotiated. You need it in specific situations:

SSO / SAML integration for organisations that require employees to log in via their identity provider
SLA guarantees beyond the standard uptime commitment
Audit logs for compliance-driven industries (healthcare, fintech, legal)
Custom data residency — if GDPR or local regulation requires data to stay in a specific region
Very high API volume where negotiated rate caps are cheaper than metered Growth overages
More than 5 datasets at scale (large agencies managing dozens of client projects under one organisation often hit this)

For most product companies under 50 content seats and without compliance requirements, Enterprise is overkill. The tell is when legal or IT starts asking questions about where data lives and who has access to audit trails.

Pricing comparison at a glance

	Free	Growth	Enterprise
Monthly price	$0	~$15/seat/mo	Custom
Datasets	2	5 (+ add-ons)	Custom
Non-admin users	2	Per seat	Custom
API CDN requests/mo	500k	1M included	Custom
Bandwidth/mo	10 GB	100 GB	Custom
Asset storage	20 GB	100 GB	Custom
Scheduled publishing	✗	✓	✓
Custom RBAC roles	✗	✓	✓
Sanity AI Assist	✗	✓	✓
SSO / SAML	✗	✗	✓
SLA / audit logs	✗	✗	✓

Which plan do you actually need

Here is a practical decision guide based on team size and traffic, not marketing copy.

Solo developer or side project: Stay on Free until you hit 500k requests or need a third editor seat. Most hobby projects and personal portfolios never leave Free.

Small startup or agency client (2–5 editors, under 50k monthly page views): Growth at 3–5 seats is typically $45–$75/month. The scheduled publishing and RBAC alone justify it if a non-technical editor is touching the CMS.

Growing product team (5–20 editors, 50k–500k monthly page views): Growth scales linearly with seats. At 10 seats you are paying around $150/month on annual billing. Monitor your API request usage — a content-heavy site with ISR revalidation on short windows can push past the 1M included requests. Either cache more aggressively or budget for overages.

Marketing-led company with frequent campaigns: If your team runs scheduled launches, A/B content variants, or requires multiple staging datasets per region, Growth at 5+ seats with dataset add-ons is the budget line. Expect $150–$300/month depending on headcount.

Enterprise or regulated industry: If SSO is a requirement from IT or audit logs are needed for compliance, there is no workaround — you need Enterprise. Start the conversation with Sanity's sales team early; procurement cycles for Enterprise contracts run 4–8 weeks.

The add-ons worth knowing about

Sanity sells a few capabilities as optional add-ons rather than baking them into tier upgrades. Sanity AI Assist is included in Growth but usage beyond a certain monthly volume may have caps. Additional datasets can be purchased on Growth if 5 is not enough. Connector integrations (Shopify sync, PIM connectors) are sometimes add-on-priced depending on the partner.

None of these are gotchas if you scope them in advance. They become surprises when a developer sets up three extra datasets for locale testing and the invoice jumps.

Scope your Sanity budget before the build starts

The practical approach is to map your project against three numbers before you start: how many content editors will need non-read-only access, how many datasets your architecture needs (at minimum: production and staging), and a rough estimate of monthly API requests based on traffic and cache TTL. Those three inputs almost always determine your tier without ambiguity.

For most commercial Next.js + Sanity projects I scope, Growth at 3–5 seats is the right starting point. Free works for prototypes and small launches. Enterprise is a specific, compliance-driven need — not a prestige tier. If you're budgeting a build and want the developer side scoped too, here's how to hire a Sanity CMS developer — I send a fixed-price proposal after a short call.

Always verify current numbers at sanity.io/pricing before finalising a client proposal or internal budget. Sanity has changed plan structures in the past and will likely do so again.

Payload CMS vs Sanity for Next.js in 2026: an honest comparison

Nayan Kyada — Sat, 30 May 2026 07:25:49 +0000

Searching for "payload cms vs sanity nextjs" usually means you are already past the "what is a headless CMS" stage and trying to make an actual decision. I have shipped more than fifteen Sanity projects in production. I have not shipped Payload in production, but I have evaluated it seriously on three client decisions in the past year — reading the source, building small prototypes, and stress-testing the query model. What follows is the comparison I wished existed when I was sitting in those evaluation calls.

The decision matrix up front

Criterion	Sanity	Payload CMS
Hosting model	Sanity-hosted "content lake" (SaaS)	Self-hosted — Postgres or MongoDB, any infra
Query language	GROQ (Sanity-proprietary)	Local API (TypeScript), REST, GraphQL
TypeScript DX	TypeGen generates types from GROQ queries	Schemas are TypeScript — types are native
Studio / editor UI	Sanity Studio v3 (React, highly customisable)	Payload Admin (Next.js App Router, code-first)
Image pipeline	Sanity CDN + image transformation URL API	Bring your own CDN; S3/Cloudflare R2 adapters
Pricing	Free tier, then $15–$99+/mo per project	Open source MIT; only infra and storage costs
Lock-in risk	GROQ + hosted data = meaningful lock-in	Low — own your DB, schema is TypeScript
Maturity for Next.js	Extensive ecosystem, 5+ years of patterns	v3 (late 2024) is solid; ecosystem younger

If you already know your constraint — data residency, SaaS budget, or team size — you can probably stop here. Otherwise, keep reading for the nuance.

Hosting model: Sanity's content lake vs Payload's self-hosted approach

Sanity stores your content in its own hosted document store. You get a CDN, real-time collaboration, and zero ops overhead in exchange for a monthly bill that scales with API usage and dataset size. For most client sites this is a fair trade — I have never had a Sanity project where infrastructure ops became a meaningful line item. But for clients in regulated industries (healthcare, fintech in certain jurisdictions) or clients with explicit data-residency requirements, the conversation stalls. Your data lives in Sanity's cloud, and you cannot move it to an EU-only data centre of your choosing.

Payload flips this entirely. You own the database. Postgres on Railway, Neon, or your client's existing RDS instance — it doesn't matter. That is a genuine operational burden (backups, migrations, scaling read replicas) but it is also genuine control. For a startup that already runs Postgres and doesn't want another SaaS line item, or an enterprise with strict residency requirements, Payload's model is not a compromise — it is the point.

Query language: GROQ vs Payload's local API

GROQ is expressive and surprisingly powerful once it clicks. Deeply nested projections, conditional fields, joins across references — all readable once you know the syntax. The cost is that it is Sanity-specific. You are learning a query language that does not transfer to anything else.

Payload's local API is different in character. Because you are running Payload inside the same Next.js app (via the @payloadcms/next package), you query your content with TypeScript function calls in the same process — no HTTP round trip for server-side rendering:

// app/blog/[slug]/page.tsx — Payload local API call (same process, no HTTP)
import { getPayload } from 'payload'
import config from '@payload-config'

export default async function BlogPost({ params }: { params: { slug: string } }) {
  const payload = await getPayload({ config })
  const { docs } = await payload.find({
    collection: 'posts',
    where: { slug: { equals: params.slug } },
    depth: 2,
  })
  const post = docs[0]
  // ...
}

This is ergonomically nice for a Next.js team. No separate SDK, no serialisation overhead, full type safety from your schema without a code-generation step. The downside is that Payload must run in the same deployment as your Next.js app (or as a separate service), which changes your infra topology compared to Sanity's pure API model.

TypeScript developer experience

Sanity TypeGen is good — I have written about it separately — but it is a generation step. You define schemas in Sanity's schema format, run sanity typegen generate, and get types that reflect your GROQ query shapes. It works well in CI but it is an extra step, and the types are only as accurate as your GROQ projection.

Payload's TypeScript DX is better by design. Your schema is TypeScript. Payload infers collection types from your field definitions automatically. There is no generation step at dev time — the types exist because the schema exists. For TypeScript-heavy teams this is a meaningful quality-of-life difference.

Editor and Studio experience

Sanity Studio is the strongest headless editing experience I have worked with. Portable Text, hotspot-aware image cropping, real-time multiplayer editing, a structure builder that lets you surface exactly the views editors need — it is genuinely polished after five years of iteration. Non-technical clients consistently find it approachable after one 30-minute walkthrough.

Payload Admin has caught up substantially in v3. It is built on Next.js App Router itself, which means customising it feels familiar if you already live in that stack. It is less opinionated about rich text (it uses Lexical by default, which is capable but less battle-tested in content-heavy sites than Portable Text). Live preview exists but the ecosystem of third-party Studio plugins that Sanity has accumulated over years is not there yet for Payload.

Image pipeline and CDN

This is where Sanity has a durable advantage for most projects. The Sanity CDN serves images at cdn.sanity.io with URL-based transformations — width, height, format, quality, focal-point crop — all without a separate image service. Pair that with next/image and you get AVIF/WebP serving, LCP-friendly preloading, and LQIP blur-ups without touching your own infra.

Payload has no built-in image CDN. You configure an upload adapter — S3 is the standard — and then decide how to serve and transform images. Cloudflare Images, imgix, or a Cloudflare Worker that transforms on the fly all work, but you are assembling those pieces yourself. That is not a fatal problem but it is real work, and it adds cost to the initial build.

Pricing and total cost of ownership

Sanity's free tier covers small projects comfortably (three users, 2 GB assets, 500K API calls/month). A real production site typically lands on the Growth plan at $15/month per project. A multi-tenant agency setup or a high-traffic editorial site can push into $99+/month territory once you add seats and bandwidth. That cost is predictable and low relative to developer time, but it does not go to zero.

Payload is MIT-licensed. The software costs nothing. What you pay is infra (a Postgres database, object storage, possibly a separate compute instance) and the developer time to operate it. For a solo developer running three client sites, that ops overhead is real. For a startup with a DevOps function already in place, Payload's TCO can be lower over three years than Sanity's.

Honest recommendation by team type

Solo freelancer or small agency: Sanity. The hosted infrastructure, polished Studio, and Next.js SDK mean you spend time building features, not operating databases. The monthly cost is a rounding error on a client retainer.

Startup with a technical co-founder and existing Postgres infra: Payload deserves a serious look. Native TypeScript types, no SaaS bill, and data ownership matter more as you scale. Factor in the image pipeline gap.

Agency delivering many client sites: Sanity. The organisational model (separate datasets per client, Studio customisation via plugins, structure builder) is built for this workflow.

Enterprise or regulated-industry client with data-residency constraints: Payload is often the only viable choice. Self-hosted, EU-only Postgres, no third-party content lake in the chain.

Team that wants maximum Next.js co-location: Payload's local API and co-located Admin are architecturally cleaner for teams that want everything in one repo and one deployment. Sanity's external API model is fine, but it is a seam.

The honest bottom line: Sanity wins on ecosystem maturity, editor experience, and zero-ops image delivery. Payload wins on data ownership, TypeScript ergonomics, and total cost for teams already running their own infrastructure. Neither is a wrong answer in 2026 — the question is which constraints matter most on your specific project.

If Strapi is also on your shortlist, I cover all three in my Sanity vs Strapi vs Payload comparison, and if you've landed on Sanity, the Sanity pricing breakdown for 2026 walks through the plan you'll actually need. When you're ready to build, here's how to hire a Sanity CMS developer — fixed-price proposal after a short scope call.

Next.js partial prerendering in production: an honest assessment

Nayan Kyada — Fri, 29 May 2026 08:13:37 +0000

Next.js partial prerendering (PPR) in production is one of those features that looks elegant in a demo and then humbles you the moment you apply it to a real content site with auth, personalisation, and third-party scripts. I have been running PPR on a handful of client projects since it moved out of experimental in Next.js 15, and this is what I actually think.

What PPR is trying to solve

The honest framing: PPR is a compromise between static and dynamic rendering, not a replacement for either. The classic problem it targets is a page that is 90% cacheable — a marketing landing page, a product detail page, a blog post — but has one or two dynamic fragments: a user-specific cart count, a personalised banner, a recently-viewed shelf. Before PPR, a single cookies() or headers() call anywhere in the render tree opted the entire route into dynamic rendering, destroying your TTFB.

PPR lets you stream a static shell (prerendered at build time, served from the edge instantly) and defer the dynamic parts behind <Suspense> boundaries, which are filled in via a streaming response once the dynamic work resolves. For content-heavy pages with a small dynamic surface, this is genuinely useful.

Where it actually works well

The page patterns that benefit most are exactly what you would expect:

Product pages with static copy and a dynamic price/stock fragment
Blog posts served from a CMS (Sanity, in my case) with a personalised "save for later" button
Marketing landing pages with a logged-in user greeting or A/B variant in a single section

The gains are real. A Sanity-powered product page that previously hit ~300ms TTFB due to a single cookies() call in a nav component drops back to sub-50ms for the shell. The user sees content immediately; the dynamic fragment streams in within a couple hundred milliseconds. That is a meaningful LCP improvement without restructuring the whole page.

The Suspense boundary problem

Here is where developers hit a wall. PPR does not automatically know which parts of your tree are dynamic — you have to wrap dynamic components in <Suspense> and ensure the static outer shell contains no dynamic calls. That sounds simple until you realise how many components call cookies() or headers() indirectly, often through a shared auth utility or a third-party wrapper.

// app/products/[slug]/page.tsx
import { Suspense } from 'react'
import { ProductDetails } from '@/components/product-details' // static — reads from Sanity
import { CartButton } from '@/components/cart-button' // dynamic — reads cookies
import { CartButtonSkeleton } from '@/components/cart-button-skeleton'

export const experimental_ppr = true

export default async function ProductPage({ params }: { params: { slug: string } }) {
  return (
    <main>
      {/* This component fetches from Sanity — fully static, prerendered */}
      <ProductDetails slug={params.slug} />

      {/* CartButton calls cookies() internally — must be inside Suspense */}
      <Suspense fallback={<CartButtonSkeleton />}>
        <CartButton />
      </Suspense>
    </main>
  )
}

The problem I run into most often: a layout component that seemed static actually calls headers() to read an accept-language header for locale detection. That single call poisons the entire shell. You have to audit every component in the static portion of the tree, and in a real codebase that audit takes time.

Next.js will tell you at build time if a dynamic API is used outside a Suspense boundary when PPR is enabled — but the error messages are not always specific enough to pinpoint the offending import chain quickly.

What changes in your data-fetching

The shift PPR demands is moving from "fetch data at the top of the page and pass it down" toward "fetch data as close to the component that needs it as possible". This aligns well with React Server Components anyway, but PPR makes it mandatory for anything that mixes static and dynamic data.

For Sanity-backed pages, this is mostly fine — fetch in an RSC is deduplicated by Next.js's request cache, so multiple components querying the same document do not trigger multiple round trips. The bigger adjustment is pulling dynamic reads (auth cookies, user preferences, request headers) into leaf components wrapped in Suspense, rather than resolving them in a shared root layout.

// lib/get-product.ts — called from a static RSC, no dynamic APIs here
import { client } from '@/sanity/client'

export async function getProduct(slug: string) {
  return client.fetch(
    `*[_type == "product" && slug.current == $slug][0]{
      _id, title, price, description, mainImage
    }`,
    { slug },
    // Tag for on-demand revalidation via Sanity webhook
    { next: { tags: [`product:${slug}`] } }
  )
}

The next: { tags } option still works exactly as before with PPR — ISR tag-based revalidation invalidates the prerendered shell. That combination (PPR shell + webhook-triggered revalidation) is the pattern I reach for on Sanity content sites now.

Where PPR breaks down

Three situations where I would not use PPR:

Fully dynamic pages. If a page is personalised end-to-end — a dashboard, a checkout, anything behind auth — there is no static shell to speak of. PPR adds complexity with no payoff. Use dynamic rendering or a client-side data fetch.

Pages with many small dynamic fragments. If you have eight different Suspense boundaries each streaming in a small fragment, the waterfall of small streaming chunks can actually feel worse than a single dynamic response. The user watches the page assemble piece by piece. PPR works best when the dynamic surface is small and concentrated.

Teams without strong component discipline. PPR punishes implicit coupling. If your codebase has a habit of reading cookies() in utility functions called from many places, the refactor required before PPR is worthwhile is not trivial. I have quoted that work to clients as a discrete scope item, not a free upgrade.

My current position

PPR is worth enabling on content-heavy routes where a small dynamic fragment was the only thing blocking static rendering. It is not a silver bullet, and it is not as automatic as Vercel's blog posts make it sound. Treat it as a page-level decision, not a global configuration you flip on and walk away from. Audit your component tree first, plan your Suspense boundaries before writing code, and keep the dynamic surface as small as possible.