DEV Community: Nayan Kyada

How I write custom validation rules in Sanity schemas

Nayan Kyada — Mon, 29 Jun 2026 09:15:31 +0000

Sanity custom validation rules in schemas are one of those features that look simple in the docs but get complicated fast in production. Required fields are trivial. The moment you need async uniqueness checks, cross-field conditionals, or messages that actually tell an editor what to fix, the built-in examples stop being enough. Here is exactly how I handle each case.

The baseline: required, regex, and length

Every schema gets at least the basics. Sanity's .validation callback receives a Rule object — you chain methods off it or return a custom function. I always type the schema with defineField so TypeScript catches mismatches early.

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

export const article = defineType({
  name: 'article',
  title: 'Article',
  type: 'document',
  fields: [
    defineField({
      name: 'title',
      title: 'Title',
      type: 'string',
      validation: (Rule) =>
        Rule.required()
          .min(10)
          .max(80)
          .error('Title must be between 10 and 80 characters.'),
    }),
    defineField({
      name: 'metaDescription',
      title: 'Meta description',
      type: 'text',
      rows: 3,
      validation: (Rule) =>
        Rule.required()
          .min(120)
          .max(160)
          .warning(
            'Meta descriptions outside 120–160 characters often get rewritten by Google.',
          ),
    }),
    defineField({
      name: 'externalUrl',
      title: 'External URL',
      type: 'url',
      validation: (Rule) =>
        Rule.uri({
          scheme: ['https'],
        }).error('Only HTTPS URLs are allowed.'),
    }),
    defineField({
      name: 'sku',
      title: 'SKU',
      type: 'string',
      validation: (Rule) =>
        Rule.custom((value) => {
          if (!value) return true // not required here
          const skuPattern = /^[A-Z]{2}-\d{4,6}$/
          return skuPattern.test(value)
            ? true
            : 'SKU must match the pattern AA-0000 (two uppercase letters, hyphen, 4-6 digits).'
        }),
    }),
  ],
})

A few things I do consistently: .error() for publish-blocking problems, .warning() for best-practice nudges that don't block. The message text is written for the editor, not for me — "SKU must match the pattern AA-0000" beats "invalid format" every time.

Async checks: uniqueness via GROQ inside `custom()`

The Rule.custom() callback can return a Promise<true | string>. That opens the door to hitting the Sanity client from inside validation — useful for uniqueness checks that don't belong in a slug field specifically.

// schemas/product.ts
import { defineField, defineType } from 'sanity'
import { groq } from 'next-sanity'

export const product = defineType({
  name: 'product',
  title: 'Product',
  type: 'document',
  fields: [
    defineField({
      name: 'barcode',
      title: 'Barcode (EAN-13)',
      type: 'string',
      validation: (Rule) =>
        Rule.custom(async (value, context) => {
          if (!value) return true

          // Basic EAN-13 format guard first
          if (!/^\d{13}$/.test(value)) {
            return 'Barcode must be exactly 13 digits.'
          }

          const { document, getClient } = context
          const client = getClient({ apiVersion: '2024-01-01' })

          // Exclude the current document so edits don't false-positive
          const existingId = await client.fetch<string | null>(
            groq`*[_type == "product" && barcode == $barcode && _id != $id][0]._id`,
            { barcode: value, id: document?._id ?? '' },
          )

          return existingId
            ? `Barcode ${value} is already used by another product.`
            : true
        }),
    }),
  ],
})

