#Caching and Revalidation
Cache server data with tags and revalidate windows, choose a render mode, and invalidate ISR pages on demand with revalidatePath and revalidateTag.
Krate caches request-time work in three places:
| Cache | Holds | Lives in |
|---|---|---|
| ISR page cache | The rendered body of each ISR page variant (route + params + query) | SSR renderer (one per worker), or a shared cache |
| Region cache | Rendered dynamic regions (Suspense/runtime components, Go regions) | SSR renderer and Go host |
| Data cache | unstable_cache results and fetch responses requested with cache options |
Each server process (renderer, Node API sidecar, Go host for QuickJS routes), or a shared cache |
@krate/runtime/cache (also re-exported from @krate/runtime/server) is the
API for all three. It mirrors next/cache.
import { revalidatePath, revalidateTag, unstable_cache, unstable_noStore } from "@krate/runtime/cache";#What keys a cached entry
An ISR page is cached per route + params, plus only the query keys its render read
(searchParams, useSearchParams-style accessors): /blog?utm_source=x and a
random ?zz=1 share the entry of /blog unless the page looks at them, and a
page that enumerates the query is keyed by all of it. Regions work the same way,
for async server components and for runtime component bundles alike: the render
sees props.query through a view that records the keys it touches. Until a render
has shown what a page or region reads, a request that carries a query renders
instead of being answered from the cache (a restart, or an evicted record, costs
one render), so an entry is never matched to a query it was not made for.
The caches are bounded (ssr.maxCacheSize, 512 by default) with a segmented LRU:
a new entry starts in a probation segment and is promoted by its first hit, so a
client requesting thousands of one-off variants (any slug renders on an open
[param] route) only churns probation and cannot flush the pages and regions that
were requested twice. Unknown params still render; nothing 404s because of the
cache.
A Go region (*.runtime.go with // krate:revalidate) is keyed on what the
component read of its kr.Request: r.Header(name), r.Cookie(name),
r.QueryValue(name) and r.Param(name) record the names they were asked for (like
the Vary header of a response), and the entry is keyed on the values of those
names only. A cookie or header the component never reads cannot split the cache,
and one it reads always does, so two visitors with different cookies never share a
render. A component that reads the Headers, Query, Params, Method or URL
fields, or passes the Request to another function, cannot be recorded: its
renders are keyed on the whole request (every header included, so only an
identical request hits). A component without a kr.Request parameter shares one
entry.
#Choosing a render mode
A page picks its mode with the config object or with Next.js-style segment
exports:
| Export | Mode |
|---|---|
export const revalidate = 60 |
ISR, regenerated every 60 seconds |
export const revalidate = 0 |
SSR (rendered per request) |
export const revalidate = false |
Static (SSG), cached indefinitely |
export const dynamic = "force-dynamic" |
SSR (wins over revalidate) |
export const dynamic = "force-static" or "error" |
Static, or ISR when revalidate = N is also set |
export const dynamic = "auto" |
No effect |
export const config = { isr: true, revalidate: 60 } |
ISR (the config object wins over the segment exports) |
revalidate must be a constant number of seconds (60 * 60 is folded) or
false. Any other value, and any other dynamic string, is reported as
warning KR8601 and ignored.
When a page states no mode, Krate looks at how the page and the local modules it imports read data:
fetch(url, { cache: "no-store" }),{ next: { revalidate: 0 } }orunstable_noStore()make the page SSR.{ next: { revalidate: N } }orunstable_cache(fn, keys, { revalidate: N })make it ISR with the smallestN.- Tags alone (
{ next: { tags: [...] } },unstable_cache(..., { tags })) make it ISR that stays cached until a tag or path is revalidated.
Only code that runs on the server counts. A fetch in a "use client" module
(or a module only client components import), in a useEffect/onMount
callback, or in an onClick-style event handler runs in the browser and never
changes how the page renders.
The build prints the inferred mode (posts.tsx -> isr (tagged data read)). A
page that is pinned static (force-static, revalidate = false,
output: "static") but reads tagged, timed or no-store data gets warning
KR8602: its HTML is baked once and nothing can refresh it.
#The Cache-Control header of a page
A page rendered per request answers with Cache-Control: no-store unless
something set the header first. A Cache-Control that middleware sets
(NextResponse.next({ headers }) or response.headers.set(...)) or that a
headers rule in krate.config matches is kept, so an app can let a CDN cache
a request-time page:
export function middleware() {
const res = NextResponse.next();
res.headers.set('Cache-Control', 'public, s-maxage=60');
return res;
}An ISR page gets public, s-maxage=<revalidate> by default and the same rule
applies. Krate keeps no-store where caching would be wrong: error, 404 and
403 pages, a 503 while the renderer is down, an ISR render that read request
state such as cookies or headers (private, no-store), and server action
responses. The rule is the same in krate serve and on the Cloudflare, Vercel,
Netlify and node targets.
On Cloudflare, deploy.cloudflare.cache: true stores such responses in
caches.default, and a fetch wrapper in src/cloudflare.ts can do your own
caching. See Edge cache for SSR pages.
#Caching data
#fetch options
Inside server code (page renders, API routes, server actions) fetch accepts
the Next.js cache options:
export default async function Posts() {
const res = await fetch("https://api.example.com/posts", {
next: { tags: ["posts"], revalidate: 300 },
});
const posts = await res.json();
return <ul>{posts.map((p) => <li>{p.title}</li>)}</ul>;
}next.tagsare recorded on the page's ISR entry, sorevalidateTag("posts")purges the page.next.revalidate: Ncaches the response for N seconds;cache: "force-cache"ornext.revalidate: falsecache it until invalidated.cache: "no-store"ornext.revalidate: 0skip the cache and keep the render out of the ISR cache.- Only successful
GET/HEADresponses are cached, keyed by method, URL and request headers. Requests without these options are not cached.
#unstable_cache
const getPost = unstable_cache(
async (id: string) => db.post.findUnique({ where: { id } }),
["post"],
{ tags: ["posts"], revalidate: 3600 },
);The key is the function source, keyParts and the call arguments. Results must
be JSON-serializable (a hit returns a parsed copy). revalidate defaults to
false (kept until invalidated); 0 disables caching. Concurrent misses for
the same key share one call. An expired entry is recomputed on the next call
(there is no stale-while-revalidate for data entries).
#unstable_noStore
Called during a render, it keeps that render out of the ISR cache. Outside a render it has no effect.
#On-demand revalidation
"use server";
import { revalidatePath, revalidateTag } from "@krate/runtime/cache";
export async function publish(id: string) {
await db.post.update({ where: { id }, data: { published: true } });
revalidateTag("posts");
revalidatePath(`/blog/${id}`);
}revalidateTag(tag)purges every ISR entry and region whose render read the tag, plus every data-cache entry with the tag, in every process and worker.revalidatePath(path)purges a page:- a concrete URL (
/blog/hello) purges that params variant (all query variants of it) of the matching dynamic route, - a route pattern (
/blog/[slug]) or a static route purges every variant, revalidatePath("/blog", "layout")purges every page at or below/blog. It also drops the data-cache entries those renders stored.
- a concrete URL (
The next request for a purged page renders it fresh (a cache MISS).
Time-based ISR keeps its stale-while-revalidate behavior.
#Where you can call them
| Context | Behavior |
|---|---|
| Server action | Queued, then applied before the action responds. The JSON response carries "revalidated": true and "revalidation": { "paths": [...], "tags": [...] }, and the client dispatches a krate:revalidate window event with that detail so the router can refresh the current route. |
| Node/Bun API route | Queued, then applied before the response is sent. |
| Embedded (QuickJS) API route | Applied synchronously by the Go host. |
| Go API route | krate.RevalidatePath(path, "page"|"layout") / krate.RevalidateTag(tag) from goext/krate; returns after the caches were invalidated. |
Other server code under krate serve / krate dev (a timer, a queue consumer) |
Sent immediately; failures are logged. |
| During a page render | Throws: revalidate after the data changed, from an action or API route. |
| Anywhere else (a build, a script) | Throws: KRATE_HOST_URL is not set. |
If the host cannot apply an invalidation (the renderer is unreachable), the action or API route fails instead of answering with stale data.
#Static pages are skipped, not silently accepted
A static (SSG) page is an HTML file baked at build time; revalidation cannot
rebuild it. revalidatePath("/about") on a static page reports it under
skipped with the reason and logs a warning once per route. The build warns
early with KR8603 when a revalidatePath call
with a literal path names a static page. Make such pages ISR
(export const revalidate = N) or SSR (export const dynamic = "force-dynamic").
Unknown paths are reported as skipped too.
#How it works
krate serve and krate dev start a loopback-only internal endpoint,
POST /__krate/internal/revalidate, authenticated with a random per-process
secret. Every server runtime (SSR renderer, Node/Bun API and action sidecar,
QuickJS routes, Go API routes) receives KRATE_HOST_URL and
KRATE_INTERNAL_SECRET. The host resolves paths against the build manifest and
invalidates the renderer (fanned out to every ssr.rendererWorkers worker), the
Go region cache, the QuickJS data cache and the Node API sidecar's data cache
(fanned out to every API worker) before it answers:
{ "revalidated": [{ "target": "/blog/hello", "kind": "path", "routes": ["/blog/[slug]"] }],
"skipped": [{ "target": "/about", "reason": "route /about is static (SSG): ..." }] }The renderer's mutating endpoints (/__krate/ssr/revalidate, /refresh,
/invalidate, /cache-invalidate) require the same secret; the public server
only forwards /__krate/ssr/health without it.
#Sharing caches between instances
By default each krate start process (and each serverless instance) keeps its
own caches. Several instances behind a load balancer then render every page once
each, and revalidateTag on one leaves the others serving the old page. A shared
cache fixes both:
// krate.config.ts
export default {
cache: { adapter: "redis", url: process.env.REDIS_URL },
};| Cache | With a shared adapter |
|---|---|
| ISR page cache | Entries live in the store. An instance serves a page another one rendered; stale-while-revalidate and the tags a render read work across instances. |
Data cache (fetch with next options, unstable_cache) |
Entries live in the store, tagged. Concurrent identical misses in one process still share one upstream call. |
| Region caches (Suspense/runtime component and Go regions) and the embedded QuickJS data cache | Stay in each instance's memory (they hold request-keyed fragments), but a revalidation clears them on every instance. |
revalidatePath / revalidateTag |
The originating instance purges the store, then publishes the revalidation on the store's channel; every other instance clears what it keeps in memory. A missed message (a dropped connection) makes the instance clear everything. |
Redis is built in (a small RESP client with no dependency; rediss:// for TLS,
AUTH and a database number from the URL). krate start joins the invalidation
channel itself, so the Go host's caches are cleared too.
A broken cache never breaks a page. Every call is bounded by timeoutMs
(250 ms), a failure is logged once, and after three in a row the store is skipped
for five seconds. Meanwhile pages render and are cached in the instance's own
memory; when the store answers again, sharing resumes without a restart. A
revalidation while the store is down purges the instance's own cache and the
response stays 200, but other instances keep the shared copy until the store is
back and its entries expire or are revalidated again.
Per-user responses are never shared. Only renders that are cacheable are
stored, the same rule as the in-process cache: a render that read cookies or
headers, called unstable_noStore() or fetched with cache: "no-store" is not
written, and neither is a page answering 4xx or 5xx.
#Writing an adapter
An adapter is a small key-value store with tag deletion and pub/sub:
import type { CacheAdapter } from "@krate/runtime/cache";
export default function createAdapter(options: { url?: string; prefix?: string }): CacheAdapter {
return {
name: "my-store",
async get(key) { /* the string stored under key, or null */ },
async set(key, value, { ttlSeconds, tags } = {}) { /* store; remember the tags */ },
async delete(key) { /* remove one key */ },
async keysByTag(tag) { /* keys stored with tag */ },
async deleteByTags(tags) { /* remove every key stored with one of tags; return how many */ },
async publish(channel, message) { /* deliver to every subscriber, this process included */ },
async subscribe(channel, handler) { /* call handler(message); handler("*") after missed messages; return an unsubscribe function */ },
async close() {},
};
}Point cache.adapter at the module ("./cache-adapter.ts" or a package name) and
Krate imports its default export (a factory called with { url, prefix, timeoutMs, ...options }, or an adapter object). Methods may reject: Krate bounds and
tolerates them. The Go host joins the invalidation channel for redis only; with
a custom adapter the shared ISR and data caches and revalidation work, but the
Go-host regions and QuickJS data cache of other instances are not cleared.
#Serverless targets
krate deploy writes the cache settings (without the URL) into the bundle. The
node, vercel and netlify targets read the URL from KRATE_CACHE_URL, or
from the variable cache.urlEnv names, at run time; the Redis adapter needs
outbound TCP. A custom cache.adapter module is imported into the bundle at
deploy time, so an HTTP-based store (Upstash REST, Vercel KV, Cloudflare KV)
works wherever fetch does. On Cloudflare Workers use such an adapter: the
deploy warns when cache.adapter is "redis" there.
Without krate deploy, pass the adapter to the handler yourself:
import { createKrateHandler } from "@krate/runtime/server-handler";
import { createRedisAdapter } from "@krate/runtime/cache-redis";
const handler = createKrateHandler({ target: "node", data, modules, cache: createRedisAdapter({ url: process.env.REDIS_URL! }) });With a shared adapter configured, revalidatePath and revalidateTag no longer
report instances as skipped, and krate deploy stops warning about them. In
the serverless handler, instances that live long enough (the node target) also
subscribe to the invalidation channel to clear their region caches; short-lived
functions simply read the store on every request.
#Limits
- Without a shared cache the caches are in memory per server process. Several
krate serveinstances behind a load balancer do not share them, and a CDN that holds an ISR response (s-maxage) keeps serving it until its own TTL expires. See Sharing caches between instances. - Go components cannot read tagged data, so
revalidateTagdoes not target Go region renders;revalidatePathdoes. - Region renders run synchronously today, so tags are only recorded for data read during the page render itself.
fetchcache options in Node API routes and actions need the staged data cache runtime (.krate/cache-runtime.mjs, written bykrate serve/dev); if@krate/runtimecannot be found the server prints a warning.
Last updated: 2026-11-17
Contributors: Noinkin