ChaiBuilder is optimized for content-heavy, public-facing sites: pages are static once built, and edits go live by invalidating exactly what changed. This page explains the cache layers and the publish-to-live pipeline, so you can reason about freshness on any hosting target.

The rendering model in one pass

1. No build-time page generation. Deploys are fast because pages are not pre-rendered at build time.
2. Built on first visit. The first request to a page renders it server-side and stores the result in the Next.js ISR cache. Subsequent visitors get the cached page.
3. Invalidated on publish. Publishing in the builder revalidates that page's cache entries - the next visitor triggers a rebuild and gets the new version. No redeploy, no full rebuild.

This is standard Next.js SSG + ISR (the public catch-all route is force-static), so every host that supports Next.js caching supports it - Vercel natively, Node servers via the on-disk cache, Cloudflare via the OpenNext incremental cache.

What gets invalidated when

Cache entries are tagged, and every content operation reports which tags and paths it touched. After each builder action, the affected tags and paths are revalidated:

You do	What revalidates
Publish a page	that page's path and cache tags
Change site settings / theme	the site-wide settings tag, plus the page layout tree
Publish a CMS item (e.g. a blog post)	pages rendering that collection's content
Publish a partial (shared header/footer)	pages using that partial

CMS-driven invalidation comes from the starter's Payload wiring: collections listed in the ChaiBuilder plugin's revalidateCollections (the starter includes its content collections) revalidate their dependent pages on change. Add your own collections there when custom content should refresh pages that render it.

Draft mode is never cached

Preview uses Next.js draft mode: while previewing, data is fetched fresh per request (a request-scoped memory cache prevents duplicate queries inside one render, but nothing persists). Editors always preview live data; the persistent cache and CDN are only in the published-visitor path.

Manual revalidation

The starter exposes a revalidation route for cases where content changes outside the builder - an external system writing to your database, or a script. The route is protected by a bearer token: set REVALIDATE_TOKEN in your environment and send it on every request. When the token is unset, the route is disabled and every request gets a 401.

curl -X POST https://www.example.com/admin/api/revalidate \
  -H "Authorization: Bearer $REVALIDATE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"paths": ["/pricing", "/blog/my-post"], "tags": []}'

It accepts paths and/or tags (arrays or comma-separated strings) and revalidates each. Generate the token like any secret (openssl rand -hex 32) and store it wherever the calling system keeps its credentials.

Data-layer caching for custom code

Custom blocks and data providers run server-side and are not cached by default - keep them fast or cache them. The pattern the platform itself uses:

• Request-level - memoize within one render, so a value used by five blocks is fetched once.
• Persistent - cache shared, public queries across all visitors with cache tags, then revalidate those tags when the underlying data changes.
• Draft mode automatically downgrades persistent caching to request-level, so previews stay fresh.

When writing custom data fetching, follow the same shape: tag your cached queries, and have whatever mutates the data revalidate those tags (via the route above or revalidateTag in your own server code).

Putting a CDN in front

The ISR cache already makes origin responses cheap, and platform CDNs (Vercel, Cloudflare) integrate with revalidation automatically. If you add an external CDN in front of a Node deployment, be careful with HTML caching: the CDN does not know when you publish. Safe default - let the CDN cache immutable assets (/_next/static, media URLs) and pass HTML through to the origin, which serves it from the ISR cache anyway.

Troubleshooting

• Published change not visible - check you published (not just saved), then hard-refresh to rule out browser cache. On Node, confirm the process can write to .next (the ISR cache lives there).
• Stale content behind an external CDN - your CDN is caching HTML; exclude HTML or purge on publish.
• Custom block shows stale data - its data source changed without a matching revalidation; wire the mutation to the revalidate route or tag.
• Everything rebuilds after deploy - expected; a new deployment starts with an empty ISR cache and pages rebuild on first visit.

Related

• Rendering Model - the conceptual view.
• Hosting Overview - cache support per target.
• Preview & Publish - the editor-side workflow.