The ui-react components

That is worth knowing before you plan a sprint around it. What you get is a working app you own, not a kit of parts to assemble.

What is actually written

Adding React is the command that writes it, adopting an existing Vite app is the other route in, and front ends overview is the map.

A router, two globs and a shadow rule.

A session hook, a sign-out that says so when the session did not end, and a signed-in route guard. useSignOut() returns { run, pending, failure } as useAction does, and the scaffolded screens show the failure rather than a sign-in screen over a live session.

Sign-in screens — magic link, one-time code, callback — and the three a suspended or deleted account lands on, when the Worker composes auth.

A humanity-check widget, when turnstile is composed.

Paywall, pricing and subscription screens, when payments is composed.

An organization chooser and an invitation screen, when organization is composed: where somebody who belongs to more than one account picks the one to act in, and where an invitation link lands, at /invitations/:token. Reading the offer is public; accepting needs a sign-in, which comes back to the same screen.

A privacy-choices screen, when consent is composed: every purpose and where the person stands on it, to agree and to withdraw. It claims the consent screen role, so a “your privacy choices” link finds it by job.

An agent consent screen and a connected-applications screen, when auth and mcp are both composed: where an agent’s authorization lands and the one decision is made, and the list of applications acting as the person, with the revoke.

One screen of your own, written once and never again.

Two stylesheets: yours, and the one defining every class a Pithy screen renders.

The copied screens import those three from @pithy-sh/ui-core, so pithy ui add react writes it into the Worker’s dependencies on every scaffold, beside @pithy-sh/ui-react, which still exports them at src/read, src/action and src/redirect for screens scaffolded before. They are code you upgrade, not copies you own: a fix to them reaches your screens with the package rather than with a re-scaffold.

The router is two globs and a shadow rule

src/routes/pithy/*.tsx     Pithy's screens
src/routes/app/*.tsx       yours

Each route module exports its own path alongside its component. The router keys modules by that declared path, and yours shadows Pithy’s: a module in your directory declaring the same path replaces it entirely.

Adding a screen needs no edit and no re-run. Drop a file in with a declared path and it is routed. No route table to register in, no generated manifest, no command to run again — @pithy-sh/ui-core builds the table from the declared paths when the app loads.

Replacing a Pithy screen needs no fork. Write yours with the same path and yours wins. Pithy’s file stays on disk, unmodified and inert — delete it whenever you like.

A screen names its own path, and guards read it

The router sends a signed-out visitor to whichever screen declares the sign-in role, and a visitor short an entitlement to the one declaring the paywall role — at whatever path that screen declares.

So renaming a route is one edit, in one file, and every redirect follows it.

Claim a role from your own directory to take the job over, exactly as you take a path over. A role nothing claims throws rather than sending anybody nowhere.

The callback path is read, not repeated

The sign-in screen reads the callback path from the callback screen, so that rename is one edit too.

This is the one round trip you cannot check by being signed in — which is exactly why it is not left as two strings that agree today.

Co-located tests are not routes

Both globs negate the test-file names, so a test beside a screen is registered as nothing and reaches no bundle.

That negation is the one filename rule the router has, and it earns its place: without it the file is a route, and everything in it — fixtures, stub tokens, the shape of an endpoint and how it fails — is served to anyone who asks.

A companion file under another tool’s convention is not covered. Give it its own negation, or keep it outside the routes directory.

Reading data, running calls, leaving

The seeded screens call no useEffect of their own. Three exports carry what those effects used to do, and a screen of yours can use them the same way.

import { useRead } from "@pithy-sh/ui-core/src/read";
import { Redirect } from "../../router";

export const path = "/projects";

export default function Projects() {
  const projects = useRead("projects", (signal) => fetch("/api/projects", { signal }).then((r) => r.json()));
  if (projects.failure) return <p>Could not load your projects.</p>;
  if (projects.value === undefined) return <p>Loading…</p>;
  if (projects.value.length === 0) return <Redirect to="/projects/new" replace />;
  return <ProjectList rows={projects.value} />;
}

useRead(key, read, options?) loads data. It returns { value, loading, failure, refresh }. The read gets an AbortSignal that aborts when a newer key supersedes it or the screen unmounts, and an answer that arrives after either is dropped. A failed read lands in failure rather than throwing.

  • skip: true makes no request until a condition holds.
  • deadline, in milliseconds, aborts a read nobody answers and lands it in failure as a ReadTimeout.
  • once: true runs a read at most once per key for the life of the screen, StrictMode’s double mount included, for a read that costs something.

useAction(call) runs a call a person triggers. It returns { run, pending, failure, value }. A newer run aborts the older one through the same AbortSignal, and an unmount aborts the call in flight and sets no state.

<Redirect> leaves, as one of the states a screen renders. When an answer means “not here”, render it the way you render loading and failure: to for a path, or screen for whichever screen claims a role, plus replace for a correction the reader did not make and load to leave by a full document load. It navigates once and renders nothing, so the screen never draws its content on the way out.

The route guards are built this way. A signed-out visitor to a guarded route sees the loading line and then the sign-in screen, never the route.

Path parameters and the query string

A segment beginning with a colon is a parameter, and its value arrives as a typed prop rather than something you parse.

The query string is available the same way. Nothing here asks you to reach for the raw location.

What the client knows about your backend

Virtual modules, resolved in memory — not a generated types file on disk.

So there is no artifact to regenerate, nothing to gitignore, and no moment where the client and the backend disagree because somebody forgot to re-run something.

A capability’s client-safe projection is opt-in by construction: a new config field never reaches a browser bundle unless it is explicitly projected, and a capability with no browser surface projects nothing at all — the front end then reads a disabled flag.

What you are expected to write

Your design system. Every visual decision beyond the palette tokens.

Your components. Buttons, inputs, tables, modals, everything.

Your screens, beyond the one home screen and the auth flow.

Your layout and navigation.

That is a real amount of work, and pretending otherwise would waste your time. What the scaffold removes is the wiring — routing, session, sign-in, the asset allowlist, the build, the deploy — rather than the design.

Bring your own everything else

Nothing here is a dependency you cannot replace. A different styling approach, a different data-fetching library, a different component library — all fine, because the scaffolded files are yours from the moment they are written.

ESC