How-to guides¶
Each page here completes one task in an app you already have running: a form, login, a slow view, production error reporting. A recipe states the goal, shows the complete code, and links to the concept page for the why instead of re-teaching it.
Testing has its own section.
If your views are Fresco
The view code in these recipes is written for a React substrate adapter with reg-view views: the adapter's client-root / render! to mount, @(subscribe …) to read, ^{:key} metadata on list items, and Form-2 views where a value has to stay stable across renders. Fresco has its own h/client-root / h/render! mount calls, h/defview views and h/sub reads; translate the view code using its conventions. Everything below the view carries over unchanged: events, effects, subscriptions and frames. For the view and the mount, read Installation and Views and reads; for the debugging recipes, Diagnostics and Performance.
Build it¶
| I want to… | Recipe |
|---|---|
| boot and mount the app, with hot reload | Boot and mount an app |
| add login and keep the user logged in | Add authentication |
| build a form: local edits, validation, clean submit | Build a form |
| use a React component from npm, such as a date picker | Use a React component |
| load a feed one page at a time | Paginate a feed |
| refetch the right server data after a write | Invalidate after a mutation |
| catch bad state and malformed events early | Validate with schemas |
Debug it¶
Every dispatch records what it did on the trace stream, one epoch per event (Observability explains how). These recipes read that record.
| I want to… | Recipe |
|---|---|
| see exactly why the app just did that | Debug with Xray |
| find the view that re-renders too much, and stop it | Find and fix a slow view |
To inspect a running app instead — read a frame's app-db, dispatch events, hot-swap a handler from your editor — use the pair skill.
Ship it¶
| I want to… | Recipe |
|---|---|
| keep tokens, passwords, and large blobs out of traces | Keep secrets and large things out of traces |
| hear about production errors with their full context | Report errors in production |
| set up dev and production builds | Configure dev and production builds |
| render with UIx or reagent-slim instead of Reagent | Use UIx or reagent-slim |
When a recipe is the wrong shape¶
Some questions are design decisions rather than tasks:
- "Should this value be a subscription, a flow, a resource, or a machine?" See Where should this value live?
- To watch one app grow through auth, feeds, forms, and invalidation in order, follow the RealWorld tutorial.
- For the exact shape of a public function, use the API reference.