weft
ir 2.6.0 · warp 1.8.0
Part one · Step 3 of 19

Fragments, components and lists

A sealed template with pre-encoded bytes, a component resolved at build time, and one row template projected per item.

Goal

Break the page into fragments, put one inside another, and render a list — then read the template the compiler sealed and find the holes it did not have to escape.

The page is one fragment so far. A fragment is not a component that runs: it is a template the compiler sealed, with pre-encoded bytes between its holes and a version that is a hash of its content. Splitting the page up is therefore free at render time — what it costs is measured once, at build.

1 · One fragment inside another

A tag whose name is a fragment is resolved when the parent is compiled. There is no call site at runtime, no element to mount and nothing to reconcile — the child’s bytes are spliced into the parent’s, and its holes become the parent’s holes:

sketch — not compiled
// app/fragments/price.tsx
import { fragment } from '@weftjs/core'

export default fragment(({ amount }: { amount: number }) => (
  <b class="price">{amount}</b>
))
sketch — not compiled
// app/fragments/item.tsx
import { fragment } from '@weftjs/core'
import Price from './price.tsx'

interface Item { sku: string; name: string; price: number }

export default fragment(({ item }: { item: Item }) => (
  <li>
    <code>{item.sku}</code> {item.name} — <Price amount={item.price} />
  </li>
))

2 · A list is one row template, projected

A map in a template does not build markup per item. It compiles to a single row template that the renderer projects once per value, which is why a thousand rows cost one template rather than a thousand:

sketch — not compiled
export default fragment(({ items }: { items: Item[] }) => (
  <ul>{items.map((item) => <Item item={item} />)}</ul>
))

3 · Look at what it sealed

$ weft why /  templates  4 sealed · 1 row template projected per item  holes      sku (text, escape) · name (text, escape) · amount (text, none)  reads      nothing — static

amount is typed number, so the compiler knows it cannot hold markup and marks it as needing no escaping. You wrote that type for yourself; the template got the escape elision for free. See fragments and templates for what a sealed template is, and one fragment inside another for why composition has no runtime cost.