Intents: the only thing that writes
A render cannot write. Mutations are intents, addressed by an opaque id, with their writes declared.
The framework drops exactly the tags you named and nothing else. Naming nothing is legitimate for an intent that owns no cached state — and the client never names your code: an intent is addressed by an opaque id derived from its module and export, so renaming the export does not change the wire.
An undeclared write is an invalidation nobody could predict by reading the code, and predicting it by reading the code is the whole value of the effect graph. Unlike the read guard, this one is not dev-only.
In plain terms
Nothing but an intent may write. It declares four things — a name, the tags it invalidates, a validator for its input, and a body — and that is the whole surface. Post it from a plain form and the page works with JavaScript switched off; dispatch it from the channel and the same four things run.
A render cannot write. That is enforced by the type of the context a render receives, not by a convention — so every mutation is an intent, and intents are the only thing in this framework allowed to change anything.
// app/intents/cart.ts
import { defineIntent } from '@weftjs/core'
export const add = defineIntent<{ sku: string; qty: number }>({
name: 'cart.add', // for logs and `weft why`. Never on the wire
writes: ['cart'], // the complete set this may invalidate
input: (raw) => parse(raw), // throwing here is a 422, not a 500
async run(ctx, { sku, qty }) {
await db.cart.add(ctx.session, sku, qty)
await ctx.revalidate('cart') // an undeclared tag throws
},
})A mutation with no JavaScript at all
examples/helpfulA form, a hidden field and a POST to the route the intent manifest generated. This one is live: pressing it dispatches a real intent in this process.
app/fragments/examples/helpful.tsximport { fragment } from '@weftjs/core'
/**
* A mutation with no JavaScript on the page at all.
*
* The form posts to `/_weft/i/docs.helpful`, which is the route the intent manifest generated from
* `app/intents/feedback.ts`. Phase A dispatch means a real status code, a cookie the server may set
* `HttpOnly`, and a 303 back here — the three things a `fetch` handler cannot give you and the
* reason the no-JavaScript path is the *first* path rather than the fallback.
*
* The same intent, unchanged, is what a client would dispatch over the channel. There is no second
* endpoint and no second handler.
*/
export default fragment(({ page, count }: { page: string; count: number }) => (
<form class="vote" method="post" action="/_weft/i/docs.helpful">
<input type="hidden" name="page" value={page} />
<button type="submit">Useful</button>
<span class="count">{count}</span>
</form>
))
What the compiler knows
Holes
| Binding | Hole | Escape |
|---|---|---|
page | attr | escape |
count | text | proven-safe |
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
- 1
- Version
951dcf634875ff1de1098eb7eb26b16b
Phase A dispatch is what makes a real status, an HttpOnly cookie and a 303 available — the three things a fetch handler cannot give you. The count is real, it is this process’s, and it moves when you press the button — which took three declarations agreeing. The intent names docs.votes in writes, so ctx.revalidate may fire it. The body is a live region tagged with the same name, so the write drops it. And the route carries that tag too: a document held for an hour under no tag is a second cache the invalidation cannot reach, and while it was missing every layer here worked perfectly and the number stayed at zero. W_DOCUMENT_OUTLIVES_INVALIDATION exists so the next person is told instead of guessing. The cost is named too: this page is L0_LIVE rather than a file, which is the trade a page about writing has a reason to make and the other twenty-one guide pages do not.
That form is not an illustration: app/intents/feedback.ts is a real module in this application, so the manifest generated from it has a route and pressing the button dispatches the intent. Its id is c2d722 — the first six characters of a hash of the module path and the export name, which is what the client would carry if this page had any JavaScript. The tally is in this process’s memory, because a documentation site has no reason to bind a store.
Two rules
A write is declared, and an undeclared one throws. ctx.revalidate('orders') from an intent that did not declare orders is E_UNDECLARED_WRITE, naming the tag and the field to add it to. Unlike the plugin read guard this is not dev-only: an undeclared read is a missed optimisation, and an undeclared write is a cache invalidation nobody can predict by reading the code.
The client never names server code. An intent is addressed by an opaque id derived from its module and export, so renaming the function does not change the wire and the wire does not disclose a function name.
The same intent, three ways in
| Caller | What happens |
|---|---|
| A form post, no JavaScript | Dispatched in phase A, so a real status, an HttpOnly cookie and a 303 are all available. |
fetch | The same dispatch, outcome as JSON, chosen by Accept rather than a second endpoint. |
| Over the channel | The client stages its guess in an epoch; success replaces it with the truth in one paint, failure discards it. |
Every field an intent may declare — reads, capabilities, signed, limit, invalidatesAll — is on the defineIntent reference, along with defineRenderable, which is the same shape for the other thing a client may ask this deployment to do.
Who may run one
An intent may declare capabilities, and an intent declaring one with nothing bound to check it is refused rather than allowed — E_NO_CAPABILITY_CHECK. A signed intent carries a token this deployment issued, and a token may be narrowed once into a leaf that authorises less. Minting is uncacheable by construction, which is why a signed intent has no no-JavaScript path.