Scaffold a front end into an existing Worker and wire it end to end — Vite, the SPA entry, the routes, the assets stanza, the dev command.
A new project can start with one: pithy init --target web or --target both runs the same scaffold into its first Worker, with no screens, because nothing is composed yet to sign in to. Run pithy ui add react once a capability with screens is.
pithy ui add react-native is the other stub, and it is the one that does not live in the Worker. It writes an Expo app for iOS, Android and the web into an apps/<name>/ of its own, which calls the Worker across origins. React Native: an app of its own is the command; React Native is the guide.
Adding React is the walkthrough, keeping routes in sync is what sync is for, and what lands in your tree is the ui-react components.
Synopsis
pithy ui add <framework> [--worker <name>] [--app <name>] [--ios-rail <rail>] [--android-rail <rail>] [--web-rail <rail>] [--auth | --no-auth] [--payments | --no-payments] [--organization | --no-organization] [--consent | --no-consent] [--dry-run] [--json]
pithy ui sync [--worker <name>] [--app <name>] [--ios-rail <rail>] [--android-rail <rail>] [--web-rail <rail>] [--check] [--json]
pithy ui list [--json]Flags
| Argument or flag | Applies to | Default | Purpose |
|---|---|---|---|
<framework> | add | required | The stub to scaffold: react or react-native |
--worker <name> | add, sync | resolved | The Worker under apps/ to scaffold into, or to re-derive. For react-native, the Worker the app calls |
--app <name> | add, sync | app (mobile when the Worker is app) | react-native only. The app’s own directory, apps/<name>. On sync, rewrite that app’s generated config instead of a Worker’s allowlist |
--ios-rail <rail> | add, sync | apple when the Worker enables it, else none | react-native only. The rail the iOS app sells through: apple, stripe, lemonSqueezy, paddle or none |
--android-rail <rail> | add, sync | google when the Worker enables it, else none | react-native only. The rail the Android app sells through: google, stripe, lemonSqueezy, paddle or none |
--web-rail <rail> | add, sync | the Worker’s first enabled hosted rail, else none | react-native only. The rail the web build sells through: stripe, lemonSqueezy, paddle or none |
--check | sync | false | Report the drift, write nothing, exit non-zero on a shadowed route — the CI gate |
--auth / --no-auth | add | see The screen sets | Scaffold the sign-in screens, or leave them out |
--payments / --no-payments | add | see The screen sets | Scaffold the paywall and subscription screens, or leave them out |
--organization / --no-organization | add | see The screen sets | Scaffold the account chooser and the invitation screen, or leave them out |
--consent / --no-consent | add | see The screen sets | Scaffold the consent settings screen, or leave it out |
--dry-run | add | false | Show the plan and write nothing. Every refusal still applies |
--json | all three | false | One line of machine-readable output. pithy ui never prompts under --json, nor under --no-input or PITHY_NONINTERACTIVE=1 |
There are no provider flags. No --google, no --github, no --turnstile. Which social providers exist, and whether a humanity check gates sign-in, is already declared in that Worker’s pithy.config.ts. A flag would be a second source of truth, frozen at scaffold time, that drifts the moment somebody enables a provider in config. The scaffolded screens read the composed config at runtime instead, so enabling a provider stays a one-line config edit and a redeploy.
The rail flags are not provider flags. Which rails exist is the Worker’s config, and the CLI reads it. Which one each platform of an app sells through is the app’s choice, made per platform, and the Worker cannot state it: one backend serves an iOS build that buys through StoreKit and a web build that buys through Stripe. So the flag picks among the rails the Worker enables, and a rail it does not enable is refused by name.
What it does
The SPA and the API deploy as one unit, on one origin, out of one apps/<name>/. One origin, one deploy is the argument for that; this page is the command.
Resolving the Worker
add and sync wire exactly one Worker, so they follow the same rule as pithy add: with a single Worker under apps/ the flag is optional; with several, the CLI prompts at a terminal and fails input/required, naming --worker, when it may not ask (--json, --no-input, PITHY_NONINTERACTIVE=1) rather than guessing. Scaffolding a front end into the wrong Worker would put an assets stanza and an asset-routing allowlist on a script that serves no browser.
ui list takes no --worker: it reports the framework stubs add can scaffold, not the Workers that already carry one. For the per-Worker view, use pithy worker list.
The screen sets
pithy ui add scaffolds up to four sets of Pithy’s screens, one per capability, and at a terminal it asks about each:
Scaffold the passwordless sign-in screens?
Scaffold the paywall and subscription screens?
Scaffold the account chooser?
Scaffold the consent settings screen?- The suggested answer is yes when the target Worker composes that capability —
auth,payments,organization,consent— and no when it does not. --auth/--no-auth,--payments/--no-payments,--organization/--no-organizationand--consent/--no-consentanswer them without asking. Where nobody may be asked (--json,--no-input,PITHY_NONINTERACTIVE=1), the suggested answer applies unless a flag is passed.- With auth on, the stub adds
src/routes/pithy/— the magic-link, OTP and callback screens, and the screens a suspended or deleted account lands on — and the router’s route guard. Payments adds the paywall, pricing and subscription screens; organization adds the account chooser and the screen an invitation link lands on; consent adds the settings screen where a person reads and withdraws their consents. Everything else is scaffolded either way. - The agent screens have no flag and no question of their own. They ride on
--authwhen the Worker composesmcp: the agent consent screen an MCP client’s authorization lands on, the connected-applications screen a person revokes an approval from, and a seeded gate for each. A Worker serving the endpoint without them would send every agent’s user to a page that does not exist.
Asking for a set on a Worker that does not compose its capability is an error rather than a warning.
What it writes
Every file is written only if it does not already exist. pithy ui add never overwrites, never merges and never reformats. A file already on disk is left byte-for-byte alone and reported as kept. The one exception is client-env.d.ts, which is generated in the kit rather than authored: a backfill rewrites it when it differs from the kit’s current emit, and reports it as refreshed.
That is the whole ownership model: Pithy authors a file once, and from that moment it is yours.
Path, under apps/<worker>/ | Written when | What it is |
|---|---|---|
index.html | always | The Vite entry document |
vite.config.ts | always | cloudflare() + react() + pithy() |
tsconfig.client.json | always | The client program — jsx and DOM, covering src/**/*.tsx |
tsconfig.node.json | always | The config program — types: ["node"], covering vite.config.ts |
client-env.d.ts | always | Ambient declarations for the virtual:pithy/* modules. Generated in the kit, so a backfill rewrites it when it differs from the current emit, and reports it under refreshed |
src/client.tsx, src/client.test.tsx | always | The SPA entry, and a seeded test that it mounts into a node it creates |
src/router.tsx, src/router.test.tsx | always | The two-glob router and its route guard, and a seeded test that a guard sends you to the path its screen declares. Both globs negate *.test.tsx and *.spec.tsx, so a co-located route test ships to nobody |
src/styles.css | always | Yours: the palette tokens, the reset, body |
src/pithy-screens.css | always | Pithy’s: every class name a Pithy screen renders, in a @layer pithy cascade layer |
src/pithy-config.tsx | always | Every virtual:pithy/* module, narrowed once for the screens. The consent screen narrows virtual:pithy/consent itself |
src/pithy-locale.tsx, src/pithy-locale.test.tsx | always | Resolves the reader’s language and keeps <html lang> on it, and a seeded test that the two agree. Renders its children untouched when nothing is composed |
src/session.tsx | --auth | The session hook, signOut and useSignOut, and the signed-in route guard |
src/turnstile.tsx, src/turnstile.test.tsx | --auth | The Turnstile widget and the token placement the middleware reads, and a seeded test that it solves for the action your config names |
src/routes/pithy/*.tsx | --auth | Pithy’s screens: sign-in, OTP, callback, and account suspended, account deleted, organization suspended. sign-in.test.tsx holds the link to the path callback.tsx declares, and otp.test.tsx sends a suspended or deleted account to its own screen |
src/routes/pithy/agent-consent.tsx, agent-consent.test.tsx, connected-applications.tsx, connected-applications.test.tsx | --auth, on a Worker composing mcp | The agent consent screen, the screen that lists and revokes what you approved, and a seeded gate for each |
src/payments.tsx, src/routes/pithy/paywall.tsx, pricing.tsx, subscription.tsx | --payments | The payments client bound to its base path, and Pithy’s paywall, pricing and subscription screens |
src/routes/pithy/choose-organization.tsx, choose-organization.test.tsx, invitation.tsx, invitation.test.tsx | --organization | The account chooser, the screen an invitation link lands on at /invitations/:token, and a seeded gate for each |
src/routes/pithy/consent.tsx | --consent | Every purpose and where the person stands on it, to agree and to withdraw. It claims the router’s consent screen role, and calls under the base path virtual:pithy/consent names, so a Worker composing consent({ basePath: "/privacy" }) is called at /privacy |
src/routes/app/home.tsx | always | Your first screen. Written once, never again |
The screen sets stack rather than choose. Which files a given invocation writes is decided by a named group in the library’s manifest rather than by directory: base is written always, auth rides on the auth capability, mcp on auth and the mcp capability together, payments on the payments one, organization on the tenancy one, and consent on the consent one. A Worker composing two gets both sets, because they name disjoint files over one layout — and that is what a later screen set costs too: a new group naming new files in the same tree, with no path moved and no import changed.
src/index.ts — the Worker entry — is not touched.
Both tsconfigs are composite, because both are referenced from the project’s root tsconfig.json, and each names a .tsbuildinfo under the project’s dist/ — never this Worker’s, which Vite empties on every build.
Two structural rules the stub depends on, worth knowing before you move a file:
- Every client file is
.tsx. The Worker’s existingtsconfig.jsonincludessrc/**/*.ts, which does not match.tsx, so the Worker’s type program ignores the client entirely and needs no edit. For the same reasonclient-env.d.tssits at the Worker root and not undersrc/— a.d.tsthere would match. - No
.tsfile in the Worker program may import a.tsxfile. The seam between a Worker and its client is runtime-only. One import across it pulls the browser build into the Worker’s type program, and the rule above stops holding.
What it wires
Four files are edited, and an edit touches the lines it means to change and no others. Every one of them is checked into your repository, so the writer prints what Biome would — short arrays on one line, an object left in whatever shape it already had, comments where you put them. A pithy ui sync that adds one path is a one-line diff, and its output passes biome check with no formatting step of your own.
wrangler.jsonc — the assets stanza. not_found_handling is "single-page-application", and run_worker_first is an explicit allowlist derived from that Worker’s composed route table — never true, and never a guessed prefix like /api/*. Pithy’s routes sit at capability base paths (/auth, /leaderboard, /payments, /storage, /media, …) plus /health; nothing lives under /api, and an allowlist that assumes otherwise hands GET /health the SPA shell.
Three derivation rules:
- Every entry is emitted in two forms, the bare path and its
/*glob, because"/auth/*"does not match a bare"/auth". - Never a bare-prefix glob.
"/media*"also captures/mediafoo; the pair"/media"plus"/media/*"captures the route table exactly. - The route table is taken once per environment, and the allowlist is the union. A Worker composes differently per environment —
@pithy-sh/authmounts/__pithy/dev-loginonly indev— so a single composition produces one environment’s table and calls it the Worker’s.CIis ignored while deriving, so--checkin CI andsyncon a laptop derive the same list from the same repository.
assets.directory is not written. Under the Vite plugin the directory is the plugin’s to set — it overwrites the key silently rather than erroring, so a value there would be a lie in your own config.
The array form of run_worker_first is what sets has_static_routing, and that is the whole mechanism. With it, not_found_handling applies to every request no worker-first pattern matched — so a listed route always reaches the Worker, and an unlisted one always gets the SPA shell, whatever the method. Without it, the asset worker overrides not_found_handling to "none" for every request that is not a navigation, which sends fetch and curl to the Worker and still hands the shell to a magic-link click or an OAuth callback. Both halves of that trade are silent 200s; the list is the half that can be checked.
pithy.worker.jsonc — the dev and ui blocks.
{
"dev": {
"autostart": true,
"readySignal": "ready in \\d+",
"command": ["bun", "x", "vite", "dev", "--configLoader", "runner", "--strictPort", "--port", "{port}"]
},
"ui": { "stub": "react", "build": ["vite", "build", "--configLoader", "runner"] }
}dev.command is what joins the front end to the dev set, {port} and all. --strictPort is not optional: without it Vite silently increments off a busy port, and a Worker that quietly moves breaks every sibling that was told its address at creation.
ui.stub records which stub was scaffolded — it is what makes a second add on the same Worker an error, and what tells add --auth it is backfilling a scaffold rather than starting one. ui.build is argv run through your package manager before wrangler deploy, so a UI-bearing Worker never ships a stale client.
Both commands carry --configLoader runner, and that is load-bearing rather than a preference: Vite’s default config loader bundles vite.config.ts and leaves @pithy-sh/vite external, which asks Node to import raw TypeScript with extensionless relative imports — Node cannot resolve those, and refuses to strip types under node_modules at all.
package.json — the client dependencies and the scripts that run them. React, @pithy-sh/i18n (the translator), @pithy-sh/ui-core (the hooks and the route table every seeded screen imports), @pithy-sh/ui-react (the same hooks at the paths screens scaffolded earlier import them from), the Vite plugins, and @pithy-sh/vite. Written at scaffold; pithy ui never revisits them. A @pithy-sh/* package a linked checkout already provides is left out of dependencies and devDependencies, and out of both lists in the --json result.
The project’s root tsconfig.json — the client’s two programs, appended to references. A program nothing references is a program nothing checks. They are appended after the Worker’s own, so tsc -b reports in layout order, and a re-run adds nothing. Extended, never created — a project scaffolded before the solution-file rule existed has Workers whose programs are not composite, and tsc -b refuses a reference to one of those outright.
pithy ui add --dry-run
The same scaffold and the same wiring, written into a private copy of the project under the system temporary directory, and the plan is the difference: every file it would create, and each of the four documents it would edit, with its diff. The copy is gone before the command exits, and the project is byte-identical. Everything the run decides first still decides — a Worker that already has a front end is refused, and the screens follow the same flags and the same composition — so the report beside the plan is the one the real run gives.
$ pithy ui add react --worker api --no-auth --dry-run
Would scaffold a react front end into api.
Would create apps/api/index.html.
…
Would edit apps/api/wrangler.jsonc.
Would edit tsconfig.json.
Dry run. Nothing written.pithy ui sync
run_worker_first is derived from the route table, and the route table changes whenever a route is mounted: by pithy add, by pithy remove, and by you writing one into your own app capability. That last one runs no command, which is how the list goes stale without anybody touching it. sync re-derives it and rewrites that one key.
It touches nothing else. No file is created, no dependency moves, no scaffolded screen is regenerated. It is idempotent.
--check writes nothing and reports what the list no longer covers. A shadowed route answers 200 text/html from the SPA shell with the handler never invoked, and no test suite of yours sees it — tests call handlers directly, so the asset router is never in the picture. So the check exits non-zero and belongs in CI, beside pithy doctor:
$ pithy ui sync --check --worker api
api: the SPA shell is answering these, not the worker.
/api/cli/device/start
/api/organizations
Run pithy ui sync --worker api.A route the allowlist cannot express is never reported: core’s own app.use("*"), and a route mounted at /, are paths the derivation deliberately leaves to the shell. A check that flagged them would mark every project drifted forever.
React Native: an app of its own
pithy ui add react-native writes an Expo app (SDK 57, React Native 0.86) into apps/<app>/, beside the Worker it calls rather than inside it. One Expo project builds iOS, Android and the web. The app has no wrangler.jsonc and no pithy.config.ts, so it is not a Worker: pithy deploy leaves it alone, and every command that composes Workers skips it. Nothing in Pithy builds the app for a store. A store build goes through EAS (eas build), and expo export --platform web is the web build. The web build calls the Worker by relative path with its cookie, so serve it from the Worker’s own origin. --worker names the Worker it calls, resolved the way every --worker is. --app names its directory, app by default. A directory that is a Worker, or that holds another stub’s front end, is refused.
The screen sets are decided as for react, against the Worker the app calls, with one difference: the account chooser and the invitation screen read the session the sign-in screens hold, so a run without --auth leaves them out, and refuses an explicit --organization. The files are @pithy-sh/ui-react-native’s templates: Expo Router’s app/ entry, app.config.ts, the Metro config that proxies the Worker’s paths in dev, the router adapter, the bearer transport, the session, and the screens, each under the same name as its DOM counterpart. Every app gets the base set: app.config.ts, metro.config.js, metro-proxy.cjs, metro-proxy.d.cts, tsconfig.json, vitest.config.ts, app/_layout.tsx, app/index.tsx, app/[...pithy].tsx, and under src/ theme.ts, platform.ts, pithy-config.ts, pithy-config.generated.ts, pithy-locale.tsx, router.tsx, route-modules.ts, transport.ts, routes/app/home.tsx and routes/app/home.test.tsx, nineteen files. Each screen set adds its screens and the helpers only they use: --auth the session, attestation.ts (the native attestation the email send uses where the environment takes it), the Turnstile WebView and the sign-in and account screens; --payments the payments client, its store bindings, and the paywall, pricing and subscription screens; --organization choose-organization.tsx and invitation.tsx; --consent consent.tsx; and mcp, riding on --auth, agent-consent.tsx and connected-applications.tsx.
Screen tests. The app runs its own: vitest.config.ts is nativeTestProject from @pithy-sh/ui-react-native/testing/vitest, which renders the screens through react-native-web in happy-dom with a stand-in for every native module, and the app’s test script runs it. Two tests are seeded. src/routes/app/home.test.tsx matches the home screen written: the bare one checks the Worker’s health route on the web and on iOS, and the signed-in one checks the guard and sign-out, reading the session from the secure-store stand-in on a phone. --auth adds src/routes/pithy/sign-in.test.tsx, on the web and on iOS. The kit’s own tests for every screen stay in @pithy-sh/ui-react-native. The root vitest.config.ts that pithy init writes leaves any apps/<name> with its own vitest.config.ts out of its node project. An older one collects every app’s src tests in plain Node, where a screen does not load. So in a project whose root config does not leave the app out, with neither the starter’s own-runner check nor an "apps/<app>/**" exclusion, the run writes no screen tests: no vitest.config.ts, no seeded test, no runner devDependencies and no test script. Your project’s test run stays green. The output and screenTests in --json say so, with the one line that adds them: add "apps/<app>/**" to the root config’s node project exclude, then run pithy ui add react-native --app <app> again. React Native has the stand-ins and how a test drives them.
What it wires. Two documents, both in the app’s directory, and nothing in the Worker:
pithy.worker.jsonc:dev.commandrunsexpo start --port {port}through the project’s package manager, sopithy devstarts the app beside the Workers on a pinned port.dev.readySignalis^Waiting on, the line Expo CLI prints once Metro listens with no terminal attached.ui.stubisreact-native, andui.buildisexpo export --platform web, recorded for you and never run bypithy deploy.ui.workernames the Worker the app calls, which is howpithy ui sync --appfinds it again.package.json: written with Expo Router’s entry andengines.node: ">=22.18"if absent, then merged like a Worker’s. Expo handsapp.config.ts’s import of the generated config to Node, which strips TypeScript types by default only from 22.18; React Native has the fix for an app scaffolded before. React, React Native,react-native-weband every native module at the version Expo SDK 57 bundles. The screen tests’ runner as devDependencies,vitest,happy-dom,@testing-library/reactand@pithy-sh/ui-react-native, and atestscript,vitest run.@pithy-sh/core,@pithy-sh/i18nand@pithy-sh/ui-coreat their own ranges. Every other kit package a written template imports gets a range whether or not the Worker composes it: the Worker’s own range first, so the app and the Worker run one release, then the project root’s, then the version installed under the project or beside the CLI, then the registry’slatest. A package none of them answers for is named in the output and inunresolvedPackages, and gets no line.
src/pithy-config.generated.ts. Metro cannot resolve virtual:pithy/*, so the composed config arrives as a file. It holds each capability’s client projection — auth’s, i18n’s, payments’, Turnstile’s and consent’s — for dev and for each of staging and prod the project deploys to, keyed like the origins; the Worker’s origin per environment; and five values that are yours: appScheme (the app’s name), universalLinkOrigin (the Worker’s production domain, then its staging one, else null), the Google client ids, playIntegrity (the Google Cloud project Android attests for, null until you set it), and rails. Set appScheme and universalLinkOrigin before a store build. The comment at the top of the file says how to change each rail. A build reads the projection for the environment EXPO_PUBLIC_PITHY_ENV names, so a prod web build renders prod’s Turnstile sitekey, and a build naming an environment the file has no projection for fails, naming the field. The consent screen and the transport’s visitor header follow consent’s projected base path.
Origins. origins.dev is the Worker’s local origin in the main checkout: the one the main checkout’s .dev.config.json pins for it, else http://localhost:8787. A run in a feature worktree writes the main checkout’s origin too, never the worktree’s own port, because the file is committed. Under pithy dev the app calls the worktree’s Worker anyway, through the origin pithy dev exports for it; React Native has how. origins.staging and origins.prod are present for each environment the project deploys to, and read offline the way pithy env reads them: the Worker’s domains declaration, then its route in wrangler.jsonc, then its vars.BASE_URL. One none of those names is null. A Worker that answers only on workers.dev is the usual case, since that address takes the account to resolve: set the origin in the file by hand. The app picks one when it is built, from EXPO_PUBLIC_PITHY_ENV (dev, staging or prod, dev when unset), which Expo inlines into the bundle. A phone build naming staging or prod stops at launch when that origin is unset or not https, naming the field to set, since the bearer credential goes there. The web build needs none. On Android a localhost or 127.0.0.1 dev origin is reached through 10.0.2.2, the emulator’s address for this machine. A device on your network needs this machine’s network address in origins.dev, and the Worker listening there.
Sign-in returns to the app. A sign-in started on a phone returns to the app’s scheme, and to its universal link when one is set, and auth refuses either unless its trustedOrigins names it. So ui add says which entries to add, quoted exactly: "<appScheme>://", and universalLinkOrigin when it is set. When the Worker composes auth it reads trustedOrigins from the loaded config and names only the missing entries, in the output and in untrustedOrigins. When it does not, it names the entries to add once it does.
Screens that need sign-in. The account chooser and the invitation screen read the session the sign-in screens hold. --organization with the sign-in screens left out is refused by name; left to decide, it is left out.
Rails. One per platform. --ios-rail, --android-rail and --web-rail decide outright. Without one, a person at a terminal is asked, offered only the rails the Worker enables, starting from the default; anyone else gets the default. The default is the platform’s store on a phone and the Worker’s first enabled hosted rail on the web, and none wherever the Worker enables no such rail, so a default is never a rail the Worker refuses. none shows plans and sells nothing. A web rail on a phone opens checkout in the system browser. Whether a store allows that link out is your call; React Native names the rules.
A backfill. pithy ui add react-native on an app that already exists adds the screens it lacks, --auth after --no-auth say, and rewrites src/pithy-config.generated.ts from the Worker the way pithy ui sync does. Your five values are kept, and a backfill does not prompt for rails: a rail already written stays unless a rail flag sets it now. The run says the config was rewritten.
pithy ui sync --app <name>. Rewrites the app’s generated config from the Worker its manifest names, or the one --worker names. The projections, every environment’s, and the origins are the Worker’s and are rewritten, with two exceptions: an origin you set for an environment the Worker names none for is kept, and so is a dev origin that is not this machine’s loopback. Your five values are kept, except a rail a flag sets now. A --worker other than the one the manifest names points the app at it: the manifest’s ui.worker is rewritten, so the next sync without --worker finds the same Worker. Every rail is held to the Worker again, so one it has stopped enabling is refused by name. A file that is not the config Pithy writes is refused rather than overwritten; delete it to start from the defaults. --check writes nothing and exits 1 when the file is behind the Worker, in any environment’s projection.
$ pithy ui add react-native --worker api --no-auth --no-payments --ios-rail none
Scaffolded a react-native app into apps/app. It calls api. Bare template.
19 files created.
Rails: iOS none, Android none, web none.
apps/app/src/pithy-config.generated.ts holds api's config. Set appScheme and universalLinkOrigin there before a store build.
When api composes auth, its trustedOrigins needs "app://".
Change api's config, then run pithy ui sync --app app --worker api.
Install the packages: bun install. Then pithy dev.
Done.--json
One line, one object, one shape per subcommand.
$ pithy ui add react --worker api --json
{"command":"ui.add","schemaVersion":2,"dryRun":false,"worker":"api","deployedAs":"pithy-app-api","framework":"react","auth":true,"payments":false,"organization":false,"consent":false,"created":["client-env.d.ts","index.html","src/client.tsx", …],"skipped":[],"unstyled":[],"runWorkerFirst":["/auth","/auth/*","/health","/health/*"],"packageManager":"bun","dependencies":["@pithy-sh/i18n","@pithy-sh/ui-core","@pithy-sh/ui-react","react","react-dom"],"devDependencies":["@cloudflare/vite-plugin","@pithy-sh/vite", …],"scripts":["dev","build","preview"],"next":[{"command":"bun install","why":"ui add wrote 13 packages into package.json, and the build needs them installed."}]}$ pithy ui sync --worker api --json
{"command":"ui.sync","schemaVersion":1,"worker":"api","deployedAs":"pithy-app-api","before":["/auth","/auth/*"],"after":["/auth","/auth/*","/leaderboard","/leaderboard/*"],"changed":true,"uncovered":[],"notFoundHandling":"single-page-application"}| Key | Type | Meaning |
|---|---|---|
command | string | The subcommand’s dotted name: ui.add, ui.sync or ui.list |
schemaVersion | integer | The version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one |
worker | string | add, sync. The apps/ directory the front end was written into, and what every path in the same payload is relative to. For react-native, the Worker the app calls |
deployedAs | string | add, sync. The Worker’s deployed script name — what the Cloudflare dashboard shows |
framework | string | add. The stub that was scaffolded |
app | string | add, and sync with --app. react-native only: the app’s own apps/ directory. On add, created and skipped are relative to it. Absent for react |
rails | object | add, and sync with --app. react-native only: { ios, android, web }, the rail each platform sells through. Absent for react |
trustedOrigins | string[] | add. react-native only: the entries auth’s trustedOrigins needs for the app, "<appScheme>://" and universalLinkOrigin when it is set. Absent for react |
untrustedOrigins | string[] | add. react-native only: the entries of trustedOrigins the Worker’s auth config does not list. Empty when nothing is missing or the Worker composes no auth. Absent for react |
unresolvedPackages | string[] | add. react-native only: kit packages the app’s templates import that no source had a range for, so its package.json declares none. Absent for react |
backfill | boolean | add. react-native only: whether the app already existed, so this run added screens to it and rewrote its generated config from the Worker, keeping your five values. Absent for react |
screenTests | object | add. react-native only: { seeded, remedy }. seeded says whether the app’s screen tests were written: vitest.config.ts, the seeded tests, the runner’s devDependencies and the test script. When they were left out, because the root vitest.config.ts would run them in plain Node, remedy is the one line that adds them; null when they were written. Absent for react |
auth | boolean | add. Whether Pithy’s sign-in screens were scaffolded |
payments | boolean | add. Whether the paywall and subscription screens were scaffolded |
organization | boolean | add. Whether the account chooser and the invitation screen were scaffolded |
consent | boolean | add. Whether the consent settings screen was scaffolded |
created | string[] | add. The files this run wrote, worker-relative and sorted |
skipped | string[] | add. The template’s files already on disk, left byte-for-byte alone |
refreshed | string[] | add, on a backfill. The generated files already on disk that differed from the kit’s current emit and were rewritten with it: client-env.d.ts. Empty when it was current. Absent on a first scaffold and for react-native |
unstyled | string[] | add. Class names Pithy’s screens render that no stylesheet in the Worker defines. Empty on an ordinary run; anything else is the exact list to fix |
runWorkerFirst | string[] | add. The asset-routing allowlist derived from that Worker’s composed route table |
packageManager | string | add. The package manager the scripts were written for |
dependencies | string[] | add. Only what this run added |
devDependencies | string[] | add. Only what this run added |
scripts | string[] | add. Only what this run added |
dryRun | boolean | add. Whether this was --dry-run. Nothing was written when it is true, and every other key is what the run would report |
plan | object | add, under --dry-run only. Each file created or edited, with its diff |
next | object[] | add only. [{ command, why }]: the project’s install (bun install, pnpm install, …) when this run wrote dependencies into the Worker’s package.json, or for react-native into the app’s, because the build fails without them. Absent when it wrote none, and under --dry-run; never empty |
before | string[] | sync. The allowlist before the run. Empty with --app |
after | string[] | sync. The allowlist after it. Empty with --app |
changed | boolean | sync. Whether the call moved anything — the allowlist, or a not_found_handling it had to write. With --app, whether the generated config differs from the Worker’s, which under --check is the finding |
uncovered | string[] | sync. The routes the list in the file does not cover. Empty after a write; under --check it is the finding, and the one thing that fails the exit. Empty with --app |
notFoundHandling | string | sync. Reported because SPA routing depends on it and sync does not overwrite a value you chose. Absent with --app |
stubs | object[] | list. Each stub’s id and description: react, and react-native |
created, skipped and, on a backfill, refreshed are worker-relative and sorted; together they are every file the template declares, so a backfilling run reports the untouched ones rather than staying silent about them. A backfill skips every file already there except a generated one: client-env.d.ts is the kit’s emit and not yours, so one that differs from the current emit is rewritten and listed under refreshed, and a virtual:pithy/* module declared since the scaffold reaches the screens the backfill adds. The human run names it on a line of its own. unstyled is the second claim: wrote the screens and the screens are styled are two things, and only the first was ever reported. It is read off the stylesheets as they stand on disk after the write, not off the template, because a stylesheet you have since edited is the case it exists for.
With --app, sync touches no allowlist. changed says whether the app’s generated config differs from what the Worker gives now, and under --check that is the finding. before, after and uncovered are empty, notFoundHandling is absent, and app and rails are present.
Errors
Each is a problem line then an action line, and the process exits by its class: 2 for a call to fix, 3 for something in the way that has to change first. pithy ui sync --check exits 1 when it finds something, because its report is the answer, and Ctrl-C at the screens prompt exits 130.
Unknown framework. Exit 2.
$ pithy ui add svelte --worker api
No UI stub named "svelte".
Run pithy ui list to see the frameworks you can add. Known: react, react-native.A UI is already there. Exit 3. The check is the manifest’s ui block rather than the presence of files. The stub is scaffolded once; a second add would create nothing and imply otherwise. A Worker carrying a different stub is refused the same way: one Worker, one front end.
$ pithy ui add react --worker api
api already has a react front end.
Add screens by dropping files into src/routes/app/. Run pithy ui sync --worker api to re-derive its route allowlist.A template file already on disk. Exit 3. A first scaffold never overwrites a file it did not just write, so one that finds one names every such file and writes nothing.
--auth, --payments, --organization or --consent without its capability. Exit 3, core/precondition_failed, with the pithy add that composes it as its fix. For auth that is pithy add auth --worker api --with-prerequisites, since auth declares secrets and email.
$ pithy ui add react --worker api --auth
The auth screens need the auth capability, and api doesn't compose it.
Run `pithy add auth --worker api --with-prerequisites` first, or leave them out with --no-auth.pithy ui sync on a Worker with no front end. Exit 3, and the action names that Worker: Run `pithy ui add react --worker api` to scaffold one.
pithy ui sync --app on a directory with no React Native front end. Exit 3, core/not_found.
$ pithy ui sync --app mobile
apps/mobile has no React Native front end.
Run pithy ui add react-native --app mobile, naming the worker it calls with --worker.--organization with --no-auth on react-native. Exit 2, validation/invalid_input: The account chooser needs the sign-in screens, and this run leaves them out. The action reads Pass --auth, or leave the account chooser out with --no-organization.
A rail a platform cannot sell through. Exit 2, validation/invalid_input, listing the ones it can: Pass --android-rail google, stripe, lemonSqueezy, paddle or none. On sync, a rail kept in the generated config is held to the same list, so a hand-edited rails.android of apple is refused the same way, naming the key.
A rail the Worker does not enable. Exit 3, core/precondition_failed, naming the rail and the key that turns it on, before anything is written. A Worker that composes no payments at all gets the pithy add payments fix instead.
$ pithy ui add react-native --worker api --android-rail google
The google rail isn't enabled in api's payments config.
Enable rails.google in apps/api/pithy.config.ts, or pass --android-rail none.--app or a rail flag with react. Exit 2. The React front end lives in the Worker it calls and has no rails of its own. On sync, a rail flag with no --app is refused the same way.
An apps/<name> that is a Worker, or holds another front end. Exit 3. An --app naming the Worker the app calls is exit 2.
Several Workers, no --worker, where nobody may be asked. The same input/required refusal pithy add raises, naming the Workers it found. Exit 2.
pithy ui sync --check finding an uncovered route or an unstyled screen. Exit 1. Not an error line: the report above is the finding.
Examples
pithy ui add react --auth
pithy ui sync --worker api
pithy ui sync --check --worker api
pithy ui list
# An Expo app beside the api Worker, selling through StoreKit on iOS and Stripe on the web.
pithy ui add react-native --worker api --ios-rail apple --web-rail stripe
# Rewrite that app's config after the Worker's changed.
pithy ui sync --app app