What a route declares
Placement, delivery, cache policy and budgets are declared per route — and checked against what the compiler inferred.
Head, cache policy, loader, guard, slots, parameter set. Delivery is then derived, and the build prints which pages became files.
Every one names what it looked at: the read, the streaming slot, the undeclared parameter, the live region.
In plain terms
A route declares what it is, not how to cache it: a title, a loader, a guard, its slots, its parameter set. Everything about delivery is then derived — and a declaration the framework cannot honour fails the build with the reason named.
A route’s .data.ts is the one place placement lives. It is read at build time and becomes part of the generated plan, so what it says is a fact about the application rather than a branch taken per request.
import { defineRoute } from '@weftjs/core'
export default defineRoute({
head: { title: 'Cart' },
layoutValues: { heading: 'Your cart' },
cache: { class: 'private' },
slots: {
panel: { html: '' },
body: { fragment: 'cart', live: true, load: loadCart },
readout: { fragment: 'markup', html: summary },
},
})What a slot may declare
Nine of them, which are the ones worth meeting first. The other seven — and every field a route may declare, with its type and its default — are on the defineRoute reference.
| Field | What it decides |
|---|---|
fragment | Which compiled fragment fills the hole. A name in app/fragments/. |
load | The loader. Its result is the values the fragment renders with. |
stream | Whether this region arrives separately, and at what priority. |
needs | Another slot this one depends on, so the scheduler puts it in a later wave. |
cache | The class, TTL and tags for this region — checked against what it reads. |
budget | A CPU ceiling and what happens when it is exceeded. |
live | Whether this region may be refreshed over the channel. |
refresh | An interval, and the conditions under which it applies. |
placeholder | The bytes sent when the region degrades. Honest, cheap, visibly incomplete. |
Every declaration is validated
A declaration naming a hole the document does not leave is E_SLOT_NOT_IN_SHELL, listing the holes it does leave. A hole nothing fills is E_SHELL_HOLE_UNFILLED. An executor that is not bound is E_UNKNOWN_EXECUTOR. The pattern is the same throughout: the declaration and the derivation are both written down, so a disagreement is a build error rather than an empty region in production.
What you do not have to declare
Everything above is optional, and the useful default for most of it is silence. A route with no cache gets the class its fragments’ reads imply; a route with no stream anywhere lowers to in-order delivery and ships no filler script; a page whose fragments read nothing becomes a file at build time without asking.
And the part that is about time can come from a measurement rather than from you — see a plan generated from measurement.