weft
ir 2.6.0 · warp 1.8.0

A fullstack framework that negotiates how UI reaches the browser.

A piece of UI can travel as full markup, as a surgical delta, or as a patch. The compiler proves the three say the same thing, and the server picks one per request — where most frameworks freeze that choice at build time.

A folder is an application. The file tree is the route table: app/routes/about.data.ts answers /about because of where it sits. Fragments compile by being in app/fragments/; writes become the intent manifest by being in app/intents/. Nothing registers anything, so there is no wiring file to keep in step.

There is no bundler, no virtual DOM, and no component code running in the browser: the compiler seals your pages into templates, the server fills them, and the client runtime binds what is already there.

Pages still change. A signal updates one value in place, without re-rendering around it. An intent is the only thing allowed to write, and it declares which regions it invalidates — so what goes stale is known before it runs.

$ npm create weft my-app

Client modules are TypeScript with their types stripped by Node and two bare specifiers rewritten, so what runs in the browser is the file on disk.

app/routes/cart.data.ts

import { defineRoute } from '@weftjs/core'

export default defineRoute({
  head: { title: 'Cart' },
  // no cache key here. There is no setter.
  slots: {
    items: { fragment: 'cart/items' },
    total: { fragment: 'cart/total', needs: ['items'] },
    feed:  { fragment: 'feed', stream: true },
  },
  etag: true, // E_ETAG_STREAMS — feed streams
})

app/fragments/cart/total.tsx

import { fragment } from '@weftjs/core'

export default fragment(({ rows, total }: Prices) => (
  <div class="prices">
    {rows.map((r) => (
      <p>{r.label}<b>{r.price}</b></p>
    ))}
    <p class="total">Total<b>{total}</b></p>
  </div>
))

// 7 holes · 4 need no escaping, because they are typed number

the frames on the socket

// what the client sent — it names what it already holds
HELD cart/total t_9f4c1ab2 r_41c8

// html — the whole region, re-parsed · 6,289 B
FRAME cart/total html
  <div class="prices"><p>Oat milk<b>7.80… (12 rows)

// patch — the holes that changed, as DOM writes · ~1,300 B
FRAME cart/total patch
  [4, "<b>9.75</b>"], [9, "<b>14.00</b>"]

// delta — values only, into DOM that exists · 371 B
FRAME cart/total delta r_41c8->r_5d02
  { 4: 9.75, 9: 14.00 }

// same fragment, same DOM. The kernel picks per request.

app/intents/quantity.ts

import { defineIntent } from '@weftjs/core'

export const quantity = defineIntent<{ qty: number }>({
  name: 'docs.quantity',
  writes: ['cart', 'totals'],  // declared, so the
  //                        regions that go stale are known
  input: (raw) => {
    const qty = Number((raw as any).qty)
    if (!Number.isFinite(qty)) throw new Error('qty')
    return { qty: Math.max(0, Math.trunc(qty)) }
  },
  async run(input, ctx) { await ctx.cart.set(input.qty) },
})

Benchmarked, not asserted

Shell time to first byte

Apple M4 · Node 24.18 · 200 iterations
a 40 ms query behind a slot · 40 ms RTT injected

weft
segments · the shell is never downstream of a query
44.01 ms
React Router 7
tuned — Suspense boundary, onShellReady
46.54 ms
weft — blocking
the slot awaited instead of streamed
91.31 ms
React Router 7 — blocking
loader awaited, onAllReady — the shape most apps ship
98.85 ms

Bar length is the measurement. Note which gap is larger: the two React Router 7 configurations are 52.3 ms apart, and the tuned one is 2.5 ms from weft. The shape you ship dominates the framework you ship it on — what changes here is that the fast shape is the only one available.

Bytes on the wire the same document, identity encoding lower is better
weft
sealed template, no framework markers
6,289 B
React Router 7 — blocking
no boundary, so no Suspense markers
6,370 B
React Router 7
Suspense markers and comment nodes: +22%
7,687 B
Time to last byte when the slow region has landed — streaming moves the first byte, not the last lower is better
weft
114.41 ms
weft — blocking
115.45 ms
React Router 7
the extra 1,398 bytes cost 12 ms here
126.53 ms
React Router 7 — blocking
122.95 ms

