re-frame2

re-frame2

Authors re-frame2 ClojureScript application code. Router skill: this file carries decision shortcuts; depth lives one level deep in references/, patterns/, and decision-trees/.

When to load

.cljs / .cljc authoring of: event handlers, subscriptions, flows, state machines, views, schemas, routes, stories, or the canonical patterns. References to reg-event, reg-sub, reg-fx, reg-flow, reg-machine, dispatch, subscribe, app-db, flows, frames, regions, tags, or pattern names are sufficient triggers — re-frame2 need not be named.

When NOT to use

Full skill-disambiguation matrix lives at skills/README.md §Skill routing — single source. In brief: not for live-runtime inspection, greenfield bootstrap, v1→v2 migration, porting existing Reagent views onto Freehand (use reagent-migration), view code on the re-frame.ui donor substrate (defview and friends — use re-frame2-ui), porting re-frame2 itself, or spec / API / EP rationale reading.

This skill's view surface is the adapters — Reagent, reagent-slim, UIx, Helix. Freehand is re-frame2's re-frame-native peer view layer; references/fundamentals/views.md §Freehand carries what it changes and where its contract lives. Everything upstream of the view is the same either way, so the rest of this skill applies unchanged.

Cardinal rules

1. Implementation is ground truth. When spec and implementation/** disagree, the implementation wins. Recipes here are verified against implementation/** and examples/**.
2. Recipes over explanations. Use the canonical shape; do not re-derive from first principles.
3. Distinguish orchestration from state. State machines for modes (legal-transitions-depend-on-current-state); slices for fields. See decision-trees/slice-or-machine.md. Standing mental model for machines: think in xstate, then map onto re-frame2 — most concepts translate cleanly; a handful re-frame2 renames or omits, and those divergences are the trap. Translation catalogue: references/state-machines/xstate-translation.md; declaration grammar + divergence flags: references/state-machines/reg-machine.md.
4. Schemas at boundaries. Schema the paths that cross trust boundaries — HTTP payloads, persisted state, snapshot restores — and do not schema-fence every internal key. Which surface you reach for depends on when you need the check to run. reg-app-schema and handler :schema are development-build assertions: a production build registers them but never checks them, so they are tripwires that catch you in dev, not guards on the deployed bundle. Register them anyway — then, where untrusted data must be rejected in production too, give the handler that ingests it a :schema and reference the :rf.schema/at-boundary interceptor, which is the schema surface that survives the production gate. Details and the full behaviour matrix: references/fundamentals/schemas.md.
5. Match the canonical shape. When a pattern has a worked example or reference declaration, match its shape; don't re-derive. (Repo: examples/**; consumer app: the relevant pattern/fundamentals leaf plus any reference views your project follows.)
6. Frames before globals. Talk to a frame via dispatch / subscribe. Do not import frame internals or bypass to mutate state.
7. :rf/* is reserved. Application keywords pick their own feature prefix (:cart/..., :auth/...).
8. reg-* macros over the runtime-fn forms. Macros capture source coordinates that tools rely on; the functional counterparts — the *-suffixed twins for reg-view* / reg-machine*, or the same name in value position for everything else (reg-event, reg-sub, reg-interceptor, …) — are for advanced/programmatic cases only.
9. Pillar 4 — assume training knowledge. Teach the re-frame2-specific binding, not FSM theory / HTTP retry / React rendering.

Decision shortcuts

Slice vs machine vs region — decision-trees/slice-or-machine.md. Tell: if the prompt names transitions or modes, machine. If it names fields, flags, or counters, slice. A sub-concern of a larger feature's lifecycle is a region inside that feature's machine, not its own top-level machine.

Which pattern fits — decision-trees/pick-a-pattern.md. Quick map:

Patterns compose; a screen can use Forms on submit, RemoteData for the request, and WebSocket for a push.

Cross-cutting concerns — orthogonal to pattern choice; load alongside the primary leaf when the trigger fires.

Testing your views

"Does the screen show the right thing? Does the button dispatch the right event?" — use the hiccup-walk pattern (walk the view-fn's returned hiccup by :data-testid, not a browser-mount; state-only assertions miss the view-broken and wrong-frame-dispatch bugs the walk catches). Recipe: references/cross-cutting/testing.md.

Where the depth lives

Load at most two leaves per task. If a task seems to need three, it likely spans patterns and should be broken up.

Fundamentals — references/fundamentals/: events.md, fx.md, cofx.md (value-returning reg-cofx, :rf.cofx/requires), subs.md, views.md (reg-view, injected dispatch/subscribe, reg-view*), flows.md (reg-flow, flow-vs-sub), schemas.md, frames.md, images.md (rf/image, image-order composition, frame-isolation story — EP-0023), event-state-cycle.md, project-structure.md.

State machines — references/state-machines/: reg-machine.md (declaration, guards/actions, divergence flags), xstate-translation.md (the full xstate→re-frame2 catalogue), machine-schemas.md (:schemas :data/:output + snapshot redaction), regions.md (parallel), tags.md, spawn.md (child machines), history.md (:type :history re-entry), cancellation.md. Standing model across all: think in xstate, then map onto re-frame2.

Tooling — references/tooling/: stories.md, routing.md, story-recorder.md (record canvas interactions as a :script), story-mcp-loop.md (story-mcp author/refine side; run-loop handoff to re-frame2-pair), xray.md (devtools panel mount + launch modes). Standing model for Story: think in Storybook JS, then map onto Story (stories.md has the concept map).

Cross-cutting — references/cross-cutting/: testing.md (with-frame, dispatch-sync, compute-sub, view-tree walk), api-cheatsheet.md (one-page reg-* signature index), privacy-and-elision.md (path-based fail-open egress: owner classifies / framework projects / sinks consume; the six :rf.egress/* profiles), production-observability.md (rf/register-listener! on :events/:errors), ssr-authoring.md (reg-head/render-head/active-head + the :rf.ssr/check-* fxs), path-and-identity.md (the :rf/path algebra + canonical EDN identity).

Patterns — patterns/: one leaf per canonical pattern (see table above). Each opens with load triggers, the canonical mini-declaration, the features it uses, trade-offs, and the worked-example link. Pattern → example app: examples-map.md.

Decision trees — decision-trees/: pick-a-pattern.md, slice-or-machine.md.

Authoring workflow (every task)

1. Identify the surface — event? sub? fx? cofx? view? machine? route? story? schema?
2. Load at most two leaves (the relevant fundamentals or pattern; a second only if the task spans two surfaces).
3. Match the canonical declaration in the leaf; do not re-derive.
4. Pick the feature prefix (:cart/..., :auth/...) — never :rf/*.
5. Cross-check a worked example or reference view that uses the same shape when one exists (in the re-frame2 repo, that's examples/**; in a consumer app, your project's own reference views).
6. Schema only at boundaries.
7. Use reg-* macros unless the macro shape can't express the need.
8. Cut-test comments: would I write this same comment in a React / Vue / Elm app? If yes, cut it.

Done checklist

• Ids do not collide (grep the codebase for the chosen id).
• Schema registered for any new boundary.
• No :rf.* application keywords.
• Cut-test passed on comments.
• Shape matches the canonical declaration in the leaf.
• If a worked example exists, the new code's shape matches it.
• Hand off the gate to run — name the nearest relevant one concretely (e.g. "run clojure -M:test in src/app/"). This skill writes the code; the author runs the tests, the compiler, the app.

How re-frame2 differs from re-frame v1

Do not re-derive v1 mappings from training memory. Migration workflow + breaking-change rule index: skills/re-frame-migration/; authoritative rule corpus: migration/from-re-frame-v1/README.md.

Background reading (optional)

For "why does it work this way?" or a feature whose shape isn't obvious. All route via SKILL-REDIRECT.md at the repo root: Principles, Conventions, Construction prompts, EP design rationale.

re-frame2 (v2 line). v1: re-frame. Full skill-disambiguation matrix: skills/README.md §Skill routing — single source. Deep-dive links route through SKILL-REDIRECT.md.