defineRenderable
The catalogue: what a browser may ask to have rendered, by opaque id, and the gates that ask passes.
A module under app/renderables/ is to a render request what an intent module is to a mutation, down to the derivation: the id is intentId(module, export), the same six hex characters the compiler writes into a template’s wiring.
A directory rather than a flag on a fragment, because the set of things a client can name is a security boundary and it should be visible in the file tree. app/fragments/ holds everything a page composes; this holds what a browser may ask for. Making the second set the first would turn every component in an application into a public endpoint taking arbitrary props.
The id resolves through the registry, so an entry served by this process today can be served by a region on another deployment tomorrow and the client cannot tell.
import { defineRenderable } from '@weftjs/core'
export const details = defineRenderable<{ sku: string }>({
name: 'product.details',
fragment: 'product/details', // or `region: 'catalogue'`, resolved by the registry
capabilities: ['catalogue:read'],
limit: { max: 60, windowMs: 60_000 },
input: (raw) => ({ sku: String((raw as { sku: unknown }).sku) }),
load: (ctx, { sku }) => ctx.services.catalogue.get(sku),
})A fragment a client may ask for by opaque id, and the gates that ask applies.
Read from packages/weft/src/renderables.ts · RenderableDeclaration
namerequired
Human-readable, for a log and for the build report. Never on the wire.
name: 'product.details'fragmentoptional
Which fragment renders it, by name under app/fragments/.
fragment: 'product/details'regionoptional
Or: the region that serves it, by name, resolved through the registry like any other region.
The half that makes this a catalogue. An entry named here is rendered by whichever deployment the registry currently points that region at, so moving it is a registry write — and the client, which only ever had an opaque id, is not involved in either arrangement.
// Rendered by whichever deployment the registry points `catalogue` at.
// The client only ever had an opaque id and is not involved either way.
region: 'catalogue'capabilitiesoptional
Capabilities the caller must hold. Unchecked capabilities are refused, not waved through.
capabilities: ['catalogue:read']signedoptional
Reachable only with a signed, expiring token this deployment minted.
signed: truelimitoptional
How much of this one caller may ask for.
The one call a client can make that costs server work without writing anything, so it is the one that most wants a limit. What it is counted against is the limits port's, as everywhere else.
// The one call a client can make that costs server work without writing anything.
limit: { max: 60, windowMs: 60_000 }inputoptional
Parse and validate the raw params. Throwing here is E_RENDER_INPUT, not a 500.
// Throwing here is E_RENDER_INPUT, not a 500.
input: (raw) => ({ sku: String((raw as { sku: unknown }).sku) })loadoptional
The values the fragment renders with. Absent renders it with none, which is right for a static one.
load: (ctx, { sku }) => ctx.services.catalogue.get(sku)