weft
ir 2.6.0 · warp 1.8.0

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.

pre-encoded bytes·holes, filled per render
version t_9f4c1ab2 — a hash of its content
A fragment lowers to segments and holes. The bytes never change, only what lands in the holes — which is why a render can be a copy and an update can name one hole.
✓ Valid A hole the compiler can name

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.

✕ Refused a call inside a hole
what you wrote→a fragment body is a declaration, not code that runs→refused

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.

Two holes, one annotation apart. Open the facts below: count is proven-safe and name is escape, and nothing in the file said so.

output

Olive oil — 3 items

app/fragments/examples/total.tsx
import { 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
Holes2
Escape elided0
Effect setnone — static
Wire formshtml · bundle · split · patch · delta

Holes

BindingHoleEscape
nametextescape
counttextproven-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.

Three rows, two sealed templates. Page weight tracks content rather than markup.

output
OIL-2LOlive oil, 2L14
RICE-5Basmati rice, 5kg9
DATE-1Medjool dates, 1kg12
app/fragments/examples/list.tsx
import { 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
Holes1
Escape elided0
Effect setnone — static
Wire formshtml · bundle · split · patch · delta

Holes

BindingHoleEscape
rowslisttrusted-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.

RefusalWhat it means
E_EXPRESSION_UNSUPPORTEDAn expression with no lowering — a template literal in an attribute, for instance. Move the value into a prop.
E_UNTRACKED_EFFECTA 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_ROOTA 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.