The context argument is the part most tutorials skip. It carries document (the full in-progress document), getClient (so you don't need to import a separate client), path, and type. I always use getClient from context rather than importing a singleton — it respects the Studio's configured dataset and token without extra wiring.

Note the document?._id ?? '' pattern. On first save the document ID might not exist yet. Passing an empty string means the GROQ filter _id != $id still works correctly and won't accidentally exclude a real match.

Cross-field validation on the document type itself

Single-field rules can't see sibling fields. For rules like "if publishDate is set, author is required" you need to validate at the document level using __experimental_actions or, more practically, Rule.custom on the document type.

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

export const event = defineType({
  name: 'event',
  title: 'Event',
  type: 'document',
  // Document-level validation runs against the whole document object
  validation: (Rule) =>
    Rule.custom((doc) => {
      if (!doc) return true

      const { startDate, endDate, registrationUrl, capacity } = doc as {
        startDate?: string
        endDate?: string
        registrationUrl?: string
        capacity?: number
      }

      if (startDate && endDate && endDate <= startDate) {
        return 'End date must be after start date.'
      }

      if (registrationUrl && !capacity) {
        return 'Set a capacity when a registration URL is provided.'
      }

      return true
    }),
  fields: [
    defineField({ name: 'title', type: 'string', validation: (Rule) => Rule.required() }),
    defineField({ name: 'startDate', type: 'datetime' }),
    defineField({ name: 'endDate', type: 'datetime' }),
    defineField({ name: 'registrationUrl', type: 'url' }),
    defineField({ name: 'capacity', type: 'number', validation: (Rule) => Rule.min(1).integer() }),
  ],
})

Document-level validation errors appear at the top of the Studio form — editors see them before they try to publish. The downside is the message has to describe the problem without highlighting a specific field. I keep these messages concrete: name the fields involved so the editor knows where to scroll.

Making error messages useful

A few rules I follow for validation copy:

State what is wrong, not what the field is called. "Title must be between 10 and 80 characters" not "Invalid title".
For cross-field errors, name both fields: "End date must be after start date" not "Date error".
Use .warning() for non-blocking guidance (SEO tips, recommended word counts). Reserve .error() for things that genuinely break the page or downstream systems.
Async uniqueness errors should include the conflicting value so the editor can spot it fast: "Barcode 1234567890123 is already used by another product."

One trap to avoid: returning false from custom() shows no message at all. Always return a string when validation fails — the string is the message.

Combining multiple rules

You can return an array from the validation callback to run several independent checks and surface all failures at once rather than stopping at the first:

validation: (Rule) => [
  Rule.required().error('Title is required.'),
  Rule.max(80).warning('Titles over 80 characters are truncated in search results.'),
]

This is cleaner than chaining when the rules have different severities or different messages.

Custom validation is one of the highest-leverage places to invest in a Sanity schema. Good rules catch bad data before it reaches your frontend queries, reduce back-and-forth with editors, and make the Studio feel considered rather than generic.

How I customise Sanity Structure Builder with custom ordering and grouping

Nayan Kyada — Sat, 27 Jun 2026 07:33:30 +0000

Sanity's default desk structure is fine when a project has three document types. Once you're past a dozen schemas, editors start complaining that the sidebar is a wall of alphabetical noise. Here's exactly how I configure Structure Builder — custom ordering, grouped sections, and hidden system types — so that every Studio I ship feels deliberate rather than auto-generated.

What Sanity structure builder custom ordering actually controls

Structure Builder lives inside sanity.config.ts via the structureTool plugin (formerly deskTool). It lets you replace the auto-generated document list with a hand-crafted sidebar tree. The key APIs are:

S.documentTypeList(schemaType) — renders all documents of a given type
S.listItem() — a single navigable row
S.list() — a named group of items
S.divider() — a visual separator
defaultOrdering on documentTypeList — controls how documents are sorted before editors touch them

The default ordering is by _updatedAt descending. That works for a blog, but it's wrong for a settings singleton or a navigation document that almost never changes.

Setting up the structure file

I always pull the structure function into its own file to keep sanity.config.ts readable.

// sanity/structure.ts
import type { StructureResolver } from 'sanity/structure'

export const structure: StructureResolver = (S) =>
  S.list()
    .title('Content')
    .items([
      // ── Singletons ──────────────────────────────────────────────
      S.listItem()
        .title('Site settings')
        .id('siteSettings')
        .child(
          S.document()
            .schemaType('siteSettings')
            .documentId('siteSettings')
        ),

      S.listItem()
        .title('Navigation')
        .id('navigation')
        .child(
          S.document()
            .schemaType('navigation')
            .documentId('navigation')
        ),

      S.divider(),

      // ── Editorial ───────────────────────────────────────────────
      S.listItem()
        .title('Posts')
        .child(
          S.documentTypeList('post')
            .title('Posts')
            .defaultOrdering([
              { field: 'publishedAt', direction: 'desc' },
            ])
        ),

      S.listItem()
        .title('Authors')
        .child(
          S.documentTypeList('author')
            .title('Authors')
            .defaultOrdering([
              { field: 'name', direction: 'asc' },
            ])
        ),

      S.divider(),

      // ── Products ────────────────────────────────────────────────
      S.listItem()
        .title('Products')
        .child(
          S.documentTypeList('product')
            .title('Products')
            .defaultOrdering([
              { field: 'title', direction: 'asc' },
            ])
        ),

      S.listItem()
        .title('Categories')
        .child(
          S.documentTypeList('category')
            .title('Categories')
            .defaultOrdering([
              { field: 'title', direction: 'asc' },
            ])
        ),
    ])

Then in sanity.config.ts:

// sanity.config.ts
import { defineConfig } from 'sanity'
import { structureTool } from 'sanity/structure'
import { structure } from './sanity/structure'
import { schemaTypes } from './sanity/schemas'

export default defineConfig({
  projectId: process.env.NEXT_PUBLIC_SANITY_PROJECT_ID!,
  dataset: process.env.NEXT_PUBLIC_SANITY_DATASET!,
  plugins: [
    structureTool({ structure }),
  ],
  schema: { types: schemaTypes },
})

The structureTool plugin accepts a structure option — just pass the resolver directly. No extra wiring needed.

Hiding types you don't want editors to see

Sanity will surface every registered schema type unless you exclude it. Two common cases:

Media plugin types (sanity.imageAsset, sanity.fileAsset) — Sanity handles these internally. They should never appear in the sidebar.
Sub-documents — if you have a blockContent or figure object type that only ever lives inside another document, listing it standalone confuses editors.

The cleanest approach is to build an explicit allowlist rather than a denylist. Because I'm constructing the entire tree manually in structure.ts, any schema type I omit simply never appears. There's nothing to suppress.

If you want to be defensive — say a new developer adds a schema and forgets to wire it into the structure — you can log a warning in development:

// sanity/structure.ts  (add at the top of the resolver)
import type { StructureResolver } from 'sanity/structure'

const MANAGED_TYPES = new Set([
  'siteSettings',
  'navigation',
  'post',
  'author',
  'product',
  'category',
])

export const structure: StructureResolver = (S, context) => {
  if (process.env.NODE_ENV === 'development') {
    const allTypes = context.schema
      .getTypeNames()
      .filter((n) => !n.startsWith('sanity.') && !n.startsWith('assist.'))

    const unmanaged = allTypes.filter((t) => !MANAGED_TYPES.has(t))
    if (unmanaged.length > 0) {
      console.warn('[structure] Unmanaged schema types:', unmanaged)
    }
  }

  return S.list()
    .title('Content')
    .items([
      // ... same as before
    ])
}

This gives you a console warning every time Studio hot-reloads if a schema type is unaccounted for. It's saved me from missed wiring at least three times on larger projects.

Grouping into nested lists

On projects with 20+ document types I group related schemas under a parent list item rather than flattening everything. The S.list() builder nests cleanly:

S.listItem()
  .title('Commerce')
  .child(
    S.list()
      .title('Commerce')
      .items([
        S.listItem()
          .title('Products')
          .child(
            S.documentTypeList('product')
              .defaultOrdering([{ field: 'title', direction: 'asc' }])
          ),
        S.listItem()
          .title('Collections')
          .child(
            S.documentTypeList('collection')
              .defaultOrdering([{ field: 'title', direction: 'asc' }])
          ),
        S.listItem()
          .title('Discount codes')
          .child(
            S.documentTypeList('discountCode')
              .defaultOrdering([{ field: '_createdAt', direction: 'desc' }])
          ),
      ])
  ),

Nesting beyond two levels starts to feel maze-like for editors. I keep it to one level of nesting maximum.

Default ordering field choices by document type

A few patterns I've settled on across projects:

Document type	Field	Direction	Reason
Blog post	`publishedAt`	desc	Most recent post on top
Author / person	`name`	asc	Alphabetical scan
Product	`title`	asc	Alphabetical scan
Event	`startDate`	asc	Upcoming first
Redirect	`_createdAt`	desc	Newest entry likely needs review
Singleton	N/A	N/A	Single document, no list

The field must exist on the schema and be indexed for GROQ ordering to work in the Studio. Computed or derived fields won't work here — stick to top-level scalars.

Icons make a real difference

The sidebar becomes scannable fast when each list item has an icon. Sanity ships @sanity/icons and you can pass any React component to .icon():

import { DocumentTextIcon, TagIcon, CogIcon } from '@sanity/icons'

S.listItem()
  .title('Posts')
  .icon(DocumentTextIcon)
  .child(S.documentTypeList('post').defaultOrdering([...]))

This is a ten-minute addition that editors notice immediately. I do it on every project by default now.

Where this breaks down

Structure Builder is purely UI-side configuration. It doesn't restrict API access, it doesn't enforce permissions, and it doesn't change what GROQ queries return. If you need to hide document types from specific roles rather than just from the sidebar, that's a job for Sanity's access control rules — a separate layer entirely.

Also worth noting: the structure is evaluated client-side inside the Studio bundle. Keep the resolver function synchronous and cheap. I've seen projects that fetched data inside the structure resolver to build dynamic lists — it works, but it makes Studio load sluggish and is hard to cache properly.

How I set up sanity scheduled publishing with Next.js ISR revalidation

Nayan Kyada — Fri, 26 Jun 2026 08:06:52 +0000

Sanity scheduled publishing lets editors set a future publish date on any document. The problem is that Next.js has no idea a schedule just fired — the cached page keeps serving stale content until something tells the router to revalidate. This post shows exactly how I wire those two systems together so a post scheduled for 09:00 goes live at 09:00, not whenever the next organic revalidation happens to occur.

How sanity scheduled publishing actually works

The Scheduled Publishing feature ships as a first-party Sanity plugin (@sanity/scheduled-publishing). Once installed it adds a schedules document type to your dataset and a calendar UI to Studio. When the scheduled time arrives, Sanity's cloud infrastructure publishes the document — it transitions from draft to published exactly like a manual publish action. What it does not do is ping your front-end. That's your job.

The plugin exposes a REST endpoint:

GET https://api.sanity.io/v2022-03-07/schedules/{projectId}/{dataset}?state=upcoming

You can poll it to see what's queued, but for triggering revalidation in Next.js the right tool is a Sanity webhook pointed at the document being published, not a polling loop.

Setting up the plugin

Install and register the plugin inside sanity.config.ts:

// sanity.config.ts
import { defineConfig } from 'sanity'
import { scheduledPublishing } from '@sanity/scheduled-publishing'
import { structureTool } from 'sanity/structure'

export default defineConfig({
  projectId: process.env.NEXT_PUBLIC_SANITY_PROJECT_ID!,
  dataset: process.env.NEXT_PUBLIC_SANITY_DATASET!,
  plugins: [
    structureTool(),
    scheduledPublishing({
      enabled: true,
      inputDateTimeFormat: 'dd/MM/yyyy HH:mm',
    }),
  ],
  schema: {
    types: [
      // your document types
    ],
  },
})

That's all the Studio side needs. After deploying, editors see a clock icon next to the Publish button. They pick a date, save, and the document enters a scheduled state — it's still a draft from the perspective of your GROQ queries until the moment it publishes.

One thing worth knowing: a scheduled document has _type: "schedule.metadata" in the dataset alongside the actual document. Your existing GROQ queries that filter on _type == "post" && defined(slug) naturally ignore it, so there's nothing to change there.

Triggering ISR when a scheduled document goes live

When Sanity publishes a scheduled document its event type in the mutations stream is create or update with transition: "appear" — the same signal as a regular publish. That means the webhook you already have for on-demand ISR fires for scheduled publishes too, at no extra configuration cost.

If you haven't wired webhooks to ISR yet, here's the minimal route handler. It receives a Sanity GROQ-powered webhook, verifies the HMAC signature, and calls revalidateTag for the affected document.

// app/api/revalidate/route.ts
import { revalidateTag } from 'next/cache'
import { type NextRequest, NextResponse } from 'next/server'
import { createHmac, timingSafeEqual } from 'crypto'

const SECRET = process.env.SANITY_REVALIDATE_SECRET!

function verifySignature(body: string, signature: string): boolean {
  const expected = createHmac('sha256', SECRET)
    .update(body)
    .digest('hex')
  try {
    return timingSafeEqual(
      Buffer.from(signature, 'hex'),
      Buffer.from(expected, 'hex'),
    )
  } catch {
    return false
  }
}

export async function POST(req: NextRequest) {
  const rawBody = await req.text()
  const signature = req.headers.get('sanity-webhook-signature') ?? ''

  if (!verifySignature(rawBody, signature)) {
    return NextResponse.json({ error: 'Invalid signature' }, { status: 401 })
  }

  const payload = JSON.parse(rawBody) as {
    _type: string
    slug?: { current: string }
  }

  // Revalidate the document type cache and the specific slug
  revalidateTag(payload._type)
  if (payload.slug?.current) {
    revalidateTag(`${payload._type}:${payload.slug.current}`)
  }

  return NextResponse.json({ revalidated: true, ts: Date.now() })
}

In Sanity's dashboard under API → Webhooks, create a webhook pointing at https://yourdomain.com/api/revalidate. Set the filter to _type == "post" (or whatever document type you schedule), check Create, Update, and Delete, paste in your HMAC secret, and enable it.

The webhook filter runs server-side in Sanity's infrastructure, so when the scheduler fires it evaluates to true and Sanity sends the POST within a second or two of publication.

How ISR cache tagging interacts with scheduled content

In your data-fetching layer, tag every fetch call that depends on a document type:

// lib/sanity/queries.ts
import { client } from './client'

export async function getPostBySlug(slug: string) {
  const query = `
    *[_type == "post" && slug.current == $slug && !(_id in path("drafts.**"))] [0] {
      _id,
      title,
      publishedAt,
      slug,
      body
    }
  `
  return client.fetch(
    query,
    { slug },
    {
      next: {
        // revalidate as a safety net — webhook is the primary trigger
        revalidate: 3600,
        tags: [`post`, `post:${slug}`],
      },
    },
  )
}

The revalidate: 3600 is a safety net only. For scheduled content you want the webhook to be the trigger, because revalidate: 3600 could mean up to an hour of lag between publication and the cached page updating. With the webhook in place the lag is typically two to five seconds — Sanity's webhook delivery latency plus the time Next.js needs to purge the tag and rebuild the static shell.

Handling the "scheduled doc is still a draft" edge case

Before the publish time, the document exists only in draft form. If your Studio preview fetches with perspective: "previewDrafts" you'll see it, but your public GROQ queries — which filter !(_id in path("drafts.**")) — correctly exclude it. Nothing leaks to the public site before the schedule fires.

The one gotcha: if you have a sitemap that reads all published posts and an editor schedules a post for midnight, the sitemap stays accurate because the document isn't published yet. After the webhook fires and revalidation runs, the next sitemap request picks up the new slug automatically, assuming your sitemap route also uses revalidateTag or a short revalidate window.

Confirming it works end-to-end

Schedule a test document two minutes ahead. Watch the Sanity webhook logs in the dashboard — you'll see a delivery attempt appear within seconds of the publish time. Check your Next.js logs for the revalidated: true response. Then fetch the public page: it should reflect the new content. If the webhook shows a non-2xx response, the most common cause is a signature mismatch from a stale or mismatched SANITY_REVALIDATE_SECRET environment variable between your Sanity webhook config and your deployed function.

Payload CMS vs Contentful 2026: which one fits your Next.js project

Nayan Kyada — Thu, 25 Jun 2026 07:59:23 +0000

Choosing between Payload CMS and Contentful in 2026 means choosing between two genuinely different philosophies: code-first self-hosted versus hosted SaaS with a visual modelling UI. Both are production-ready, both work with Next.js App Router, and both will cost you something — the question is what kind of cost you can absorb.

How payload cms vs contentful 2026 actually breaks down

The fastest way to see the difference is a side-by-side on the dimensions that matter for a real project.

Dimension	Payload CMS	Contentful
Hosting	Self-hosted (Node, Docker, Railway, Render)	Fully managed SaaS
Schema definition	TypeScript config files, git-versioned	Web UI (content type builder)
Database	MongoDB or Postgres (your choice)	Proprietary (opaque)
API surface	REST + GraphQL + local API (same process)	REST + GraphQL (remote only)
Auth / access control	Built-in, code-defined roles	UI-defined roles, paid tiers for advanced
Pricing model	Free + infrastructure cost	Free tier → steep SaaS curve
Localization	Plugin, manual wiring	Built-in on paid plan
Next.js draft mode	Custom route handler, manual	Contentful Preview API, documented
Vendor lock-in	Low (your DB, your code)	Medium-high (proprietary delivery API)
Editor experience	Functional, improving fast	Polished, mature

Neither row is universally better. They represent a trade-off you need to make before you write a line of schema code.

Schema in code vs schema in a UI

Payload defines every collection and field in TypeScript. That means your schema lives in git, gets reviewed in PRs, and rolls back cleanly when something breaks in production.

// collections/Articles.ts
import type { CollectionConfig } from 'payload'

export const Articles: CollectionConfig = {
  slug: 'articles',
  admin: { useAsTitle: 'title' },
  fields: [
    { name: 'title', type: 'text', required: true },
    { name: 'slug', type: 'text', unique: true },
    {
      name: 'hero',
      type: 'upload',
      relationTo: 'media',
    },
    {
      name: 'body',
      type: 'richText',
    },
  ],
}

Contentful's content type builder is visual and approachable — a non-technical content strategist can add a field without touching code. That is genuinely useful on teams where editors own the information architecture. The cost is that schema drift happens invisibly, migrations require their own CLI tooling, and you cannot enforce field constraints in the same way you can with TypeScript types.

For agency and product teams where a developer owns the content model, Payload's approach is cleaner. For enterprise teams where content strategy, development, and editorial are three separate departments, Contentful's UI modelling is a real operational advantage.

API and Next.js integration

Contentful gives you a remote REST and GraphQL API. Every page render — even during build — is an outbound HTTP call. You rate-limit against their CDN and you pay per API call at scale.

Payload's local API runs in the same Node process as your Next.js app when you deploy them together (or as a monorepo on a single server). Fetching content is a direct function call, not an HTTP round-trip.

// app/articles/[slug]/page.tsx
import { getPayload } from 'payload'
import config from '@payload-config'

export default async function ArticlePage({ params }: { params: { slug: string } }) {
  const payload = await getPayload({ config })
  const { docs } = await payload.find({
    collection: 'articles',
    where: { slug: { equals: params.slug } },
    depth: 1,
  })
  const article = docs[0]
  if (!article) return notFound()
  // render...
}

No fetch, no network latency, no API key in environment variables for the frontend. For React Server Components this is a significant win — you get typed data directly in the component without an extra abstraction layer.

Contentful's Next.js integration is well-documented and the Content Delivery API is fast from Vercel's edge network. But it is still a remote call, and you are still building around their SDK types rather than your own.

Pricing curve

This is where the comparison gets sharp. Payload itself is MIT-licensed and free. You pay for a server (a $7/month Railway instance handles a modest site), your own database, and your own CDN for assets. The curve is flat and predictable.

Contentful's free tier allows 25,000 API calls per month and two locales. Once you hit the Community plan ceiling, the next meaningful tier (Basic) is around $300/month at 2026 pricing. Enterprise licensing is negotiated and can reach five figures annually. For a high-traffic editorial site or a platform with multiple spaces, the bill grows faster than traffic does.

For a single-brand marketing site with a small team, Contentful's free tier often holds. For a multi-tenant product, a publication with heavy traffic, or a startup that wants cost control as it scales, Payload's infrastructure model is materially cheaper.

Editor experience and maturity

Contentful has a decade of editor UX refinement. Rich text, asset management, reference fields, and scheduled publishing all work well out of the box. Support is enterprise-grade and the documentation is thorough.

Payload's admin UI has improved significantly through 2024 and 2025, but it is still younger. Rich text uses the Lexical editor, which is capable but occasionally rough at the edges. If your client's editorial team is the primary user and they have never touched a headless CMS before, Contentful will feel more immediately familiar.

That gap is narrowing. For developer-run projects or internal tools where the admin UI is secondary, it is not a deciding factor.

When to choose Payload

Pick Payload if your team owns the infrastructure, the schema needs to be version-controlled, you want the local API advantage in Next.js RSC, and cost control matters as the project scales. Also a strong fit for applications that blur the line between CMS and backend — Payload's auth, access control, and hooks mean it can replace an API layer entirely.

When to choose Contentful

Pick Contentful if your client or stakeholders need a polished editorial UI from day one, you have a non-technical team managing the content model, you need enterprise SLAs and support contracts, or you are working inside a larger organisation that already has a Contentful space and does not want another system to maintain.

Lock-in is a real consideration. Contentful content lives in Contentful's database. Migration tooling exists but it is non-trivial at scale. Payload's data is in your Postgres or MongoDB instance — you own it outright.

Best free headless CMS for Next.js in 2026: five tiers compared

Nayan Kyada — Wed, 24 Jun 2026 07:58:30 +0000

Finding the best free headless CMS for a Next.js project in 2026 is harder than it looks. Every vendor buries the real limits — API call caps, seat restrictions, bandwidth ceilings — in a pricing footnote. This post cuts through that: five CMS options, free tier only, honest about what breaks first.

What free actually means across these five CMS options

Before the comparison: there are two categories of "free" here. Managed SaaS free tiers (Sanity, Contentful, Storyblok) give you a hosted service with hard caps. Self-hosted open source (Payload, Strapi) are free in licence cost but you pay for the server, Postgres, backups, and your own time. Neither is bad — they suit different project shapes.

Sanity free tier (2026)

Sanity's free plan is called the Free plan. As of mid-2026 the headline numbers are: 3 users, 2 datasets, 500k API requests/month, 5 GB asset storage, 1 GB bandwidth/month, and 10k non-CDN API requests included in that 500k cap.

What you keep on free: the full GROQ API, Sanity Studio (embeddable in your Next.js App Router at /studio), image transforms via the CDN, and the TypeGen pipeline. Presentation / live preview also works on free — it only hits the CDN, not the non-CDN quota.

What you lose: no private datasets (everything is publicly readable by API key), no custom roles, no RBAC, no content releases, and 1 GB bandwidth will vanish fast on any image-heavy site with real traffic.

When you outgrow it: the 1 GB bandwidth cap is the trip-wire. A mid-sized blog with 50 images per page and 5k monthly visitors can hit it in the first week. The Growth plan at $15/seat/month unlocks 100 GB bandwidth. For a side project or staging environment Sanity free is excellent. For a live marketing site with a real content team, budget for Growth from day one.

// This GROQ query works identically on the free tier — no feature gates on query language
*[_type == "post" && defined(slug.current)] | order(publishedAt desc) [0..9] {
  _id,
  title,
  "slug": slug.current,
  "lqip": mainImage.asset->metadata.lqip,
  publishedAt
}

Contentful free tier (2026)

Contentful's Community plan: 1 space, 2 environments (master + 1), 5 users, 1 million API calls/month, 2 GB asset storage, no GraphQL on free (REST only).

What you lose on free: GraphQL Content API (Community is REST-only), Workflows, Launches, content scheduling, roles beyond Admin/Editor/Author. The 1 million API call cap sounds generous but Contentful counts preview API calls separately and ISR revalidation burns through them faster than you'd expect on a busy Next.js app.

Contentful's free tier used to be my first recommendation for agency proof-of-concepts but their 2025 pricing restructure removed the 24-hour API token and made the Delivery API key management more restrictive. It still works fine for a single-developer prototype. Five seats is reasonable.

When you outgrow it: first you'll hit the 2-environment ceiling — you need at least staging, preview, and production for a real delivery pipeline. The Basic plan starts at $300/month. That jump is steep and it's the main reason Contentful loses clients at the "we're ready to go live" stage.

Storyblok free tier (2026)

Storyblok Community: 1 space, 1 user, 1 published source, 10k API calls/month (not 1M — ten thousand), 1 GB asset storage.

10k API calls per month is extremely restrictive. A Next.js site doing ISR with a 60-second revalidation window makes up to 43,200 calls per month from Next.js alone, ignoring editor previews. Storyblok free is usable only for local development or a completely static, never-revalidated export.

Storyblok's Visual Editor is its differentiator but it is not available on the free plan — you get the content editor only. For a Next.js project where the whole point is the block-based visual editing, free is essentially a demo login.

When you outgrow it: immediately, for any live project. Entry plan starts at €99/month. Worth it if you need visual editing; otherwise look elsewhere at this price point.

Strapi community (self-hosted open source)

Strapi's Community edition is MIT-licensed, runs on Node.js, and costs nothing in licence fees. You pay for hosting: a DigitalOcean droplet ($6–$12/month), a managed Postgres instance ($15–25/month on Railway or Render), and your time.

What you get: REST and GraphQL APIs, a decent admin panel, role-based access control (basic), plugins ecosystem, and full schema control via TypeScript files. The Strapi v5 release in late 2024 improved the TypeScript support considerably.

What you lose vs cloud CMS: no built-in asset CDN (you wire S3 + Cloudfront yourself), no managed backups by default, and upgrades are your responsibility. The plugin ecosystem has fragmentation — some plugins are stuck on v4 schemas.

For a Next.js project: Strapi works well if you or your client already has a server/infra budget and you want SQL-backed content with complex relational schemas. The REST API is straightforward to consume with fetch in Next.js RSC.

// app/posts/page.tsx — consuming Strapi REST in RSC
import type { StrapiListResponse } from "@/types/strapi";

export const revalidate = 60;

export default async function PostsPage() {
  const res = await fetch(
    `${process.env.STRAPI_URL}/api/posts?populate=coverImage&sort=publishedAt:desc`,
    { headers: { Authorization: `Bearer ${process.env.STRAPI_TOKEN}` }, next: { revalidate: 60 } }
  );
  const { data }: StrapiListResponse<Post> = await res.json();
  return <ul>{data.map(p => <li key={p.id}>{p.attributes.title}</li>)}</ul>;
}

Payload CMS (open source, self-hosted)

Payload v3 (released late 2024) runs natively inside Next.js — the same app/ directory, the same server. There is no separate API server. Your Next.js route handlers are your API. This is the most interesting architectural shift in headless CMS in years.

Because it lives inside Next.js, there is no licence cost and no hosted tier to outgrow. The database is yours (Postgres or MongoDB). The admin panel ships at /admin as a Next.js route group.

Costs on free: Vercel Hobby plan limits serverless function duration and you will hit those limits with Payload's admin panel operations. Upgrade to Vercel Pro ($20/month) or self-host on a VPS. Postgres on Neon's free tier (0.5 GB storage, 1 compute hour/day) works for development but prod needs the $19/month Launch plan.

What you lose: no managed backups, no visual editor, no CDN image transforms (you wire Uploadthing or S3 yourself), and the plugin ecosystem is early compared to Strapi. The payoff is zero API quota anxiety — your Next.js RSC queries hit the same database directly, not an HTTP API.

// app/posts/page.tsx — querying Payload v3 directly inside Next.js
import { getPayload } from "payload";
import config from "@payload-config";

export default async function PostsPage() {
  const payload = await getPayload({ config });
  const { docs } = await payload.find({
    collection: "posts",
    sort: "-publishedAt",
    limit: 10,
  });
  return <ul>{docs.map(p => <li key={p.id}>{p.title}</li>)}</ul>;
}

Honest pick by project type

Personal blog or open-source project with no team: Sanity free. Full GROQ, Studio embeds cleanly, TypeGen works, and 500k API calls is fine for low traffic. The 1 GB bandwidth limit is the only watch point.

Agency staging / proof of concept: Sanity free or Contentful Community. Both give you enough to demo to a client. Sanity wins on DX; Contentful wins if the client's team already knows it.

Solo founder building an MVP, zero infra budget: Payload v3 on Vercel Pro + Neon Launch. Combined cost is ~$39/month, no API quota to hit, schemas live in your repo alongside the app. The trade-off is you own the ops.

Team of 3+ non-technical editors who need visual page building: Storyblok is the right tool but not on the free tier — budget for it from the start or choose a different CMS.

Client project that will definitely scale past 50k monthly visitors: None of these free tiers. Sanity Growth ($15/seat) or Payload self-hosted on a dedicated VPS is the honest starting point. Free tiers are for prototypes, not production traffic.

The recurring pattern: free tiers are genuinely useful for learning the API, building the integration, and demonstrating to clients. The moment you have real editors publishing real content to real traffic, the caps that matter are bandwidth (Sanity), environments (Contentful), and server costs (Payload, Strapi). Plan for the first upgrade before you start, not after you hit the wall at midnight before a launch.

Headless CMS pricing comparison 2026: Sanity vs Contentful vs Payload vs Strapi

Nayan Kyada — Tue, 23 Jun 2026 08:03:12 +0000

Headless CMS pricing in 2026 has become one of the first questions founders ask me when scoping a new build. The honest answer is: it depends entirely on your user count, API call volume, and whether you can run your own infrastructure. This post puts Sanity, Contentful, Payload, and Strapi side by side so you can read across a single table instead of opening four browser tabs.

I'm not going to repeat the feature comparisons I've already written elsewhere. This is purely about money — what you pay at each growth stage, and what event forces you to upgrade.

The headless CMS pricing comparison table

All figures are in USD per month as of June 2026. Verify against each vendor's live pricing page before you sign anything — these platforms revise tiers more often than they announce it.

	Sanity	Contentful	Payload	Strapi
Free tier	3 users, 10 GB bandwidth, 1 M API CDN requests, unlimited datasets	5 users, 25k records, 2 locales, 500k API calls/mo	Free OSS (self-host); Payload Cloud free tier: 1 project, 1 GB storage	Free OSS (self-host); Strapi Cloud free: 1 project, 1 GB
Paid entry	Growth: ~$15/mo (per seat after 3, usage add-ons stack)	Basic: $300/mo (hardcoded, not per-seat at this tier)	Payload Cloud Pro: $40/mo	Strapi Cloud Pro: $99/mo
What triggers the upgrade	>3 editors OR >10 GB bandwidth OR >1 M CDN requests/mo	>5 users OR >25k records OR >2 locales OR >500k API calls	Need CI deploys, custom domains, or more storage on Cloud; self-host stays free forever	Need >1 project, more DB storage, or dedicated support; self-host stays free forever
Self-host cost	Not available (SaaS only)	Not available (SaaS only)	$0 licence; you pay infra only (~$5–20/mo on Railway or Fly.io for small projects)	$0 licence; you pay infra only (~$5–20/mo on Railway or Fly.io for small projects)
Enterprise / custom	Contact sales; roughly $1k+/mo at scale	Contact sales; $2k+/mo is common	Custom; Payload Cloud enterprise pricing available	Custom; Strapi Enterprise licence separate from Cloud
Official pricing page	sanity.io/pricing	contentful.com/pricing	payloadcms.com/cloud	strapi.io/pricing

Reading the table honestly

Sanity is the most generous at the free tier for solo developers and small editorial teams. Three editors is enough for a founder plus one content person plus one developer. The problem is that costs compound: you pay per seat and per usage, so a mid-size marketing team of eight editors hits a meaningful monthly number fast. Sanity also has no self-host option — you are permanently renting their infrastructure.

Contentful looks cheap until you hit the Basic plan wall. There is no gradual ramp between the free tier and $300/month. That cliff is the single most common reason I see clients walk away from Contentful mid-evaluation. For a startup managing budget carefully, a $300/mo line item in month three of a new project is a real conversation. The flip side: Contentful's CDN and locale handling at the paid tier are genuinely mature, and large enterprise teams often find the flat pricing predictable at scale.

Payload is the outlier here because it is MIT-licensed open-source software. If you can self-host — and most teams with a competent developer can — the licence cost is zero. You pay for a VPS, a managed Postgres or MongoDB instance, and your time. For a small project that means roughly $10–25/month in real infra costs. Payload Cloud exists if you want managed hosting, but using it is optional. The tradeoff is operational overhead: you own upgrades, backups, and uptime.

Strapi follows the same model as Payload. The v5 open-source licence is free, self-hosting is straightforward, and Strapi Cloud is the optional managed layer. Strapi's Cloud entry point at $99/month is higher than Payload's $40, but Strapi has a larger plugin ecosystem and more established enterprise contracts if that matters to your procurement team.

Which tier fits which team size

Solo developer or two-person startup: Sanity free tier or self-hosted Payload. Both cost nothing until you grow. I usually recommend Sanity here because the zero-ops experience is valuable when you're also writing code and managing a product.

Five to ten editors, content-heavy marketing site: This is where the decision actually gets hard. Sanity starts costing $10–15 per editor per month above the base three. Contentful forces you to $300/month. Self-hosted Payload or Strapi stays near $20–40/month in infra if your team is comfortable running a server. If the client has no DevOps capability, Sanity wins on experience despite the seat cost.

Agency building for a client who will own the CMS long-term: I lean toward Payload or Strapi so the client never depends on a per-seat pricing model they can't control. Handing over an MIT-licensed codebase with a $15/month Railway deployment is a cleaner handoff than handing over a Sanity project where every new editor the client adds costs money they didn't budget for.

Enterprise with compliance requirements: Contentful and Sanity both have enterprise contracts with SOC 2 Type II and SSO. Strapi Enterprise adds audit logs and priority support. Payload is catching up on compliance certifications — worth checking their current status before scoping a regulated-industry project.

The real cost nobody puts in the table

Hosting and licence fees are the visible line item. The invisible one is migration cost. Contentful's data model is opinionated enough that moving off it later takes real engineering time. Sanity stores everything in NDJSON with a document-level graph, which is portable but still requires a migration script. Payload and Strapi use a relational database you already own — exporting your data is a SQL dump.

For a founder making this decision in 2026: price the three-year total, not the month-one number. If you expect to grow to fifteen editors, model the seat costs. If you expect to hire a developer who can maintain a server, model self-hosting. The right answer is usually one of two things: Sanity if you want zero infrastructure opinions and can absorb seat cost, or Payload/Strapi self-hosted if you want cost control and have engineering capacity to match.

Sanity vs Strapi in 2026: an honest side-by-side comparison

Nayan Kyada — Mon, 22 Jun 2026 10:20:25 +0000

Sanity vs Strapi comes up on almost every project where a client wants either full data ownership or a managed content lake — and the right answer genuinely depends on which constraint matters more. I've shipped production projects on both, and in 2026 the two platforms have diverged further rather than converged.

What each platform actually is

Sanity is a hosted content platform. Your documents live in Sanity's Content Lake, queries run over GROQ via a CDN-backed API, and the editing UI (Sanity Studio) is a React app you embed in your own repo or host on sanity.io. You get real-time collaboration, a managed asset pipeline with on-the-fly image transforms, and zero infrastructure to run.

Strapi is an open-source headless CMS you self-host. Content sits in a SQL database you control (PostgreSQL in production, SQLite for local dev). The admin UI is built into the server process. You query via REST or GraphQL. The company monetises through Strapi Cloud (managed hosting) and an enterprise licence, but the core is MIT-licensed and you can run it anywhere.

These are genuinely different bets, not just feature-list variations.

Editor UX: Sanity Studio vs Strapi admin

Sanity Studio is configurable at the code level. You write schema in TypeScript, wire in custom input components, build structure views, and embed live preview via the Presentation plugin. Editors get real-time presence indicators, document history, and hotspot cropping in the browser. The learning curve for non-technical editors is low — it feels closer to Notion than a traditional CMS admin.

Strapi's admin is auto-generated from your content types. It works well for straightforward field-and-collection models, but customising the UI means writing custom admin plugins in React against an internal API that has historically changed between major versions. In 2026 Strapi 5 stabilised a lot of that, but the plugin authoring experience is still more friction than writing a Sanity custom input.

For agencies handing off to marketing teams, Sanity Studio wins on first-day UX. For internal teams who want a predictable CRUD admin without custom code, Strapi's auto-generated forms are fine.

Querying: GROQ vs REST/GraphQL

GROQ is Sanity's query language. It lets you shape the response on the query side — dereference references, project only the fields you need, filter on deeply nested conditions — without round-trips. Once you're used to it, going back to REST feels like writing SQL with no JOIN syntax.

// Fetch a page with its author name and only the image fields needed for next/image
*[_type == "post" && slug.current == $slug][0] {
  title,
  publishedAt,
  "author": author->{ name, "avatarUrl": avatar.asset->url },
  mainImage {
    asset->{ url, metadata { lqip, dimensions } },
    hotspot,
    alt
  }
}

Strapi gives you REST endpoints auto-generated per content type, with a populate query param for relations, and an optional GraphQL plugin. The REST API is approachable for simple models. For deeply nested or cross-referenced content it becomes verbose, and populate=deep on large models is a known performance problem that teams work around with custom controllers.

If your Next.js app has complex content graphs, GROQ's projection model will save you a lot of over-fetching. If your content model is flat collections with simple relations, Strapi's REST is perfectly adequate.

Image pipeline

Sanity's asset pipeline transforms images at the CDN edge. You append ?w=800&fm=webp&auto=format to any image URL and the CDN handles encoding, caching, and serving from the correct edge node. Paired with next/image and a custom Sanity loader, you get WebP/AVIF, responsive sizes, and LQIP blur hashes without running any image processing yourself.

Strapi stores uploads in whatever provider you configure — local disk, S3, Cloudinary, or similar. There's no built-in transform pipeline. If you want on-the-fly resizes you wire in Cloudinary or imgix as a provider plugin, which adds a dependency and a pricing surface. For projects where the client already pays for Cloudinary, this is fine. For greenfield work, it's an extra thing to manage.

Edge: Sanity for image delivery with no extra configuration.

Pricing and lock-in

Dimension	Sanity	Strapi
Free tier	3 users, 10 GB bandwidth, 2 projects	Self-hosted (unlimited, MIT)
Paid starts at	~$15/month (Growth)	Strapi Cloud from ~$29/month, or your own hosting cost
Data ownership	Content Lake (Sanity-hosted)	Your database, your server
Export	Dataset export via CLI anytime	Direct DB access
Vendor dependency	API + Studio locked to Sanity	Core is open source; only Cloud is vendor-tied
Custom schema migration	GROQ + Sanity CLI	Direct SQL or Strapi migration scripts

Sanity's lock-in is real but often overstated. Your content is exportable as NDJSON at any time via sanity dataset export. The actual switching cost is rewriting your queries and remapping your schema — painful but not impossible. The Content Lake does mean you're trusting Sanity's uptime for production reads unless you cache aggressively.

Strapi's self-hosted path gives you complete data sovereignty. You own the Postgres cluster, you control backups, you can read the database directly if the API misbehaves. That matters in regulated industries, for clients with strict data residency requirements, or for teams that have been burned by SaaS price hikes. The trade-off is that you run the infra — patching, scaling, SSL, backups — unless you pay for Strapi Cloud.

When I reach for each one

I default to Sanity when the project has a non-technical editorial team, a rich media-heavy content model, or when the client's budget doesn't include DevOps overhead. The managed pipeline and Studio UX consistently reduce support requests from editors.

I recommend Strapi when the client has an internal DevOps team, a hard requirement to keep content data in their own infrastructure (GDPR jurisdiction, enterprise data policies), or when the content model is simple enough that GROQ's learning curve isn't worth it for a two-week engagement.

Strapi Cloud has improved Strapi's managed story considerably in 2025–2026, but it's still a younger managed offering than Sanity's, and the platform has less headroom for the kind of Studio customisation that agency projects often need at handoff.

Neither platform is universally better. The decision almost always comes down to: who operates the infrastructure, and how complex is your content graph.

Payload CMS vs Strapi in 2026: an honest head-to-head

Nayan Kyada — Sun, 21 Jun 2026 08:45:34 +0000

Payload CMS vs Strapi comes up constantly when teams want a self-hosted, open-source CMS they can actually own. Both have matured a lot since 2023, and both have made significant architectural moves heading into 2026 — so a comparison that was accurate two years ago is now largely wrong. Here is where they actually stand.

The fundamental architecture difference

Strapi is a standalone API server. You run it separately from your frontend, point your Next.js app at its REST or GraphQL endpoint, and manage content through a browser-based admin that lives on the Strapi process. The data layer supports SQLite, MySQL, and PostgreSQL. Strapi Cloud is the managed option; self-hosting on a VPS or containerised environment is straightforward but means you own the ops.

Payload started as a code-first CMS that collocates with your Next.js app — not beside it, but inside it. Payload 3.x runs as part of a Next.js project: the admin UI, the REST API, the GraphQL endpoint, and the local API all live in the same process and share the same TypeScript config. You get a /admin route baked into your Next.js app with zero separate deployment. Payload supports PostgreSQL (via Drizzle), MongoDB, and SQLite. There is no Payload-hosted cloud as of mid-2026; you deploy the whole app to Vercel, Railway, Fly, or bare metal.

That single architectural decision drives almost every other difference.

Admin UX and editor experience

Strapi's admin has been rebuilt iteratively since v4 and is polished. Non-technical editors feel at home quickly: a sidebar nav, a media library, collection views with filterable list tables, and a relationship picker that does not require understanding schemas. Strapi added a visual drag-and-drop layout builder (called the Content-Type Builder) years ago, and it remains the fastest way for a developer to prototype schema without touching code — though production schemas should be in code.

Payload's admin is React-based and customisable at a component level, but it looks and feels more developer-facing. The field UI is clean and functional. Complex nested arrays, tabs, and collapsible groups all render correctly. Where Strapi wins on approachability for non-technical editors, Payload wins on customisability: you can swap out any admin component, inject custom views, and write React hooks that run inside the admin panel without a plugin abstraction layer.

For content-heavy teams with junior editors, Strapi's admin is easier to hand off. For product teams where developers manage the CMS too, Payload's admin is more powerful.

APIs: REST, GraphQL, and Payload's local API

Both expose REST and GraphQL endpoints. Strapi's REST API follows predictable URL conventions and has a mature filter query language. GraphQL requires the GraphQL plugin installed — it is not on by default in Strapi v5.

Payload's local API is the real differentiator. Because Payload runs inside your Next.js process, you can call payload.find(), payload.findByID(), and payload.create() directly in React Server Components without an HTTP round trip. No network latency, no token management, no serialisation overhead.

// app/posts/[slug]/page.tsx
import { getPayload } from 'payload'
import config from '@payload-config'

export default async function PostPage({ 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]
  if (!post) notFound()
  return <article>{post.title}</article>
}

This pattern eliminates an entire network hop per request and means you get full TypeScript inference from the same config that defines your schema. Strapi cannot offer this because it runs out-of-process by design.

TypeScript config and migrations

Payload's schema is TypeScript all the way down. Collections, globals, fields, hooks, and access control are all defined in .ts files. TypeGen runs automatically and produces typed return values for every collection. There is no GUI-generated JSON schema sitting in a file you are not supposed to edit by hand — the code is the schema.

Strapi v5 improved its TypeScript story significantly: it generates types from your content types and the types are available in custom code. But the content type builder still generates JSON files under src/api/*/content-types/, and migrations are handled by a separate migration runner that feels bolted on compared to Payload's Drizzle-powered migration system, which generates SQL migration files you can inspect, commit, and run deterministically.

For teams that want schema-as-code with no JSON intermediary, Payload is clearly ahead. For teams that want GUI-driven schema building with optional TypeScript on top, Strapi is more ergonomic.

Plugins and ecosystem

Strapi has a larger plugin marketplace because it has been around longer and has more community adoption. SEO, i18n, sitemap, and media providers are available as first-party or community plugins. The internationalisation plugin is battle-tested.

Payload's plugin ecosystem is smaller but growing fast. Official plugins cover SEO fields, Lexical rich text, form builder, nested docs, and Stripe integration. Because Payload hooks are just functions, writing your own plugin is significantly simpler than the Strapi plugin architecture, which has its own folder conventions and bootstrap lifecycle.

Cost and total ownership

Factor	Payload CMS	Strapi
Licence	MIT	MIT (v4/v5 core)
Hosted option	None (self-deploy)	Strapi Cloud from ~$29/mo
Database	PostgreSQL, MongoDB, SQLite	PostgreSQL, MySQL, SQLite
Collocated with Next.js	Yes (same process)	No (separate service)
Schema format	TypeScript	JSON + generated TS
Local API (no HTTP)	Yes	No
Migration tooling	Drizzle migrations	Built-in migration runner
Admin customisation	Deep (component-level)	Moderate (extensions)
Plugin ecosystem	Smaller, growing	Larger, mature
Editor UX for non-devs	Functional, dev-focused	Polished, editor-friendly

Self-hosting either on a small VPS is roughly the same cost: you pay for compute, database, and storage. Strapi Cloud adds a recurring SaaS fee but eliminates ops. Payload on Vercel with a Neon PostgreSQL database can be genuinely cheap at low traffic — under $20/month for a modest content site.

Which one to pick

Choose Payload if your frontend is Next.js App Router, your team is TypeScript-first, and you want to eliminate the API network hop with the local API. It also wins for projects where schema-as-code and deterministic Drizzle migrations matter.

Choose Strapi if you need a managed cloud option without self-hosting, your editors are non-technical and need the most approachable admin UI, or you need a CMS that sits in front of multiple frontends (not just one Next.js app) and is genuinely framework-agnostic in its deployment.

Neither is wrong. But they have meaningfully different deployment philosophies, and that difference compounds over the life of a project.

How I set up Sanity Studio with live preview in Next.js App Router using Presentation

Nayan Kyada — Sat, 20 Jun 2026 08:02:23 +0000

Sanity's Presentation plugin is the cleanest live-preview setup I've shipped for editorial teams — editors click any text in the embedded iframe and land directly on the relevant field in Studio. Setting it up against Next.js App Router takes about two hours the first time; this post captures every non-obvious step so yours takes twenty minutes.

What Sanity Presentation actually does

Presentation is a Sanity Studio plugin that embeds your front-end URL in an iframe alongside the Studio editor. It uses @sanity/visual-editing on the Next.js side to attach data-sanity-* attributes to rendered elements. When an editor clicks a heading in the preview, Studio jumps to that document field. Under the hood it's built on @sanity/channels — a lightweight postMessage bus between the iframe and the parent Studio frame.

This is different from the older watch-mode preview pattern where you had a separate /api/draft route and a full page reload. With Presentation, GROQ queries re-run live as the editor types, with no reload.

Prerequisites

You need:

next ≥ 14.2 (App Router)
sanity ≥ 3.30 (Presentation is stable from 3.28 but 3.30 fixes a critical iframe CSP bug)
@sanity/visual-editing ≥ 2.1
@sanity/preview-kit ≥ 5.0 (for live GROQ on the Next.js side)

Install once:

npm i @sanity/visual-editing @sanity/preview-kit sanity@latest

Step 1 — Configure Presentation in sanity.config.ts

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

export default defineConfig({
  projectId: process.env.NEXT_PUBLIC_SANITY_PROJECT_ID!,
  dataset: process.env.NEXT_PUBLIC_SANITY_DATASET!,
  plugins: [
    structureTool(),
    presentationTool({
      // The origin of your Next.js dev or preview URL
      previewUrl: {
        origin:
          process.env.SANITY_STUDIO_PREVIEW_URL ?? 'http://localhost:3000',
        // Presentation will append ?sanity-preview-secret=<token> automatically
        // when the user enters draft mode from Studio.
        draftMode: {
          enable: '/api/draft-mode/enable',
        },
      },
    }),
  ],
})

The draftMode.enable path must be a route handler in your Next.js app that sets the Next.js draft mode cookie. Keep the secret out of the config — Presentation reads it from the URL param and validates server-side.

Step 2 — The draft mode enable route handler

// app/api/draft-mode/enable/route.ts
import { validatePreviewUrl } from '@sanity/preview-url-secret'
import { client } from '@/sanity/client' // your configured sanity client
import { draftMode } from 'next/headers'
import { redirect } from 'next/navigation'
import { type NextRequest } from 'next/server'

export async function GET(req: NextRequest) {
  const { isValid, redirectTo = '/' } = await validatePreviewUrl(
    // Pass a client with a read token — never the write token
    client.withConfig({ token: process.env.SANITY_API_READ_TOKEN }),
    req.url,
  )

  if (!isValid) {
    return new Response('Invalid secret', { status: 401 })
  }

  // next/headers draftMode() is synchronous in Next.js 15+
  ;(await draftMode()).enable()
  redirect(redirectTo)
}

A few things that bit me on real projects:

validatePreviewUrl makes a GROQ query to your Sanity project to confirm the secret exists as a document of type sanity.previewUrlSecret. Run npx sanity@latest manage → API → Preview URL Secrets to generate one, or use the CLI: npx sanity preview-url-secret create.
The read token needs viewer role minimum. Do not use the deploy token here.
In Next.js 15, draftMode() returns a Promise — add the await or you get a runtime error.

Step 3 — Add visual-editing overlays to your layout

The VisualEditing component from @sanity/visual-editing/next attaches the attribute listeners and opens the Studio postMessage channel. Render it only when draft mode is active:

// app/layout.tsx
import { draftMode } from 'next/headers'
import { VisualEditing } from '@sanity/visual-editing/next'

export default async function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  const { isEnabled } = await draftMode()

  return (
    <html lang="en">
      <body>
        {children}
        {isEnabled && <VisualEditing />}
      </body>
    </html>
  )
}

This is all you need for click-to-field navigation. Visual editing will auto-detect data-sanity-* attributes that Sanity's studioUrl helper injects when you use @sanity/preview-kit's live store.

Step 4 — Swap to a live GROQ store in draft mode

For real-time field updates as the editor types, replace your static sanity.fetch() calls with useLiveQuery from @sanity/preview-kit. This only needs to happen inside a client component boundary — all your RSC page shells stay server components.

The pattern I use: a LiveQueryProvider in a server component passes the initial data down, and a thin client component hydrates it live.

// app/(preview)/PreviewProvider.tsx  — client boundary
'use client'
import { LiveQueryProvider } from '@sanity/preview-kit'
import { client } from '@/sanity/client'

export function PreviewProvider({
  token,
  children,
}: {
  token: string
  children: React.ReactNode
}) {
  return (
    <LiveQueryProvider client={client} token={token} logger={console}>
      {children}
    </LiveQueryProvider>
  )
}

Wrap this around the page tree only when draftMode().isEnabled. Pass process.env.SANITY_API_READ_TOKEN from the server — it never reaches the client bundle because you're passing it as a prop from a Server Component into this Client Component, and React serialises it only for the initial render. The token is in the HTML source for draft-mode sessions, which is acceptable because those sessions are gated behind the secret.

Disabling draft mode

Add a /api/draft-mode/disable route that calls draftMode().disable() and redirects back. Wire a "Exit preview" button using a Server Action or a simple link to that route. Presentation also adds its own toolbar with an exit button, but having an independent escape hatch is worth the two extra lines.

Staging vs production

Set SANITY_STUDIO_PREVIEW_URL to your Vercel preview URL in the Studio's environment config. Because Vercel preview URLs change per branch, I set this in sanity.config.ts to fall back to window.location.origin when the env is absent — that way the deployed Studio on studio.yourproject.com previews against whatever domain the editor last manually loaded.

One gotcha: if your Next.js app sets a restrictive frame-ancestors CSP, the Presentation iframe will silently blank. Add frame-ancestors 'self' https://your-studio-domain.sanity.studio to the Content-Security-Policy header in next.config.ts. This is the most common reason Presentation appears broken on first deploy.

How I set up Sanity document-level permissions with role-based access control

Nayan Kyada — Fri, 19 Jun 2026 09:19:08 +0000

Sanity's permissions model is more powerful than most teams realise, and more often than not I see projects where every editor has full write access to every document type. That works until it doesn't — typically the moment a client's marketing intern can delete a product page. This post walks through how I set up document-level role-based access control (RBAC) in Sanity, and how that feeds into a Next.js App Router project.

Why document-level permissions matter

Sanity ships with three built-in roles: Administrator, Editor, and Viewer. For small teams that's fine. For anything with multiple brands, regions, or content teams — agencies building multi-tenant setups especially — you need tighter controls:

A regional editor should only write documents where region == 'eu'.
A contributor role should create drafts but never publish.
A read-only reviewer should see drafts in preview but never mutate.

Sanity's Roles API (available on Growth and Enterprise plans) lets you define custom roles with document-level GROQ filters. The Viewer and Editor roles at the org level stay as fallback; your custom roles sit on top.

Defining custom roles in the Sanity management API

Custom roles aren't configured in sanity.config.ts — they live in your project's settings on sanity.io/manage, or you can script them via the Management API. I prefer scripting so the config lives in version control.

Create a small Node script at scripts/upsert-roles.ts:

// scripts/upsert-roles.ts
import fetch from 'node-fetch'

const PROJECT_ID = process.env.SANITY_PROJECT_ID!
const TOKEN = process.env.SANITY_MANAGEMENT_TOKEN! // needs 'Administrator' scope
const DATASET = 'production'

const roles = [
  {
    name: 'eu-editor',
    title: 'EU Editor',
    description: 'Can create and edit EU-region documents only',
    grants: [
      {
        filter: `_type in ["post", "product"] && region == "eu"`,
        permissions: ['read', 'create', 'update'],
      },
      {
        // Allow reading all documents for cross-linking
        filter: `_type in ["post", "product"]`,
        permissions: ['read'],
      },
    ],
  },
  {
    name: 'contributor',
    title: 'Contributor',
    description: 'Can create and edit drafts, cannot publish',
    grants: [
      {
        filter: `true`, // all document types
        permissions: ['read', 'create', 'update'],
        // note: no 'publish' — Sanity treats publish as a separate capability
      },
    ],
  },
]

async function upsertRole(role: (typeof roles)[0]) {
  const url = `https://api.sanity.io/v2021-10-04/projects/${PROJECT_ID}/roles`
  const res = await fetch(url, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${TOKEN}`,
       'Content-Type': 'application/json',
    },
    body: JSON.stringify(role),
  })
  const json = await res.json()
  console.log(role.name, res.status, json)
}

for (const role of roles) {
  await upsertRole(role)
}

Run it once:

SANITY_PROJECT_ID=xyz SANITY_MANAGEMENT_TOKEN=sk... npx tsx scripts/upsert-roles.ts

The GROQ filter in grants is evaluated server-side by Sanity's API on every query and mutation. It is not a Studio-only UI restriction — the API itself enforces it. That's the key thing to understand: a rogue client making direct API calls still hits the same filter.

Restricting the Studio UI to match

The API enforcement is the source of truth, but it's good practice to reflect the restrictions in Studio so editors don't hit confusing 403s. Use the currentUser hook to conditionally hide or disable UI.

In sanity.config.ts you can scope a structure to show only the relevant document types based on the user's roles:

// sanity.config.ts (partial)
import { defineConfig } from 'sanity'
import { structureTool } from 'sanity/structure'
import { getCurrentUserRoles } from './studio/lib/getCurrentUserRoles'

export default defineConfig({
  projectId: process.env.NEXT_PUBLIC_SANITY_PROJECT_ID!,
  dataset: process.env.NEXT_PUBLIC_SANITY_DATASET!,
  plugins: [
    structureTool({
      structure: (S, context) => {
        const { currentUser } = context
        const roles = currentUser?.roles?.map((r) => r.name) ?? []
        const isEuEditor = roles.includes('eu-editor')
        const isAdmin = roles.includes('administrator')

        const postList = S.listItem()
          .title('Posts')
          .child(
            S.documentList()
              .title('Posts')
              .filter(
                isAdmin
                  ? '_type == "post"'
                  : '_type == "post" && region == "eu"',
              ),
          )

        return S.list()
          .title('Content')
          .items([
            postList,
            // other items
          ])
      },
    }),
  ],
})

The currentUser object is available synchronously in the structure callback from Sanity v3. The GROQ filter in .filter() is sent to the API, so it stacks on top of whatever role-level filter already applies — meaning an EU editor will only ever see EU documents regardless of what the structure filter says.

Connecting roles to Next.js

On the Next.js side, document-level permissions are largely invisible because you're querying with a read-only token that has no user context. The RBAC I've described is for Studio users — authenticated editors.

Where this matters in Next.js is in Draft Mode and preview routes. If you're using a preview handler that fetches drafts on behalf of an authenticated user (rather than a bot token), you'd pass the user's Sanity session token and the API would apply their role filters automatically.

More commonly, you'll want to validate in your route handler that the requesting editor is authorised before handing back a preview URL:

// app/api/preview/route.ts
import { NextRequest, NextResponse } from 'next/server'
import { draftMode } from 'next/headers'
import { client } from '@/sanity/lib/client'

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

  if (secret !== process.env.SANITY_PREVIEW_SECRET) {
    return NextResponse.json({ message: 'Invalid token' }, { status: 401 })
  }

  // Verify the document exists at all before enabling draft mode
  const exists = await client.fetch(
    `count(*[_type == $type && slug.current == $slug]) > 0`,
    { type: docType, slug },
  )

  if (!exists) {
    return NextResponse.json({ message: 'Document not found' }, { status: 404 })
  }

  const dm = await draftMode()
  dm.enable()

  return NextResponse.redirect(new URL(`/${docType}/${slug}`, req.url))
}

This is thin — it just verifies the secret and document existence. If you need user-level gating (only let this editor preview their region's documents), add a Sanity user lookup against the management API before enabling draft mode.

What you actually get

After wiring this up: EU editors see and can only mutate EU documents in both the API and Studio, contributors can draft but not publish (Sanity's publish action checks for the publish permission in the role grant and surfaces an error if absent), and previewing drafts is still a single-secret gate at the Next.js layer. The system is enforced at the API, mirrored in the Studio UI, and leaves the public Next.js frontend untouched.

The one thing to watch: Sanity's GROQ filter in a role grant runs against the full document, including the drafts. prefix documents. Make sure your region field is set before the first save, or drafts won't appear even to the correct role until a region is chosen.

How I migrated a large Next.js project from Tailwind CSS v3 to v4

Nayan Kyada — Thu, 18 Jun 2026 09:00:21 +0000

Tailwind CSS v4 migration in a Next.js project is not a one-command upgrade. I ran it on a mid-size marketing site — around 180 components, a design system with custom tokens, and a Sanity-powered content layer — and it took a full day plus a few hours of cleanup. Here is exactly what I changed and where it got awkward.

What actually changed between v3 and v4

The headline change is that the config file is gone. In v4 there is no tailwind.config.ts. Your design tokens live in CSS using @theme inside your global stylesheet. PostCSS integration also changed: v4 ships its own dedicated PostCSS plugin rather than piggybacking on tailwindcss as a generic plugin.

A handful of utilities were renamed or removed. The bg-opacity-* and text-opacity-* shorthand classes are gone — they now map to the slash syntax (bg-blue-500/50). The transform and filter utility stubs that v3 required to enable GPU compositing are also removed because v4 applies those automatically. The ring default width changed from 3px to 1px.

On the positive side: v4 is dramatically faster at build time (the Rust engine replaces the Node scanning pass), and the CSS output on a large project I measured dropped by ~18% after removing now-redundant @layer scaffolding.

Step 1 — update packages and swap the PostCSS plugin

Remove the old packages and install the new ones:

npm remove tailwindcss postcss autoprefixer
npm install tailwindcss@^4 @tailwindcss/postcss@^4

Then update postcss.config.mjs. The old config used tailwindcss as a plugin key. V4 uses @tailwindcss/postcss:

// postcss.config.mjs
/** @type {import('postcss-load-config').Config} */
const config = {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

export default config;

Note: autoprefixer is no longer needed as a separate entry — v4 bundles its own prefix handling. Leaving it in does not break anything but it adds a redundant pass.

Step 2 — move config into CSS with @theme

Delete tailwind.config.ts. Open your globals.css (or whatever your root stylesheet is) and move tokens into an @theme block. The @import "tailwindcss" line replaces the old @tailwind base/components/utilities directives.

/* app/globals.css */
@import "tailwindcss";

@theme {
  --color-brand-500: oklch(62% 0.19 250);
  --color-brand-600: oklch(55% 0.21 250);
  --color-surface: oklch(98% 0.005 250);

  --font-sans: 'Inter Variable', ui-sans-serif, system-ui, sans-serif;
  --font-mono: 'JetBrains Mono', ui-monospace, monospace;

  --radius-card: 0.75rem;
  --radius-button: 0.375rem;

  --spacing-section: 5rem;

  --breakpoint-3xl: 1920px;
}

Every CSS custom property inside @theme becomes a Tailwind utility automatically. --color-brand-500 generates bg-brand-500, text-brand-500, border-brand-500, and so on. You do not need to extend anything.

The one gotcha: if you had theme.extend.colors keyed with camelCase (e.g. brandPrimary) your class names were bg-brandPrimary. In v4 the property name drives the class name directly, so you want kebab-case keys (--color-brand-primary → bg-brand-primary). I had about 30 class references to find-and-replace across the codebase for this alone.

Step 3 — handle dropped and renamed utilities

Run the project and check the browser console and your CI visual diff. The places that broke for me:

Opacity utilities. Any bg-opacity-* or text-opacity-* class throws no error — they just silently produce no CSS. I ran a grep to find them:

grep -r 'bg-opacity\|text-opacity\|border-opacity' ./components ./app --include='*.tsx'

Replace with the slash syntax: bg-blue-600 bg-opacity-75 becomes bg-blue-600/75. This is cleaner anyway.

Ring width default. Any component using bare ring (without a width modifier) now renders a 1px ring instead of 3px. Most focus rings looked too thin after migration. I added ring-2 or ring-3 explicitly wherever the design required the heavier ring.

Transform and filter stubs. Removing transform from a class list should be fine — v4 no longer requires it. But if any component was conditionally toggling transform to enable/disable GPU promotion, that logic is now a no-op and can be deleted.

Arbitrary values with CSS variables. In v3 you could write bg-[var(--color-brand)]. This still works in v4 but if the variable is inside @theme, you can just use the generated utility directly and remove the arbitrary value syntax.

Step 4 — fix content path scanning

V4 auto-detects content paths by scanning the project from the stylesheet's directory. For most Next.js projects this works out of the box because globals.css sits inside app/ which is a sibling to components/. If you have a monorepo or unconventional folder layout and classes are getting purged incorrectly, you can hint explicitly:

/* app/globals.css */
@import "tailwindcss";
@source "../packages/ui/src";
@source "../packages/marketing/src";

@theme { … }

@source is the v4 replacement for the content array in tailwind.config.ts.

Rough edges I actually hit in production

Turbopack + v4 HMR. On Next.js 15 with --turbopack, hot reload of the @theme block was occasionally slow (2–3 second delay) compared to changing a component class. Not a showstopper but noticeable during token-heavy design iteration. Webpack mode was snappier for this particular workflow.

Third-party component libraries. I use Radix primitives with a custom Tailwind-based design system. The components themselves were fine, but a ShadCN-style component file that imported its own tailwind-merge config needed the class name mapping updated to match the new token names.

PostCSS plugin order. I had cssnano in the PostCSS config for production builds. Placing it after @tailwindcss/postcss worked correctly; placing it before caused some @theme variables to be stripped in the minification pass. Always put @tailwindcss/postcss first.

@apply with v3-only utilities. Any @apply bg-opacity-50 inside a CSS file throws a build error in v4 because the utility no longer exists. These are easier to track down than JSX class names because the build fails loudly.

Was it worth it

For this project: yes. Build time for the CSS pass went from ~1.1s to ~180ms. The stylesheet size dropped from 42 kB to 34 kB (brotli: 8.2 kB to 6.7 kB). The CSS-based config is actually nicer to work with once you stop reaching for the old config file — design tokens are colocated with where they are consumed rather than in a separate JS tree.

The migration is mechanical and grep-able. Budget half a day for a medium-size project, a full day if you have a large design token surface or heavy use of the opacity shorthand utilities.

React 19 new hooks in Next.js App Router: what actually changed for me

Nayan Kyada — Wed, 17 Jun 2026 09:17:26 +0000

React 19's new hooks — useFormStatus, useActionState, and use() — aren't just quality-of-life additions. In the context of the Next.js App Router and Server Actions, they change the fundamental shape of how I write forms and async UI. Here's what that looks like in practice, without the hype.

The problem these hooks are solving

Before React 19, building a form that called a Server Action and reflected loading/error state required a fair amount of ceremony. You'd reach for useState + useTransition, manually thread the pending flag down to a submit button, and handle error returns with your own convention. It worked, but it was boilerplate you wrote every time.

React 19 formalises that pattern into three primitives. I'll go through each one with a concrete before/after.

useActionState replaces the useState + useTransition combo

Before React 19, a typical contact form Server Action pattern looked like this:

// app/contact/page.tsx (before React 19)
'use client'
import { useTransition, useState } from 'react'
import { submitContact } from './actions'

export default function ContactForm() {
  const [error, setError] = useState<string | null>(null)
  const [success, setSuccess] = useState(false)
  const [isPending, startTransition] = useTransition()

  function handleSubmit(e: React.FormEvent<HTMLFormElement>) {
    e.preventDefault()
    const formData = new FormData(e.currentTarget)
    startTransition(async () => {
      const result = await submitContact(formData)
      if (result.error) setError(result.error)
      else setSuccess(true)
    })
  }

  return (
    <form onSubmit={handleSubmit}>
      {error && <p>{error}</p>}
      {success && <p>Sent!</p>}
      <input name="email" type="email" />
      <button disabled={isPending}>{isPending ? 'Sending…' : 'Send'}</button>
    </form>
  )
}

With useActionState this collapses significantly:

// app/contact/page.tsx (React 19)
'use client'
import { useActionState } from 'react'
import { submitContact } from './actions'

type State = { error?: string; success?: boolean }
const initialState: State = {}

export default function ContactForm() {
  const [state, formAction, isPending] = useActionState(submitContact, initialState)

  return (
    <form action={formAction}>
      {state.error && <p>{state.error}</p>}
      {state.success && <p>Sent!</p>}
      <input name="email" type="email" />
      <button disabled={isPending}>{isPending ? 'Sending…' : 'Send'}</button>
    </form>
  )
}

The Server Action now receives (prevState: State, formData: FormData) as its signature. The hook owns the pending flag and state transitions. I no longer have to wire e.preventDefault() or startTransition manually — the action prop on <form> handles that natively when given a function.

One thing worth noting: your Server Action signature must change to accept prevState as the first argument when used with useActionState. If you're migrating existing actions, that's the breaking change to watch for.

useFormStatus pushes pending state down without prop drilling

The submit button sitting inside a form has no way of knowing the form is pending unless you pass the flag down as a prop. useFormStatus solves this by reading the parent form's status from context.

// components/submit-button.tsx
'use client'
import { useFormStatus } from 'react-dom'

export function SubmitButton({ label }: { label: string }) {
  const { pending } = useFormStatus()
  return (
    <button type="submit" disabled={pending}>
      {pending ? 'Working…' : label}
    </button>
  )
}

This component can now be dropped into any form that uses a Server Action — or useActionState — and it automatically reflects pending state. No prop, no context setup, no wiring. It reads the nearest ancestor <form> that has a pending action.

The constraint is real: useFormStatus only works inside a component that is rendered as a child of the form, not inside the same component that renders the form. I've seen people trip on this. The fix is always the same — extract the button to its own component.

use() for async data and context unwrapping

use() is the strangest of the three because it does two different things depending on what you pass it.

For promises, it lets you pass a promise from a Server Component down to a Client Component and unwrap it there with Suspense. This is the pattern that replaces some useEffect-based data fetching:

// app/dashboard/page.tsx (Server Component)
import { Suspense } from 'react'
import { fetchUserStats } from '@/lib/data'
import { StatsPanel } from './stats-panel'

export default function DashboardPage() {
  // Not awaited — passes the promise down
  const statsPromise = fetchUserStats()
  return (
    <Suspense fallback={<p>Loading stats…</p>}>
      <StatsPanel promise={statsPromise} />
    </Suspense>
  )
}

// app/dashboard/stats-panel.tsx (Client Component)
'use client'
import { use } from 'react'
import type { UserStats } from '@/lib/data'

export function StatsPanel({ promise }: { promise: Promise<UserStats> }) {
  const stats = use(promise) // suspends until resolved
  return <div>{stats.totalOrders} orders</div>
}

The Server Component starts the fetch, hands off the promise, and the Client Component suspends. The practical benefit over useEffect is that the fetch starts server-side and the waterfall is shorter.

For context, use(MyContext) is just useContext(MyContext) with one meaningful difference: you can call it conditionally. That matters in practice when you have context that only exists in certain render paths and you want to avoid the rules-of-hooks gymnastics.

What this means for how I structure App Router projects

These three hooks push me toward a cleaner separation. Server Actions stay as plain async functions with a typed return — no client state logic bleeds in. Client Components that render forms are slimmer because they don't own the pending/error state machinery anymore. And small components like SubmitButton can be genuinely reusable without receiving one-off props.

The shift I haven't fully resolved: useActionState pairs state and action together, which is convenient but means the action is tightly coupled to that particular state shape. If the same Server Action is called from two forms with different UX needs, I end up duplicating or wrapping. That's a real trade-off, not a deal-breaker, but worth knowing before you adopt this pattern everywhere.

Overall, these hooks feel like React acknowledging that Server Actions are a first-class pattern and building the client-side ergonomics to match. The before/after diff is substantial enough that I've started migrating existing forms as I touch them.