Skip to content

26 - Operating well

You've read the guide. You have the mental model: the six dominoes, the single app-db, derivative views, effects as data, and the trace/epoch evidence that tools can read. This chapter is the operating map: where to find examples, reference docs, patterns, tools, skills, and migration help when the tutorial stops being the right shape.

A word on what this guide deliberately didn't cover, so you know where the edges are. The guide is the human-facing narrative track: a story you read once, front to back, to build intuition. It is intentionally not exhaustive — it teaches the shapes and the why, then hands you off to the reference track for the precise contract. Everything below is that handoff.

Build something with it

The single fastest way to make the pattern stick is to write code in it, and you don't have to start from a blank file. The worked examples are a graded sequence — start at the pedagogical end and move toward the benchmarks:

  • Pedagogical sketches — counter, login, routing, ssr, managed_http_counter, state_machine_walkthrough, counter_with_stories. Each isolates one piece of the surface and shows it composed end-to-end. Read them in order if you're new; cherry-pick if you're not. The counter_slim_and_fast variant from chapter 22 is here too, byte-for-byte identical to the canonical counter except for the adapter.
  • Benchmarks — todomvc, the seven_guis cluster, nine_states. These are the size-and-stress tests; they exercise the same primitives the sketches introduce, but in fuller compositions. nine_states in particular is the parallel-state-machine pattern from chapter 12 made concrete.
  • RealWorld scaffold — realworld/. The broad worked sketch: routing, auth, forms, paginated lists, and SSR boot in one app. This is the "what does a real one look like?" answer.

Fork the one closest to what you're building and change it until it's yours. That's the recommended on-ramp.

Look up the contract — the spec

When you need the precise answer rather than the narrative one — the exact shape of an effect map, the full failure taxonomy, the normative grammar of a state-machine spec — you want the spec. The guide is downstream of it; the spec is the artefact. Start at the spec index, then reach for the document that owns your question:

  • spec/000-Vision.md — the philosophy and the AI-first thesis, in normative voice.
  • spec/Principles.md — the nine practical principles the whole design serves.
  • spec/Ownership.md — the "where does X live?" reference. Every contract surface mapped to its owning spec. When you're not sure which document answers your question, start here.
  • spec/Conventions.md — the reserved namespaces (the :rf/* scheme from chapter 24), reserved fx-ids, reserved app-db keys, the id-prefix and packaging conventions.

The numbered specs are the per-feature contracts: 001-Registration, 002-Frames, 004-Views, 005-StateMachines, 006-ReactiveSubstrate (the nine-fn adapter contract from chapter 22), 007-Stories, 008-Testing, 009-Instrumentation (the trace bus from chapter 16), 010-Schemas, 011-SSR, 012-Routing, 013-Flows, 014-HTTPRequests, and 015-Data-Classification (the :sensitive? / :large? story from chapter 23).

And the spec ships something most specs don't: it's written to be implementable in any language. The pattern stops being a ClojureScript thing and becomes a thing you could have in TypeScript or Python or Kotlin. If you want re-frame2's shape on a different substrate entirely, the spec is the blueprint — not the CLJS reference implementation.

Look up the API

For signature-level lookup — what arguments does this function take, what does it return — the API reference is the contract-shaped complement to this guide's narrative. It's split by surface: core, views, effects, machines, flows, routing, http, schemas, ssr, testing, instrumentation, registrar, lifecycle, and adapters. There's also a removed-surfaces page that's worth a glance if you're coming from v1 and a name you remember has vanished.

Look up a pattern by name

When you hit a recurring shape — async work, websockets, forms, remote data, app boot — a Pattern doc names the canonical answer. Patterns are conventions built on top of the framework's primitives, closer in voice to this guide than to the API reference, and they're the right next stop when the shape of your problem matches one of them:

Watch your app from the inside — the tooling

You learned the framework; now meet the tools that read its trace bus. These are peers to this guide, each with its own section in the top menu, and each goes far deeper than chapter 17 — Tooling could.

  • Xray — re-frame2's in-app inspection panel, the cascade you can see. It renders the framework's own trace bus and epoch buffer into a stack of live panels: every event, sub-run, effect, render, machine transition, app-db diff, and time-travel scrub, scoped per frame. It's the v2 successor to v1's re-frame-10x — reimplemented from scratch, not ported (see chapter 25). Start at Xray — Welcome and read top-to-bottom.
  • Story — a frame-aware component playground, Storybook-flavoured but built on re-frame2's own primitives. The Story tutorial walks the surface; counter_with_stories is the worked example.
  • The pair tool — re-frame2-pair-mcp, the MCP surface that lets an AI agent attach to your running app: inspect a frame's app-db, dispatch events, hot-swap handlers, read the trace stream, and time-travel. The re-frame2-pair skill (below) is how you drive it.

Put an AI agent to work — the skills

re-frame2 is AI-first by design, and the skills/ directory is where that stops being a slogan. These are Claude Code skills you invoke when an agent should do the work:

  • re-frame2-setup — scaffold a new re-frame2 app from scratch.
  • re-frame2 — the authoring skill: design and write re-frame2 code (events, subs, machines, schemas) with the framework's conventions baked in.
  • re-frame-migration — the v1→v2 migration driver from chapter 25. The recommended path for any real port.
  • re-frame2-pair — pair-program against a running app via the Tool-Pair contract. Attach to a live nREPL, inspect a frame, dispatch, hot-swap, replay the cascade that broke. This is the one to reach for when you have a runtime in front of you and a bug you can't see.
  • re-frame2-xray — drive the Xray inspection surface from an agent.

Migrating from v1

If you have an existing re-frame v1 app to bring across, chapter 25 — From re-frame v1 is the narrative version of the story: what carries over (almost everything), what changed and why, and the two shapes worth understanding in depth (managed HTTP, flows). The mechanical version is the re-frame-migration skill — feed it your project and answer the judgment-call questions. Don't hand-migrate anything larger than a toy.

Where re-frame came from

A little lineage, because nothing this shaped appears from nowhere. The original re-frame was Mike Thompson and the day8 team's answer, in mid-2014, to a question ClojureScript SPAs kept raising: Reagent gave you a beautiful V, but where does the rest of the app go? The answer was assembled from the ideas in the air at the time — Pedestal's interceptor chains (v2's interceptor stack is a direct descendant), Flux's single direction of data flow, Om and early Elm's reactive view layer driven by a typed message stream, and the CQRS / command-query-separation intuition that changing state and reading state want to be different-shaped things (in re-frame, the gap between events/effects and subscriptions/queries). Beneath all of it sits the ClojureScript substrate: Rich Hickey's language, Dan Holmsand's Reagent and its ratom, and the community habit of treating data as the load-bearing primitive. re-frame didn't invent any of that. It composed it into a shape worth keeping.

v2 builds on the same lineage. Frames add runtime isolation; everything else — the six dominoes, the data-first event log, derived subscriptions, the centrality of app-db — is inherited. The bones are the same, and now you know them.

So: write something. Read the trace stream. Open a frame in the pair tools and watch state move. Pick the example closest to what you're building and fork it. Welcome to re-frame2.