Fragments and templates
A fragment compiles to a sealed template: pre-encoded bytes with holes, and a version that is a hash of its content.
A prop, a field, a mapped list, a derived value. The body is read once and never executed, so what lands in a hole is always a value rather than a call.
There is nowhere for the call to happen. Compute it before the fragment, or name an intent for an event.
In plain terms
You write a function that returns markup. The compiler reads it once, never runs it, and turns it into an array of finished bytes with gaps. Rendering is walking that array and dropping today’s values into the gaps.
A fragment compiles to a sealed template. What that means concretely: the constant parts are pre-encoded Uint8Array segments, the variable parts are holes, and the whole thing has a version that is a hash of its content. Rendering copies the segments and encodes the hole values straight into the output buffer.
Two consequences are worth having in mind from the start. A template is data, so it can be sent to a client and kept; and a version is a content address, so two renders of the same template with the same values are the same bytes by construction.
Escaping is decided by the type
Escaping a value that cannot contain markup is work that produces the same bytes. So the compiler asks the type checker what each hole holds, and a hole whose type makes escaping a no-op is lowered as proven-safe: no escape call at all.
Escape elision is a type question
examples/totalTwo holes, one annotation apart. Open the facts below: count is proven-safe and name is escape, and nothing in the file said so.
Olive oil — 3 items
app/fragments/examples/total.tsximport { fragment } from '@weftjs/core'
/**
* Escape elision is a type question.
*
* `count` is a number, so no value it can hold needs escaping and the compiler drops the escape
* call entirely — the hole's class is `proven-safe`. `name` is a string, so it keeps `escape`.
* Nothing here declares either; the difference is the annotation two lines down.
*/
export default fragment(({ name, count }: { name: string; count: number }) => (
<p class="total">
<b>{name}</b> — {count} items
</p>
))
What the compiler knows
Holes
| Binding | Hole | Escape |
|---|---|---|
name | text | escape |
count | text | proven-safe |
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
7917963794bd383bd071fb38c4601047
This is why the examples here are real files: elision needs a checker, and a snippet nobody type-checked has no types to elide by.
A list is one template, projected
A .map() over an array lowers to a list hole whose rows come from one nested sealed template. Fifty rows is fifty value sets and two templates — which is why page weight tracks content rather than markup, and why a delta over a list can address the rows that changed.
A list is one row template
examples/listThree rows, two sealed templates. Page weight tracks content rather than markup.
OIL-2L | Olive oil, 2L | 14 |
RICE-5 | Basmati rice, 5kg | 9 |
DATE-1 | Medjool dates, 1kg | 12 |
app/fragments/examples/list.tsximport { fragment } from '@weftjs/core'
interface Row {
sku: string
name: string
price: number
}
/**
* A list is one sealed row template, projected once per item.
*
* This is why page weight tracks content rather than markup: a fifty-row table is fifty rows of
* values and two templates, and a delta over it addresses the rows that changed.
*/
export default fragment(({ rows }: { rows: Row[] }) => (
<table class="rows">
<tbody>
{rows.map((row) => (
<tr>
<td>
<code>{row.sku}</code>
</td>
<td>{row.name}</td>
<td class="num">{row.price}</td>
</tr>
))}
</tbody>
</table>
))
What the compiler knows
Holes
| Binding | Hole | Escape |
|---|---|---|
rows | list | trusted-raw |
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
- 2
- Version
c7dd63a67cc17895d6951efb08edd865
What the subset refuses
The compiler accepts a deliberate subset of TSX, and what it refuses it refuses by name. The reason is not purity: a template has to be data for a client to hold it, and an expression the compiler cannot lower is an expression that would have to become code on the wire.
| Refusal | What it means |
|---|---|
E_EXPRESSION_UNSUPPORTED | An expression with no lowering — a template literal in an attribute, for instance. Move the value into a prop. |
E_UNTRACKED_EFFECT | A read the compiler cannot name, so it cannot become part of a cache key. The message names what to use instead. |
E_COMPONENT_NOT_SINGLE_ROOT | A composed fragment with more than one root element. An instance is one hole, so it is one node. |
The full list, with the argument for each, is in spec/compiler/supported-subset.md.