weft
ir 2.6.0 · warp 1.8.0
generatedread out of the source that implements it

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.

app/renderables/product.ts
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.

FieldTypeRequired
namestringrequired
fragmentstringoptional
regionstringoptional
capabilitiesreadonly string[]optional
signedbooleanoptional
limitIntentLimitoptional
input(raw: unknown) => Ioptional
loadRenderableLoad<I>optional

Read from packages/weft/src/renderables.ts · RenderableDeclaration

namerequired

Type
string
Default
—

Human-readable, for a log and for the build report. Never on the wire.

name: 'product.details'

fragmentoptional

Type
string
Default
—

Which fragment renders it, by name under app/fragments/.

fragment: 'product/details'

regionoptional

Type
string
Default
—

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

Type
readonly string[]
Default
—

Capabilities the caller must hold. Unchecked capabilities are refused, not waved through.

capabilities: ['catalogue:read']

signedoptional

Type
boolean
Default
—

Reachable only with a signed, expiring token this deployment minted.

signed: true

limitoptional

Type
IntentLimit
Default
—

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

Type
(raw: unknown) => I
Default
—

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

Type
RenderableLoad<I>
Default
—

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)