I audited our CMS and 86% of our articles were invisible. A Sanity gotcha.

A week ago I ran a routine count on our Sanity dataset, expecting maybe a 5% gap between drafts and published articles. The result was 33 published, 253 drafts. 86% of the content I thought was on our site wasn't there. The bug had been silently shipping for the entire 9-day life of the project.

This post is the postmortem. It is specifically about Sanity, but the underlying gotcha (a CMS client default that disagrees with what you actually want at read time) applies to any headless setup.

The setup

I run Fax Office 1987, a small daily editorial publication. Next.js 15 App Router, Sanity for the CMS, Inngest for the dispatch pipeline. The editor (me) gets a review email for each AI-assisted draft and approves or rejects via a link. Approval was supposed to make a piece appear at /dispatch/<slug>.

The review route handler looked like this:

const next = action === 'approve' ? 'approved' : 'rejected'
await sanity
  .patch(id)
  .set({ reviewStatus: next, reviewedAt: new Date().toISOString() })
  .commit()

Clean. Set the flag, return the HTML confirmation page. Done.

And separately, the public site read articles like this:

const sanity = createClient({
  projectId,
  dataset,
  apiVersion: '2024-10-01',
  useCdn: false,
  token: process.env.SANITY_WRITE_TOKEN, // we use a token so private-read works
})

export const ARTICLES_QUERY = `
  *[_type == "article"
      && defined(slug.current)
      && (reviewStatus == "approved" || !defined(reviewStatus))
    ]
    | order(publishedAt desc) { ... }
`

For 9 days I thought this worked. Approve emails arrived, I clicked approve, the confirmation page said "the piece is now visible on the site." It wasn't.

The audit

I ran a per-status count:

const r = await client.fetch(`{
  "published":      count(*[_type=="article" && !(_id in path("drafts.**"))]),
  "draft_approved": count(*[_type=="article" && _id in path("drafts.**") && reviewStatus=="approved"]),
  "draft_pending":  count(*[_type=="article" && _id in path("drafts.**") && reviewStatus=="pending"]),
  "draft_rejected": count(*[_type=="article" && _id in path("drafts.**") && reviewStatus=="rejected"])
}`)

Result:

{
  "published":       33,
  "draft_approved": 227,
  "draft_pending":    7,
  "draft_rejected":  19
}

227 drafts marked approved. All of them had their reviewStatus flag set correctly. None of them were visible to readers.

Root cause #1: perspective default

Sanity documents have two layers. A draft sits at drafts.<id>, the published version sits at <id>. Both can coexist for the same logical document. When you fetch with a token, the default perspective overlays the draft on top of the published version and returns whichever exists. For an editorial site running with a token (because the dataset is in private-read mode for our use case), this is the wrong default. We always want to read the published version on the public site, never the draft.

Without perspective: 'published' set on the client, a draft document with reviewStatus == "approved" would pass our GROQ filter and get served to readers under the same slug as its published twin. We never noticed because the in-progress drafts were never published to begin with: the bug below kept them stuck.

Fix:

export const sanity = projectId
  ? createClient({
      projectId,
      dataset,
      apiVersion: '2024-10-01',
      useCdn: false,
      token: process.env.SANITY_WRITE_TOKEN,
      perspective: 'published', // <-- the one-line fix
    })
  : null

Belt-and-suspenders, every public GROQ query also gained a filter:

const NO_DRAFTS = `!(_id in path("drafts.**"))`

So even if a future caller built an ad-hoc client without the perspective set, the query itself would still hide drafts.

Root cause #2: the approve handler

After the perspective fix, the published count was still 33. The 227 approved drafts were still drafts, just with a flag set.

Reading the approve handler again with the perspective context in mind:

await sanity.patch(id).set({ reviewStatus: 'approved', ... }).commit()

This patches the draft document. It does not promote it. The published version under the bare id never gets created. From the public site's point of view, nothing changed.

The standard Sanity draft-promotion idiom is:

if (next === 'approved' && id.startsWith('drafts.')) {
  const publishedId = id.replace(/^drafts\./, '')
  const draft = await sanity.getDocument(id)
  if (draft) {
    const { _id, _rev, _createdAt, _updatedAt, ...rest } = draft as any
    await sanity.createOrReplace({
      ...rest,
      _id: publishedId,
      _type: 'article',
      reviewStatus: 'approved',
      reviewedAt: new Date().toISOString(),
    })
    await sanity.delete(id)
  }
}

Fetch the full draft, write it under the published id (strip the drafts. prefix), delete the draft. Sanity treats the result as published. The reject path still patches in place because rejected items stay as drafts on purpose: kept as a record, hidden from readers.

Backfill

That fixes new approvals. The 227 already in the backlog still needed promoting. A one-time script that walks every approved draft and applies the same promotion logic:

const drafts = await client.fetch(
  `*[_type == "article" && _id in path("drafts.**") && reviewStatus == "approved"]
    | order(_createdAt asc)`,
)

for (const draft of drafts) {
  const publishedId = draft._id.replace(/^drafts\./, '')
  // skip if a published twin already exists; don't clobber manual edits
  const existing = await client.fetch(
    `*[_id == $id][0]{ _id }`,
    { id: publishedId },
  )
  if (existing) continue

  const { _id, _rev, _createdAt, _updatedAt, ...rest } = draft
  await client.createOrReplace({ ...rest, _id: publishedId, _type: 'article' })
  await client.delete(draft._id)
}

Ran it against production. 227 promoted, 0 errors. Published count moved from 33 to 260. Sitemap discovered URLs went from a couple dozen to 293.

Followed up with an IndexNow bulk ping so Bing, Yandex, and the consortium would crawl the new URLs without waiting for sitemap re-discovery. Single POST, 289 URLs, accepted in one shot.

The takeaway

The Sanity perspective default is not a bug. The docs are clear. The mistake was a blind spot: when you write code that uses a token for read operations (because your dataset is private-read), you have to actively pick a perspective. Otherwise you get whichever overlay Sanity decided to give you, which for a public website is rarely what you want.

The deeper lesson: I had two bugs that combined into invisible content. Either alone would have been visible. Together they hid the site from itself. A monthly audit catches this kind of compounding silently-fails-but-works-anyway state.

Code: the fix landed in two commits on the Fax Office 1987 repo. If you run Sanity and your dataset is private-read, the perspective: 'published' line might be the highest-leverage one-character change you ship this month.

推荐订阅源

DEV Community