weft
ir 2.6.0 · warp 1.8.0
Ten minutesone command, three files, and a page that streams

Quick Start

One command, three files, and a page whose slow half does not hold up its fast half. Nothing here is scaffolding you delete later.

Create it

A folder is an application: a file under app/routes/ answers the URL its path spells, and nothing anywhere registers it. There is no config file you must have either — weft.config.ts exists to bind ports, and a first application binds none.

$ pnpm create weft my-app$ cd my-app && weft dev   weft dev  → http://localhost:4173  3 routes · 4 sealed templates · no bundler
$ npm create weft my-app$ cd my-app && npx weft dev   weft dev  → http://localhost:4173  3 routes · 4 sealed templates · no bundler
$ bun create weft my-app$ cd my-app && bunx weft dev   weft dev  → http://localhost:4173  3 routes · 4 sealed templates · no bundler
No bundler ran. Client modules are TypeScript with their types stripped and two bare specifiers rewritten, so what runs in the browser is the file on disk.

Three files

The route table is the file tree. A .tsx beside a .data.ts is a page and its declaration: head, cache policy, loader, guard and slots.

app/
layout.tsx
routes/
index.tsx
index.data.ts
fragments/
feed.tsx
// app/routes/index.tsx
import { fragment } from '@weftjs/core'

export default fragment(({ user }: { user: User }) => (
  <main>
    <h1>Hello, {user.name}</h1>
    <slot name="feed" />
  </main>
))
FileWhat it is
app/layout.tsxThe document. Its <slot> holes are what a route fills.
app/routes/index.tsxThe page at /.
app/routes/index.data.tsWhat that route declares — head, cache policy, loader, slots. Optional.

Everything this framework renders is a fragment, and a fragment compiles to a sealed template: pre-encoded bytes with holes, and a version that is a hash of its own content. Here is one that this page compiled, rendering:

Two fragments and two sealed templates. The tag is resolved at build time — nothing is mounted.

output

Olive oil, 2L

new
app/fragments/examples/card.tsx
import { fragment } from '@weftjs/core'
import Badge from './badge.tsx'

/**
 * A fragment rendering another fragment.
 *
 * `<Badge/>` is not mounted and it is not a function call at runtime: the compiler resolves the tag
 * to a sealed template and leaves a component hole that projects this fragment's values into it. So
 * one `Badge` used a hundred times is one sealed template and a hundred projections.
 */
export default fragment(({ title, label }: { title: string; label: string }) => (
  <article class="card">
    <h3>{title}</h3>
    <Badge label={label} />
  </article>
))
What the compiler knows
Holes2
Escape elided0
Effect setnone — static
Wire formshtml · bundle · split · patch · delta

Holes

BindingHoleEscape
titletextescape
c0componenttrusted-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
e9199c0717e062dd18da20ba9fa37b51

Make it stream

A slot is a hole the shell refuses to wait for. Declare the slow one and the first byte stops depending on it — 329 bytes of inline script buys fastest-first delivery in Chromium, Firefox and WebKit alike.

in orderfast region visible at 105 ms
out of orderfast region visible at 23 ms

The header, the nav and everything before that slot are on the wire while the slow query is still running. Nothing about the page had to be restructured to get that — a fragment that reads something slow is a hole by construction.

Build it

CommandWhat it does
weft buildSealed templates, the generated plan, the manifest, revved assets. Prints which pages became files, and the reason for every page that did not.
weft startServe the build. No compiler runs, and static paths are answered before the kernel is reached.
weft why /The plan the framework generated for a route, chain included.
weft verify --probeAsk every region what it is serving, and exit non-zero on disagreement.