weft
ir 2.6.0 · warp 1.8.0

What a route declares

Placement, delivery, cache policy and budgets are declared per route — and checked against what the compiler inferred.

$ weft build
396 files written to .weft/static/
/play — not a file: reads what you typed
/play — not a file: reads route:src
The build prints the reason for every page that did not become a file: an undeclared parameter, a read, a live region, a streaming slot.
✓ Valid A route stating what it is

Head, cache policy, loader, guard, slots, parameter set. Delivery is then derived, and the build prints which pages became files.

✕ Refused a declaration the framework cannot honour
what you wrote→checked against the inferred effects at build time→named refusal

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.

sketch — not compiled
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.

FieldWhat it decides
fragmentWhich compiled fragment fills the hole. A name in app/fragments/.
loadThe loader. Its result is the values the fragment renders with.
streamWhether this region arrives separately, and at what priority.
needsAnother slot this one depends on, so the scheduler puts it in a later wave.
cacheThe class, TTL and tags for this region — checked against what it reads.
budgetA CPU ceiling and what happens when it is exceeded.
liveWhether this region may be refreshed over the channel.
refreshAn interval, and the conditions under which it applies.
placeholderThe 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.