What a fragment reads decides everything
The cache key, the class and the Vary header are derived from the reads the compiler saw. None of them can be declared.
Read nothing and the page is a file. Read the locale and it is one shared entry per value. Read identity and it is private — all three decided for you.
The failure names identity, so you know which read contradicted you.
In plain terms
You never write a cache key. The compiler notes every read a fragment makes — the user, a cookie, the locale, a query parameter — and that set of reads is the key. Read nothing and your page is a file; read identity and it is private to one person.
Nothing about cacheability is declared here. The compiler records what each fragment read, and the cache key, the class and the Vary header are all derived from that set. A cache class that can be asserted can be asserted wrongly, and the failure is one reader’s bytes in another reader’s cache.
A read becomes a key component
examples/greetingOne ctx.cookie call. The facts below show cookie:currency in the read set, which is where the cache key and Vary come from.
Prices shown in .
app/fragments/examples/greeting.tsximport { fragment, type Ctx } from '@weftjs/core'
/**
* A fragment that reads the request, and therefore keys on it.
*
* `ctx.cookie('currency')` taints `cookie:currency`, so this fragment's cache entry is per currency
* and the response says `Vary: Cookie`. Nothing declares that. Every read here is a call the
* compiler can name statically, which is why a read it cannot name is a build error rather than a
* cache key with a hole in it.
*/
export default fragment(async (ctx: Ctx) => {
const currency = ctx.cookie('currency') ?? 'USD'
return <p class="greeting">Prices shown in {currency}.</p>
})
What the compiler knows
Holes
| Binding | Hole | Escape |
|---|---|---|
currency | text | escape |
What the client wires on adoption
No wiring: nothing on this template changes after it is painted, so the client attaches nothing to it.
- Sealed templates
- 1
- Version
45122ec2139bdfe756602f978ec0fcea
A read the compiler cannot name statically is E_UNTRACKED_EFFECT — a build error rather than a key with a hole in it.
The classes, and what forces them
| Reads | Class | What follows |
|---|---|---|
| nothing | static | The key is the content address. It can be resolved at build time and served as a file. |
| a cookie, a header, a locale, a flag | shared | Keyed by value, and the response says Vary so a CDN cannot serve it to everyone. |
identity | private | Never shared, never a CDN entry. |
time | forces a TTL | A policy with no TTL would never expire, so declaring one is a build error. |
Identity contains itself
examples/privateOne ctx.user() read makes this region private. Because it is a slot rather than part of the document, the document stays shared.
Signed in as
app/fragments/examples/private.tsximport { fragment, type Ctx } from '@weftjs/core'
/**
* One identity read, and the region can never be a shared cache entry.
*
* Because it is a *slot* rather than part of the document, the document stays shared and only this
* region is per-user. That containment is the whole reason a page with a signed-in corner is not a
* page that has to be private.
*/
export default fragment(async (ctx: Ctx) => {
const user = await ctx.user()
return <p class="private">Signed in as {user}</p>
})
What the compiler knows
Holes
| Binding | Hole | Escape |
|---|---|---|
user | text | escape |
What the client wires on adoption
No wiring: nothing on this template changes after it is painted, so the client attaches nothing to it.
- Sealed templates
- 1
- Version
6eec7f5c8738807d4f75fa53191d73b1
The plan is checked against the compiler, never the reverse
A route may declare a cache policy. It cannot declare one that contradicts what its fragments read: .cache('public') on a fragment that reads identity fails the build, naming identity as the read that caused it. That is the strongest promise in the design and it is a build error rather than a runtime check.
export default defineRoute({
// Refused: the fragment filling this slot reads identity.
cache: { class: 'public', ttl: '1h' },
slots: { body: { fragment: 'cart' } },
})