Repository navigation
Client Data
Every browser request goes through one function, and every entity row it returns lands in one
record per entity:id. You never write fetch, never write a store, and never mirror a row
into a signal by hand. Declare the entity, return its row, call the typed client.
Shipped in 21.0.0, both halves: the HTTP seam and the store that receives its records, with the
hooks that read it. The store is installed the first time a realtime hook runs on the page; records
answered before that wait on the page handle until it is. The design is
docs/architecture/21-client-data-layer.md.
| Task | Write | Status |
|---|---|---|
| declare what a record is | entity('post', { columns: { id: uuid().primaryKey(), … } }) |
shipped |
| an action that returns a record |
output: Post.$schema, or a schema that contains it |
shipped in 21.0.0 |
| a query whose rows are records |
rows: Post.$schema on query()
|
shipped in 21.0.0 |
| call an action from an island | rpc<Api['actions']>({ baseUrl: '' }) |
shipped; now goes through the one transport |
| call a query from an island | queryClient<Api['queries']>({ baseUrl: '' }) |
shipped; now goes through the one transport |
| ignore an answer for a principal that signed out | if (isSuperseded(error)) return; |
shipped in 21.0.0 |
| any other failure |
isUltimateError(error), then switch on error.code
|
shipped |
| install realtime in an island | nothing: x build does it for every island whose own graph imports @ultimat3/realtime. An island that reaches realtime only through a package calls installRealtime({ signal: createSignal, cleanup: onCleanup }) in mount — cleanup releases each hook with its component (31.14.0) |
shipped in 21.0.0 |
| show one record in a component |
useRecord('post', id): record type, then record key, from @ultimat3/realtime
|
shipped in 21.0.0 |
| show a list |
useQuery({ name: 'postList', entity: 'post' }, input), or { name, live: true } for a live query |
shipped in 21.0.0 |
| read once, no socket |
useQuery({ name: 'postList', entity: 'post' }, input) with no live — one HTTP GET through the query client, rows into the same store. Nothing opens a socket (packages/realtime/src/use-query.ts): a list that needs no push needs no timer either — never poll |
shipped in 21.0.0 |
| re-read a list on a timer |
useQuery(ref, input, { poll: pollEvery(ms) }) on a non-live ref — refetch through core's visibleInterval, in the bundle only of an island that imports pollEvery: no read while the tab is hidden, one make-up read when it shows, none after a lost session, stopped by release(). The safety read beside an at-most-once channel. A live ref refuses poll by type. Never a hand-rolled setInterval
|
shipped in 30.0.0 |
| poll what has no changefeed |
visibleInterval(run, ms, { maxMs? }) from @ultimat3/core/page, the disposer from onCleanup: no call while the tab is hidden, one make-up call when it shows; with maxMs each failed run (a throw or rejection, re-raised for the page's error hook) doubles the wait up to it, jittered, and a success resets it to ms; an async run is never overlapped. The first X_UNAUTHENTICATED / X_SESSION_EXPIRED on a page rendered for a principal is a lost session: every visibleInterval stops, sessionIsLost() is true and onSessionLost(fn) fires once (late subscribers at once) until rescope(). An anonymous page's 401 is never a loss. The sign-in UI is the app's. guards/raw-interval.ts refuses a bare setInterval( in an island |
shipped in 30.0.0 |
| follow a channel | declare it on one ref in two halves: channelRef('org-feed', { params, catchUp }) for the browser, channel(ORG_FEED, { records, policy }) on the server. Then useChannel(ORG_FEED, { orgId }, { onEvent, onPresence }) in the island: records reach the store, events the handlers. usePresence(ORG_FEED, params) for a roster. An island whose only realtime is this is never hidden while it boots (Realtime) |
shipped in 21.0.0 |
| redraw markup that holds other islands |
disposeIslands(node) from @ultimat3/render/client on each element being dropped, before or after it leaves the page: every island under it (and the node itself, when it is one) has what its mount returned called, and one that never booted mounts nothing. Never read el.__x yourself |
shipped in 27.6.0 |
| sign out | an action (the reference app's endSession, POST /api/sessions/end), posted by a native form, whose response appends signOutHeaders() from @ultimat3/auth: Clear-Site-Data: "cache", "storage" empties the page store, local storage and the service worker's cache. The redirect is a full navigation, so the next document carries the new scope |
shipped in 21.0.0 |
| keep a record type on disk across reloads |
entity('post', { columns, persist: true }). Default false: a record is private data, and disk is a decision |
shipped in 21.0.0 |
| write with an optimistic update |
useMutation({ name: 'renamePost', local, conflict }), posted over HTTP |
shipped in 21.0.0 |
Never write fetch(, new WebSocket( or new XMLHttpRequest( in an island, or in anything an
island imports. x verify's boundaries step refuses it with X_BROWSER_TRANSPORT_BYPASS and
names the line — in every app, As of 2026-10. Built in, not a file in guards/: there is no
opt-out and no allowlist.
| The raw call was | Write instead |
|---|---|
an action (POST /api/…) |
await browserClient.<action>(input) — rpc<Api['actions']> in shared/browser-client.ts
|
a read (GET /_x/query/…) |
useQuery(<QUERY_REF>, input); outside a component, await browserQueries.<query>(input)
|
a socket or an EventSource
|
useQuery(<QUERY_REF>, input) for rows, useChannel(<CHANNEL_REF>, params, { onEvent }) for events |
| a file upload |
await uploadFile({ file, grant, onProgress }) from @ultimat3/storage — the presigned PUT is its, not yours |
| anything else |
await clientTransport({ method: 'GET', url }) from @ultimat3/core/page
|
| a page or fragment that answers HTML, CSV or plain text |
await clientTransport({ method: 'GET', url, responseType: 'text' }) — the body as a string, never read off onResponse
|
| Fact | Rule |
|---|---|
| browser-reachable | every *.island.tsx, every module that calls clientTransport / pageClient itself, and what each imports — followed name by name through barrels, into the app's own packages/*
|
| not reported | a route.ts, a job, a task, a test: server code no island imports |
| the package boundary | the walk stops at node_modules. @ultimat3/*'s three seams are trusted, never re-read |
| a server barrel |
@ultimat3/entity or @ultimat3/query imported for a VALUE in that closure is X_BROWSER_SERVER_BARREL; the fix names @ultimat3/entity/record / @ultimat3/query/client
|
| cannot see | a browser module that is no island, names no seam and is imported by neither; a request inside an installed package; globalThis['fetch']; a bare fetch( in a file that binds its own fetch
|
// app/posts/entity.ts
import { entity, text, uuid } from '@ultimat3/entity';
export const Post = entity('post', {
columns: { id: uuid().primaryKey(), orgId: uuid(), title: text({ max: 120 }) },
});The record type is the entity name (post). The record key is the primary key, in declared order.
Nothing else is declared.
// app/posts/actions/rename-post.ts
import { action, t } from '@ultimat3/action';
import { Post } from '../entity';
import { postWrite } from '../policies';
import { repo } from '../repo';
export const renamePost = action({
input: t.object({ postId: t.uuid, title: t.string }),
output: Post.$schema, // or t.object({ post: Post.$schema.nullable() }): found at any depth
policy: postWrite,
handle: ({ input }) => repo.rename(input.postId, input.title), // returns the WHOLE row
});Because the output schema references Post.$schema, the response is { data, records } with the
header x-ultimate-records: 1. Nothing to declare. .pick(), .omit() or .extend() on the row
schema drops the brand, so a partial row never overwrites a full record.
// app/posts/queries.ts
import { from, query, t } from '@ultimat3/query';
import { Post } from './entity';
import { postRead } from './policies';
import { repo } from './repo';
type PostRow = typeof Post.$row;
export const postList = query({
input: t.object({ orgId: t.uuid }),
policy: postRead,
rows: Post.$schema, // without this line the rows never reach the store
sql: ({ orgId }) =>
from<PostRow>('posts', () => repo.list()).where({ orgId }).orderBy('id'),
});sql: names its table as a string, so rows: is the one place the schema comes from. Leave it
off and the query still works, but its answer is bare rows the store never sees.
// shared/browser-client.ts — type-only import of the api, so no server code reaches the island
import { rpc } from '@ultimat3/action';
import { queryClient } from '@ultimat3/query/client'; // the browser entry: 11,012 B vs 25,237 B via the barrel
import type { Api } from '../api';
export const browserClient = rpc<Api['actions']>({ baseUrl: '' });
export const browserQueries = queryClient<Api['queries']>({ baseUrl: '' });| Fact | Rule |
|---|---|
| who writes the file |
x new — apps/web/shared/browser-client.ts, both lines, with browser-client.test.ts beside it |
| app size | both lines typecheck at any size — pinned at 300 actions in 100 modules and 100 reads in 50 (client-scale-pins.ts in each package). As of 2026-10; before, a 48th module in one defineApi list was TS2589 |
pathStyle |
stated nowhere here. The server stamps defineApi({ http: { pathStyle } }) into the document; the browser derives every action URL under it |
// app/posts/rename.island.tsx
import { isSuperseded, isUltimateError } from '@ultimat3/core';
import { browserClient } from '../../shared/browser-client';
export async function rename(postId: string, title: string): Promise<void> {
try {
await browserClient.renamePost({ postId, title }); // returns `data`, the envelope is stripped
} catch (error) {
if (isSuperseded(error)) return; // the page changed principal: render nothing
if (isUltimateError(error) && error.code === 'X_CLIENT_TRANSPORT_FAILED') {
// no usable answer: the network, a proxy, or a non-JSON body
}
throw error;
}
}baseUrl: '' is the page's own origin. A browser chunk has no process.env.
| # | Where | What happens | Status |
|---|---|---|---|
| 1 | server | the action or query route runs rowsOf(schema, answer), collecting every branded row as record type → record key → row |
in tree |
| 2 | wire |
{ data, records, removed? } behind x-ultimate-records: 1. An answer with no entity rows is byte-identical to before |
in tree |
| 3 | browser |
clientTransport decodes the envelope, checks the principal has not changed, and calls pageClient().store.adopt(type, rows)
|
in tree |
| 4 | browser | the one RecordStore per tab, shared by every island through globalThis[Symbol.for('ultimate.client')], updates the record once |
in tree (packages/realtime/src/page-store.ts). Installed by the first realtime hook on the page. Until one runs, step 3 finds no store and the page holds the records (packages/core/src/pending-records.ts), handing them over on install |
| 5 | component | every useRecord / useQuery showing that record re-renders, with no refetch |
in tree |
| Code | When | Fix |
|---|---|---|
X_CLIENT_TRANSPORT_FAILED |
no usable answer: the network refused, a proxy answered a non-2xx with no framework code, or a 2xx body was not JSON |
x doctor --json checks the network and the gateway in front of the app, then retry. A write with no idempotencyKey may already have landed |
X_CLIENT_SCOPE_CHANGED |
the page changed principal while a read was in flight |
if (isSuperseded(error)) return;, then read again under the new principal |
X_CLIENT_RECORD_ENVELOPE_INVALID |
a response carried x-ultimate-records: 1 and a body of the wrong shape |
build the body with encodeRecordEnvelope() from @ultimat3/core in the handler that set the header, or stop setting the header |
X_RECORD_KEY_MISSING |
a returned row lacks a primary-key column |
x entities show <entity> --json lists the key. Return the whole row |
X_MUTATOR_CLOCK_MISSING |
a mutator declares conflict: 'last-write-wins' and its entity has no number updatedAt, or its output has no entity row |
add updatedAt (a number, epoch ms, written by the server) to the entity, or declare conflict: 'server-wins'
|
X_REALTIME_UNINSTALLED |
a realtime hook ran in an island that never called installRealtime()
|
x build. If the island reaches realtime only through a package, call installRealtime({ signal: createSignal, cleanup: onCleanup }) in its mount
|
X_RECORD_REJECTED |
a row reached the store with no key, or not as an object |
x entities show <entity> --json lists the key. Return whole rows |
X_CONTRACT_DRIFT |
the client bundle and the server are on different builds | reload the page to pick up the new client bundle |
Full rows: Error codes.
By default the build groups islands by route. Islands rendered on exactly the same set of
routes are one split build: a module they share is one /islands/chunk-<hash>.js the page fetches
once. Every other island is built alone, self-contained, so no route pays for an island it does
not render. The groups are read from each page.tsx's island({ src }) declarations
(packages/cli/src/island-groups.ts). Measured As of 2026-11-10: the reference app's
/posts/:id (three islands on that route only) 95,754 → 65,676 B; every other route unchanged.
islands: { sharedChunks: true } in app.config.ts is one group holding every island. Off by
default, by measurement (packages/core/src/config-islands.ts): tree shaking across one build
keeps what any importer uses, so an island that takes one helper from a module the others use
heavily pays for all of it — the reference app's plain-DOM update banner went 712 → 16,288 B.
| Turn it on when | Leave it off when |
|---|---|
| shared code cached across pages is worth more than each page's first-visit bytes | an island is small and plain-DOM, or the islands share little |
x build --target static, then x verify --only budgets, shows no route growing |
any route's budget.js grows past its budget |
Layering: the last config layer that states sharedChunks wins; absent everywhere is false
(mergeIslands). A value that is not a boolean is refused at boot (X_CONFIG_INVALID). As of 2026-11.
Off by default, by measurement. Each island build inlines the part of Solid it uses, ~14 kB
tree-shaken. islands: { vendorSolid: true } in app.config.ts builds Solid ONCE instead, as
/islands/vendor-solid.<hash>.js (solid-js, solid-js/web, solid-js/store, whole: 48,083 B,
17,388 B gzip), and every island imports it. Named by its bytes, like every island output
(packages/cli/src/island-vendor.ts). Measured As of 2026-11-12, Bun 1.4.4, solid-js 1.9.17.
| Turn it on when | Leave it off when |
|---|---|
| a route renders four or more Solid islands that are built apart (not one route group) | a route renders one to three Solid islands — every Solid route of the three tracked apps grew 33,572–38,769 B with it on |
x build --target static, then x verify --only budgets, shows the routes shrinking |
any route's budget.js grows past its budget |
The vendor counts once per route in budget.js, is precached and preloaded like any shared chunk,
and adds one request. An island that imports no Solid loads no vendor. An islands.vendorSolid
that is not a boolean is X_CONFIG_INVALID.
An island's mount draws through mountOver (@ultimat3/render/client): it clears the
server's markup for the live render — Solid's render APPENDS — and puts that markup back when
the render throws, then rethrows. The hydration runtime still marks the root data-x-failed, and
clientErrors still reports it once. A visitor sees the server's HTML, never an empty box. 167 B
in a chunk; framework-neutral (the caller hands in the draw).
import { mountOver } from '@ultimat3/render/client';
import { render } from 'solid-js/web';
function Counter(props: { start: number }) {
return <p>{props.start}</p>;
}
export function mount(el: HTMLElement, props: { start: number }): () => void {
return mountOver(el, (root) => render(() => <Counter {...props} />, root));
}x g island, x new and the resource form island write it. An app scaffolded earlier adopts
through the island-mount-clears guard, which x new ships and an older app installs:
| Step | Command |
|---|---|
| install the guard | x g guard island-mount-clears |
find each island that empties its wrapper outside mountOver
|
x verify --only boundaries — one finding per clear, at its line |
| fix each | delete el.textContent = '' and end mount with return mountOver(el, (root) => render(() => <Island {...props} />, root))
|
The guard reads .textContent = '', .innerHTML = '' and .replaceChildren() on mount's own
first parameter in a *.island.tsx that calls no mountOver(. A clear of an element INSIDE the
wrapper — a handler emptying an output region — is the island's own business and is not read.
As of 31.15.0.
Ultimate — v31.48.0 As of 2026-10. The full-stack framework where the primary developer is an AI agent: bunx create-ultimate myapp → Getting started · live demo. MIT licensed. What npm serves is npm view @ultimat3/core version, never this line, and this footer is the only page that stamps a version.
Repository · Issues · Changelog · llms.txt
Edits to these pages are synced from wiki/ in the repository — change the file there, not the wiki, or the next sync overwrites it.
Start
- Getting started
- Installation
- Shapes
- Bare VM
- Project layout
- Migrating an existing app
- Compared to other stacks
Tutorials
- 1 · First app
- 2 · First feature
- 3 · Auth and admin
- 4 · Jobs and realtime
- 5 · Deploy free
- 6 · Growing up
Primitives
- The eight primitives
- Building your own base
- Actions
- Entities and migrations
- Policies and authz
- Queries and live queries
- Client data
- Jobs and workflows
- Scheduled tasks
- Routes and render modes
Capabilities
- Realtime
- Caching and invalidation
- Batching and preloading
- N+1 detection
- PWA and offline
- Client navigation
- MCP and AI
- Agents
- Working with many agents
- Admin dashboard
- Scraping
- Auth
- Notify
- Storage and uploads
- Feature flags
- SEO
- Static assets
Cross-cutting
- I18n
- Theming
- UI components
- Interface rules
- Timezones and dates
- Money
- Outbound HTTP
- Resource management
- Migrations and backfills
- Testing
- CI: the gate across parallel jobs
Reference