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
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.
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 streamingWhere to start
9 sections; 4 generated from the source, so they cannot driftQuick Start
One command, three files, and a page that streams. Ten minutes.
Guide
22 pages in order: fragments, layouts, effects, streaming, the client, intents, live regions, composition, operating it.
Tutorial
Build one real page from nothing, one step at a time, and watch what each step costs.
Examplesgenerated
All 15 live fragments on this site, with their source and what the compiler knows about them.
Referencegenerated
145 fields across six pages — every option of weft.config.ts, every field of a route, an intent, a renderable — with what each accepts and defaults to.
APIgenerated
1427 importable names across 9 modules, read out of each public entry.
Glossary
39 words this framework uses in a way another framework does not.
Error Referencegenerated
338 named refusals, each with the message it raises and the file that raises it.
Playground
Type a fragment and see what it compiles to. No files, no build — a virtual file set.
Three things this framework does not have
and what each absence is worthNo 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 uses | Where you can see it |
|---|---|
| Nested layouts — the document is a chain | Guide, Tutorial and API pages all sit under a routes/<section>/layout.tsx |
| Param routes with a declared set | One route serves every guide page; another serves all 338 error codes |
| The L0 tier | weft build writes this whole site as files. The kernel is not invoked to serve them |
| Slots as cache units | The 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 stylesheet | Every example on this site carries a .scoped.css the compiler narrowed to its elements |
| Declared refusals | The playground is the one page that is not a file, and the build says why |
| The compiler's virtual file set | The 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 page | The form on intents posts to a real intent in this application |