What this actually shows

The gap between the two React Router 7 configurations — 46.54 ms against 98.85 — is far larger than the gap between either of them and weft. The shape you ship dominates the framework you ship it on. What weft changes is that the fast shape is the only one available: there is no await in a route declaration that could put the shell downstream of a query.

What is not fair, stated

The two apps are not byte-identical and cannot be: React emits Suspense markers and comment nodes. So the byte-equality gate covers weft’s own candidates only, and the React Router 7 app is measured on timing and payload instead. On an infinitely fast link its extra 1,398 bytes are free — which is why the run models bandwidth, where they are 12 ms.

Reproduce it

node packages/bench/src/cli.ts run --axes shell-ttfb --scenarios slow-feed \
    --latency 40 --bandwidth 1600 --external benchmarks/rr7/candidates.json

The harness spawns and stops the third-party app itself, and prints queryMs so a scenario mismatch is visible rather than silent. More candidates and axes land here as they are added; each axis states the state of the art it is measured against and whether a win is expected.

One region, three ways onto the wire

A region is one rendered fragment on a page — a cart total, a feed, a header — addressable on its own. A region that changed can travel as markup, as a patch addressed the way adoption addresses the DOM, or as a delta naming only the holes whose values moved. The kernel picks per request from what the client says it holds. Nothing about the fragment changes.

You do not choose between them and you cannot get them wrong: the fragment is one declaration, and the same one serves a first visit, a surgical refresh, and a client still holding last week’s template.

Slots and streaming
html the whole region, re-parsed 6,289 B · 605 brotli
patch the holes that changed, as DOM writes between the two, structurally
delta values only, into DOM that exists 371 B · 190 brotli
One row’s quantity and price change, on a twelve-row cart. A delta applied as designed is 21–68× cheaper than the parse it replaces; a region whose values are not projectable takes the patch rung instead of falling all the way to markup.

Where to start

9 sections; 4 generated from the source, so they cannot drift

Three things this framework does not have

and what each absence is worth

No bundler

The file on disk is the file that runs

Client modules are TypeScript with their types stripped and two bare specifiers rewritten. Nothing is packed, so the stack trace you get is the code you wrote.

26,551 Bbrotli, for the whole demo — measured over HTTP, not a bundle

No virtual DOM

An update names the hole it changed

There is nothing to reconcile: a delta carries the values whose holes moved, applied straight into DOM that already exists.

21–68×cheaper to apply than the parse it replaces

No component code in the browser

The runtime binds what the parser already built

Adoption walks the server-rendered DOM and records where each value lives. No component function executes, on first paint or after.

0.045 msto adopt a 50-row region — against 0.077 ms to parse the same markup

This site is a weft application

Not a documentation generator pointed at a repository, and not a static-site tool with a weft plugin. packages/docs is an application in the same sense the demo is: routes from the file tree, a plan generated from it, 35 sealed templates, and one command to serve it. That is the strongest claim the framework can make about itself, so it is the one this site is built to be able to make.

What the site usesWhere you can see it
Nested layouts — the document is a chainGuide, Tutorial and API pages all sit under a routes/<section>/layout.tsx
Param routes with a declared setOne route serves every guide page; another serves all 338 error codes
The L0 tierweft build writes this whole site as files. The kernel is not invoked to serve them
Slots as cache unitsThe contents column is a region of its own, so it is one entry across a section rather than a copy per page
A component's own stylesheetEvery example on this site carries a .scoped.css the compiler narrowed to its elements
Declared refusalsThe playground is the one page that is not a file, and the build says why
The compiler's virtual file setThe playground compiles what you type without writing it anywhere
A read as a cache axis/play?src= taints route:src, so every source is its own content-addressed entry
An intent, with no JavaScript on the pageThe form on intents posts to a real intent in this application