Next.js boilerplate with Sanity blog

Never let a Sanity API token reach the browser

• SANITY_API_READ_TOKEN is read in exactly one place: sanity/lib/client.ts, where it configures draftClient. Nothing else reads process.env for it.
• draftClient and sanityFetch are server-only. Do not import them from a file that carries "use client", or from anything such a file imports. If a client component needs content, fetch it in the server component above and pass it down as props.
• Never rename the variable to NEXT_PUBLIC_SANITY_API_READ_TOKEN to "make it work" in a client component. That is not a fix, it is a publication.
• The token this repo uses is a Viewer token. If a task seems to need write access from the app, stop: content is written in the Studio by authenticated editors. An Editor or Deploy token in a web app is a stranger with edit rights the moment anything leaks it.
• The publish webhook and the preview link are authenticated with SANITY_REVALIDATE_SECRET, compared in constant time. Do not add an unauthenticated revalidate route "for testing".

Draft mode is for editors, and it says so

• sanityFetch checks draftMode() on every read. In draft mode it uses the token client, the drafts perspective and no caching; otherwise it uses the anonymous CDN client with tags.
• Any page that can render draft content shows <DraftBanner />. An editor who forgot they enabled preview three days ago will otherwise report bugs about content nobody else can see.
• The enable route validates the secret and resolves the slug against the dataset before redirecting. Redirecting to a path taken from the query string is an open redirect.
• Leaving draft mode is a POST. A GET that mutates state gets fired by link prefetchers, mail scanners and chat unfurlers.
• Reads go through this repo's sanityFetch, not defineLive from next-sanity/live. defineLive, <SanityLive /> and defineEnableDraftMode (next-sanity/draft-mode) are one set built for the Presentation tool. Adding one of them alone gives you two read paths and two draft-mode routes.

Import from the current majors

• next-sanity 13, sanity 6, @sanity/image-url 2, @portabletext/react 8.
• createClient and defineQuery from next-sanity. NextStudio, metadata and viewport from next-sanity/studio. structureTool from sanity/structure, visionTool from @sanity/vision, defineCliConfig from sanity/cli.
• createImageUrlBuilder and SanityImageSource from @sanity/image-url. The default export is deprecated and @sanity/image-url/lib/types/types no longer exists.
• sanity.config.ts keeps "use client". Without it the Studio lands in the server graph and next build fails to compile /studio.
• next-sanity 13 ships its own @portabletext/react 7 and @sanity/client 7. Sanity 6 uses 8 of both, so both majors install side by side. That is expected, not a broken lockfile. Import PortableText and PortableTextComponents from @portabletext/react (8), never from the next-sanity re-export, so both come from one copy.
• Do not add @sanity/client as a dependency or import from it. Take the client from createClient and its types from next-sanity, which re-exports them from the copy it actually uses.

Portable Text renders with design tokens only

• Every mapping in src/components/sanity/portable-text.tsx uses token utilities: text-ink, text-body, text-muted, bg-surface-card, bg-surface-strong, border-hairline, rounded-*, the text-title-* and text-body-* scale, p-* and gap-* spacing. No palette classes, no hex, no inline colours.
• Every block type, style, mark and annotation in sanity/schemas/block-content.ts has a mapping. An unmapped type renders as an unstyled paragraph and nobody notices until a reader does.
• Images go through <SanityImage>, which requests an exact width from the image CDN and uses the LQIP from the projection as a blur placeholder. Never render asset->url directly: that is the original upload, at full size.
• alt is required in the schema; pass it through rather than defaulting it to the title.

Caching is explicit

• Every cached read carries tags: the collection (post) and the document (post:<slug>). The webhook invalidates exactly those.
• revalidateTag(tag, "max"): the two-argument form. The single-argument form is deprecated and behaves like { expire: 0 }, which makes the next visitor wait for a fresh render instead of serving them the stale page.
• Do not sprinkle export const revalidate on pages as well. Time-based revalidation on top of webhook invalidation gives you rebuilds you did not ask for and a cache you cannot reason about.

Schema changes are commits, not Studio clicks

• Document and object types are defined in sanity/schemas/ with defineType / defineField. The Studio at /studio renders that schema; it has no way to change it, and nothing you do in the browser alters what is committed here.
• Every schema change goes through the normal review path: branch, diff, pull request. "I added a field in the Studio" is not a thing that can happen, and if someone believes it did, they edited a file and did not commit it.
• Adding a field to a document type is only step one. The field is invisible until a projection in sanity/lib/queries.ts selects it and a renderer displays it. Ship all three together or ship none of them.
• Renaming or deleting a field does not migrate existing documents. Sanity is schemaless underneath: old documents keep the old key until something rewrites them. Plan a migration script (bun run sanity with a mutation) before you delete anything that has content in it.
• Slugs are the public URL. Treat a published slug.current as immutable and add a redirect rather than editing it.
• Validation belongs in the schema, not in the renderer: rule.required(), rule.max(160), required alt text on every image. A rule in the schema is enforced for every editor on every document; a check in a component is enforced for the one page you remembered.

Every query is in sanity/lib/queries.ts

• No client.fetch("*[...]") inside a page, a component or a route handler. Queries are exported from one file, wrapped in defineQuery, and imported by name.
• One file means a schema rename breaks in one place, bun run sanity:typegen can generate result types for exactly this list, and over-fetching is visible in review because the projections sit next to each other.
• Every read goes through sanityFetch in sanity/lib/fetch.ts. It picks the right client for draft mode and attaches the cache tags the webhook invalidates. A raw client.fetch in a page is a read nobody can revalidate. The one legitimate exception is generateStaticParams, which runs at build time where draftMode() cannot be called.

Projections, not *

• Always project explicitly: { _id, title, "slug": slug.current }. A bare *[_type == "post"] returns every field of every matching document, including bodies and drafts of fields you have forgotten about, and it grows silently as the schema grows.
• Never select body in a list query. Portable text is the largest field on a post, and an index page needs none of it.
• Dereference in the query, not in a loop: "author": author->{name} and "categories": categories[]->title. Fetching a list and then fetching each reference is an N+1 with a network hop per row.
• Bound every list with a slice ([0...$limit]) and order it explicitly. Without | order(...) the result order is not guaranteed to be stable.
• Filter drafts out of public queries with !(_id in path("drafts.**")). The published perspective usually handles it, but a query used with a token does not.