🚧 Under active development. APIs may change without notice.
A fullstack framework that negotiates how UI reaches the browser.
It runs wherever you deploy it. On a host that keeps a process — Fly, Railway, Render, a container, a bare pod — the channel is a WebSocket. On one that keeps none, a serverless function on Vercel or Lambda or Workers, the same channel becomes a request and its response, and everything the client asks for still works: intents, surgical refreshes, and a whole route staged before it is clicked. Nothing degrades silently — whatever a host cannot do is a named line on the handshake.
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 and app/routes/guide/[page].data.ts answers /guide/:page, because of where they sit.
Fragments compile by being in app/fragments/; writes become the intent manifest by being in
app/intents/. Nothing registers anything — no wiring file to keep in step with the directory, and
no config file you must have.
There is also 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.
npm create weft@latest my-app
pnpm create weft my-app
yarn create weft my-app
bun create weft my-appcd my-app
npm install
npm run dev # http://localhost:3000Two templates. app is the default — a layout, three routes, a fragment with its own CSS, a slot,
and a real mutation you can press. minimal is one route and nothing else.
npm create weft my-app -- --template minimalAlready inside a project? The framework's own CLI scaffolds too:
npx weft create my-app --template appEvery file the scaffold writes is a file the framework will actually read, and each one says what it is for. Nothing is a placeholder.
The route table is the file tree. The plan that places everything on a page is generated from it — no wiring, and no config file you must have.
app/
layout.tsx the document. Its <slot> holes are what a route fills
routes/index.tsx /
routes/[slug].tsx /:slug
routes/x.data.ts x.tsx's head, cache policy, loader, guard and slots
routes/x.css linked only by the pages that render x
routes/x.scoped.css the same, narrowed to the elements x.tsx declares
fragments/<name>.tsx a component, referenced by name from a route's slots
slots/<name>.tsx fills the layout hole of that name on every route
intents/**.ts mutations. The manifest is generated from this directory
public/ served as written, and again at a URL carrying its digest
weft.config.ts what this deployment binds
A page is a fragment. It is a declaration the compiler reads and never runs, so it compiles to data rather than to a function — which is why rendering it ten times adds ten items of content and no template.
// app/routes/index.tsx
import { fragment } from '@weftjs/core'
export default fragment(({ name, steps }: Props) => (
<>
<h1>{name} is running.</h1>
<ol>
{steps.map((step) => (
<li>{step.what}</li>
))}
</ol>
</>
))Its data file is what the route declares — and deliberately not a cache key, because keys are derived from what the compiler saw the page read.
// app/routes/index.data.ts
import { asset, defineRoute } from '@weftjs/core'
export default defineRoute({
head: { title: 'my-app', description: 'A weft application.' },
cache: { class: 'public', ttl: '1h' },
load: () => ({ name: 'my-app', logo: asset('/logo.svg'), steps: [] }),
})cache: { class: 'public' } on a page that read identity fails the build, with identity named.
Mutations are intents. They run on the server, they declare what they invalidate, and they work
with JavaScript switched off — a form posts and gets a 303 back where it came from; the same
dispatch answers a fetch.
// app/intents/counter.ts
import { defineIntent } from '@weftjs/core'
export const bump = defineIntent<{ by: number }>({
name: 'counter.bump',
writes: ['counter'],
input: (raw) => ({ by: Math.trunc(Number((raw as { by?: unknown }).by ?? 1)) }),
async run(ctx, input) {
count += input.by
await ctx.revalidate('counter')
return { refresh: ['body'], data: { count } }
},
})An intent that touches state it did not declare is refused. The declaration is also what tells every open connection which regions just went stale — open the page in two tabs, press the button in one, and the other updates without asking.
No client code required. Adoption, intents, the channel and control wiring are reached through
attributes — data-weft-intent, data-weft-control, data-weft-apply — so an application can ship
none at all. The demo ships none.
Everything here is measured, reproducible from this repository, and reversed in public when it turns
out to be wrong — spec/FINDINGS.md is the claim-by-claim ledger. Apple M4,
Node 24.18, loopback, 200 samples after 30 warmup requests. The falsification test below is the one
exception and says so: it injects 40 ms of round trip and a 1,600 kbps link, because a shell-TTFB
claim measured on loopback is a claim about a network that is not there.
If the pre-encoded-buffer shell does not beat a tuned React Router 7 app on TTFB in a reproducible test, the central premise is wrong. A route whose data takes 40 ms, 40 ms of injected RTT, and a real RR7 app in two configurations:
| Candidate | TTFB p50 | Last byte | Bytes |
|---|---|---|---|
| Weft segments | 44.01 ms | 114.41 ms | 6,289 |
| String-concat SSR, streaming | 44.19 ms | 114.53 ms | 6,289 |
RR7, tuned — promise loader, Suspense, onShellReady |
46.54 ms | 126.53 ms | 7,687 |
| Await the loader, then render | 91.31 ms | 115.45 ms | 6,289 |
RR7, default shape — awaited loader, onAllReady |
98.85 ms | 122.95 ms | 6,370 |
The premise survives and the framing does not. 1.06× faster to first byte is 2.5 ms on a 44 ms number, and a design marketed on that would be marketing 2.5 ms. What the test does establish is worth more: streaming is the whole game. The two blocking candidates pay their query before their first byte — 2.07× and 2.25× worse — and no renderer improvement recovers it. Weft cannot be configured into that failure, because a fragment that reads something slow is a hole by construction. RR7 can, and its default shape is the slow one. The edge that is left sits on the axes nobody markets: 9.6% faster to last byte, 18% fewer bytes for the same content.
A slot is a hole the shell refuses to wait for. With the slow region first, 80 ms against 20 ms:
| Chromium | Firefox | WebKit | |
|---|---|---|---|
| in-order, fast region | 105 ms | 106 ms | 105 ms |
| out-of-order, fast region | 23 ms | 24 ms | 23 ms |
4.6× earlier, for 329 bytes of inline script, with identical final DOM in all three engines.
One row's quantity and price change:
| Form | Raw | Brotli |
|---|---|---|
html |
6,289 | 605 |
delta |
371 | 190 |
16.9× smaller raw, 3.2× after brotli — and nothing else in the field offers it without a stateful process per connection.
Adoption walks the DOM the parser built and records where each value lives, with no component code executing. 50-row region, ~200 bindings, p50:
| Chromium | Firefox | WebKit | |
|---|---|---|---|
| Adopt the region | 0.045 ms | 0.1 ms | 0.05 ms |
| Parse the same markup | 0.077 ms | 0.06 ms | 0.14 ms |
| Apply a 12-path delta surgically | 0.0018 ms | 0.0029 ms | 0.002 ms |
| One signal write to one node | 0.52 µs | 1.41 µs | 1.32 µs |
A delta applied as designed — one write per changed value, into DOM that already exists — is 21–68× cheaper than the parse it replaces. The signal-write row is at the floor and is meant to be: it is a tie with every compiled reactive runtime, and at half a microsecond it is also close to what these engines' clocks can resolve.
More numbers — server throughput, repeat visits, shared refresh, navigation
Server render throughput. Pre-encoded byte segments against string concatenation, both rendering the same compiled templates, so this compares the mechanism and nothing else.
| Scenario | Segments | String SSR | |
|---|---|---|---|
| shell, 707 B | 1,036,941 renders/s | 511,345 | 2.03× |
| cart, 12 rows | 199,817 | 163,337 | 1.22× |
| feed, 50 rows | 52,574 | 41,918 | 1.25× |
The 1.22–2.03× lives in server capacity; it is invisible to latency.
Repeat visits. Templates persist in IndexedDB, are advertised to the server as a coarse digest,
and arrive as TPL frames only when the client does not already hold them:
| Boot path, p50 | Chromium | Firefox | WebKit |
|---|---|---|---|
| First visit | 2.70 ms | 5.00 ms | 3.00 ms |
| Repeat visit | 0.60 ms | 3.00 ms | 1.00 ms |
| Protocol bytes, Chromium | 1,156 → 138 | ||
TPL frames sent |
2 → 0 |
IndexedDB rather than a service worker, because WKWebView gates service workers behind app-bound domains — the traffic where a repeat-visit gain matters most is the traffic that does not have them.
The shared surgical refresh. The client names the base it holds, the server recovers it, diffs,
and memoizes under delta:<tpl>:<from>-><to>. A thousand clients on one base cost one diff —
0.4 ms against a per-connection differ's 9.2. A thousand clients each on a different base share
nothing, and the shared path then costs 18.7 ms against 9.6. Both are in the report, because the
second is where a deployment gets surprised.
A region whose values are not projectable — a raw() value, an isolated instance, a slot hole —
takes the rung between delta and markup: a patch, applicable by a client holding no copy of the
template. 4.3–6.0× smaller than the region raw, 1.9–2.6× after brotli, 3.3–3.9× cheaper to apply
than the parse it replaces — and on a 141-byte region it is larger than the markup after
compression, which is in spec/kernel/surgical.md with the reason it is
still the right answer there.
Instant navigation. Hover stages a route into an epoch that paints nowhere; a click commits it as
a DOM swap. 17.0 ms staged against 605.0 ms on the demo's deliberately slow page, and at 100 ms
injected RTT every route but one wins — 3.25× to 111×, the exception being the page the server
produces fastest. On loopback a staged click is slower than letting the browser do it,
which is the honest floor of the idea and is in
spec/client/navigation.md with the table.
A test fails the moment an entry crosses its ceiling.
| Entry | brotli | Ceiling |
|---|---|---|
| Client runtime, everything | 6,137 | 6,144 |
| Content route — adopt and bind | 2,251 | 5,120 |
| App route — adopt, bind, patch, epochs | 3,190 | 12,288 |
| Server kernel — the document request path | 8,273 | 8,320 |
| Front door — the code, bundled | 14,385 | 15,360 |
Fifteen entries in all, each with its own stated ceiling rather than a share of one — see
DESIGN.md for the full table, the
watermarks that moved, and why the front-door row is the code rather than the download.
weft dev # serve, and rebuild what changes
weft dev --devtools # plus this application's routes, keys and bytes as pages
weft dev --profile # record what every render costs, and plan the next build from it
weft build # sealed templates, the generated plan, the manifest, revved assets
weft start # serve the build. No compiler runs
weft create <name> # a new application, with a page you can open
weft routes # the route table, as the file tree produced it
weft why / # the plan the framework generated for a route, chain included
weft verify --probe # ask every region what it is serving, and exit non-zero on disagreement
weft upload --to <url> --header <k=v> # PUT the build to an object storeThere is no bundler. 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.
Every URL the browser fetches carries a digest and is immutable for a year. weft dev serves
the same bytes at stable names with no-store, because a stylesheet you just edited served as
immutable is a framework that lies to you for a year.
- A compiler that turns TSX into a template IR, infers what each fragment reads, and derives the cache class from it. A key you can hand-write is a key that can disagree with the code, so there is no setter for one anywhere in the framework.
- A request lifecycle that is a state machine. Five states, and the streaming phase is a different context type with no envelope methods on it — so the mistake every other framework documents cannot be written here.
- Render as a DAG.
needsis data dependency only: nine slots, three waves, a 42.7 ms critical path against a 123.3 ms sequential walk. Safe because render is provably read-only. - Static output where a page earns it. A page that reads nothing is a file; a page whose
parameters are a declared set is several.
weft buildproves each one by rendering it twice under deliberately different requests, and prints the reason for every page that stayed dynamic. - Epochs. Staged frames paint nothing; one
COMMITflips every slot at once. 254 bytes on the client. - Live regions. A region is a fragment that lives somewhere else — this process, a service binding, another pod — and the same region composed in-process and over a binding produces byte-identical markup. Rolling one is a registry write, not a redeploy.
- Authority in two questions. A capability is a property of the caller; a signature is a property of the call. Deny by default, deny on failure, and a capability no role can grant fails the build rather than becoming a 403 nobody can explain.
- Fourteen ports, fourteen implementations, eleven bound by the front door with no configuration. A port that is not bound refuses by name and never approximates.
- A kernel that imports nothing but the WinterTC Minimum Common Web API. That rule has a test, and the test failed on its first run.
- One third-party runtime dependency in the whole framework:
oxc-parser, in the compiler.
DESIGN.md is the long form — each of these with its argument, its measurement, and
the things it refuses to do.
pnpm install
pnpm build # ten packages, in dependency order
pnpm demo # six shapes of page :4173
pnpm inspect # every mechanism, running :4180
pnpm docs:dev # the documentation site :4190All three are weft applications. demo/ imports weft and nothing else; @weftjs/inspector reaches
into the kernel, the plan layer and the adapters, because taking those apart is what it is for; and
the documentation site is itself a weft application — 14 routes, 27 sealed templates, and 370
files after a build, most of it generated from the source rather than written beside it so it cannot
drift.
pnpm release:dry # what a release would bump, write and publish — writing nothing
pnpm release # bump, changelog, commit, tag, push, publish, GitHub releaseA release is cut from main from a laptop. There is no CI, so the release script does the checking a
pipeline would: nothing is written until formatting, lint, types, the build and the tests have
passed, every tarball has been packed and inspected, and every name has been confirmed publishable.
A commit's scopes decide which packages move, and everything depending on one of those moves with it.
CONTRIBUTING.md has the rest: what each package does, how to run the tests and
the benchmark lanes, how to take a feature from a spec document to a shipped gate, how a release
works and how to undo one, and the conventions.
The version in each row is what the last release put on the registry; pnpm release writes this
table.
| Package | Version | What it is |
|---|---|---|
@weftjs/core |
0.2.4 |
The framework. The CLI, the conventions, and what an application imports |
create-weft |
0.1.6 |
npm create weft — a shim over the templates that ship inside @weftjs/core |
@weftjs/ir |
0.1.1 |
The template IR: what a compiled fragment is |
@weftjs/warp |
0.1.1 |
The frame vocabulary that carries it |
@weftjs/compiler |
0.1.6 |
TSX to IR, on Oxc, with the type-driven escape class |
@weftjs/client |
0.1.1 |
Adoption, signals, deltas, patches, navigation |
@weftjs/kernel |
0.2.4 |
Routing, the request lifecycle, cache keys, waves, epochs, surgical refresh |
@weftjs/plan |
0.1.6 |
The plan DSL, validation against inferred effects, plugins, weft why |
@weftjs/adapters |
0.1.6 |
The fourteen ports, implemented |
@weftjs/bench |
not published | The measurement harness, and the gates it enforces |
@weftjs/docs |
not published | The documentation site, which is a weft application |
@weftjs/inspector |
not published | A station per capability, each with a control you can turn |
| Where | What it is |
|---|---|
pnpm docs:dev |
Quick Start, a 21-page Guide, Tutorial, Examples, API, Glossary, Errors, a playground |
spec/ |
The reference: each mechanism, its refusals, and what it deliberately does not do |
spec/FINDINGS.md |
Every claim a measurement reversed, with both numbers |
DESIGN.md |
The long form, and the full spec-to-implementation map |
pnpm inspect |
The same capabilities, running, with a control per station |
Three of those are gates rather than documents. Every spec document must have an inspector station and a guide page that introduces it; all 1,367 importable names must carry a doc comment; all 326 named refusals must say something other than their own name. Each is a test, and each fails the build when it stops being true.
CONTRIBUTING.md. Conventional Commits, exact dependency versions, oxlint and
Prettier, and a checklist to run before you push.