Open-source project
day8/re-frame2 avatar
day8/re-frame2

re-frame2: a spec-first ClojureScript framework that treats views as derived data

https://day8.github.io/re-frame2/

54 stars0 forksClojureMIT

At a glance

What is it?
re-frame2 is a rework of the classic re-frame pattern for React-based single-page apps. It puts a formal specification ahead of the code, models the app as a small virtual machine, and makes every external effect a managed, data-driven primitive.
Who is it for?
Adopt re-frame2 if you are building a React SPA in ClojureScript and you want a strict, event-driven architecture where views stay derivative and effects are managed as data. Do not adopt it if you need a mature, battle-tested framework with a large ecosystem, or if you cannot accept the extra ceremony of a spec-driven design that is still under active development.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 16 days ago.
What is it written in?
Mainly Clojure, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • day8/re-frame254 ★ · +8
Star history
Repository2026-08-212026-11-15
day8/re-frame24654

8 Stars in the last 86 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The problem: frameworks where the implementation is the truth

Most frameworks start with code. The implementation is written, then documentation tries to describe it, usually imperfectly. re-frame2 inverts this. The specification in the spec/ directory is the artefact. The ClojureScript implementation in implementation/ is a consequence of that spec, not the source of truth. The README claims the spec is complete enough that a capable AI could one-shot a working implementation from it. That is a bold claim, and it is also the core value proposition. If you do not like the spec, you can change it and roll your own framework in any language that cross-compiles to JavaScript and reaches React: TypeScript, Melange/ReScript, Fable, PureScript, Scala.js, Kotlin/JS, Squint. The intended audience is a developer who wants a stable, well-defined pattern, not a framework that evolves by accretion of features.

The architecture: a frame as a virtual machine

The central metaphor is that a re-frame2 frame is a small virtual machine. You register handlers, and those handlers form the instruction set. Events, coming from user actions or other sources, are the instructions. The frame processes them as an event stream, running the same pipeline for every event with no escape hatches. One turn of that pipeline is called an epoch. This is a strict, predictable model. Views are derivative, not causal. They do not own state, they do not fetch data, they do not route. They simply render from the current state. This is a deliberate rejection of the modern React trend where components accumulate hooks and effects. The README quotes the author: "Your language of choice should be Turing complete; your architecture shouldn't be." That is the point of view, and it is a coherent one. The trade-off is that you lose the flexibility of component-local state, and you must funnel everything through the event pipeline.

Getting started: what the repository gives you

The repository layout is clear: spec/ contains the specification documents, and implementation/ contains the ClojureScript reference implementation. The README does not provide explicit installation commands, so you will need to look at the implementation directory for build tooling. The project uses ClojureScript, so you will likely use tools like lein or shadow-cljs, but the README does not say which. The spec is the entry point for understanding the pattern. There is a specific document for WebSocket patterns, spec/Pattern-WebSocket.md, which shows how to build a managed WebSocket from primitives. The README mentions that the framework ships a focused set of managed effects: :rf.http/managed for HTTP, :spawn and :spawn-all for state machines, and an SSR per-request lifecycle. It explicitly does not include a managed WebSocket. That is a deliberate scoping decision, and it means you will need to read the spec to roll your own.

Managed external effects: one shape for all async

The managed external effect is the key innovation. Every outbound async interaction, HTTP, websocket, postMessage, socket.io, IPC, push notifications, background workers, server-side fetches during SSR, conforms to a single primitive shape. Effects are data, returned from handlers, not invoked as callbacks. The framework owns retry, abort, fan-out, in-flight registry, teardown, observable trace events, and privacy elision via :sensitive? and :large? flags. There is a structured failure taxonomy under each surface's :rf.<surface>/* namespace. The README claims that once you learn the model, you apply it everywhere. That is the promise. The reality is that the built-in set is small. You get HTTP, state machine spawns, and SSR lifecycle. WebSockets are not built in, but the pattern document shows how to build one that composes like the built-ins. This is a strong design if you value consistency over convenience. It is a weak design if you need a rich set of integrations out of the box.

Tooling and traceability: the app as surveillance state

Because every event runs through the same pipeline, the framework can provide a single, deeply integrated trace bus. Every event leaves an epoch that you can scrub through forwards and backwards. Tools can attach to this bus and see deep into a running program. The README mentions that with the ClojureScript implementation you can get trace form-by-form, meaning statement-by-statement, but not by default. That is a significant capability for debugging and for AI pair-programmer tooling. You can set policies to elide sensitive things like auth tokens and large binary blobs. This is a genuine differentiator. Most frameworks do not offer this level of observability out of the box. The trade-off is that the trace bus is only as good as the spec and the implementation. If the spec changes, the trace format changes. You are betting on the stability of the spec.

Limitations and when it is the wrong tool

The most obvious limitation is that this is a young project. The README is a manifesto, not a user manual. The repository has no published GitHub releases. The implementation is a reference, not necessarily a production-ready library. The spec-first approach means the code is secondary, but you still need code that works. If you need a mature framework with a large community, re-frame2 is not that. The README even admits it does not include a managed WebSocket, so you must build your own from primitives. That is a non-trivial task. Also, the architecture is strict. If you want to use React hooks for local state, or if you want to fetch data inside a component, re-frame2 will fight you. It is the wrong tool for a small prototype where you want to move fast. The ceremony of defining handlers and effects for every interaction is overhead. The README says the spec is complete enough for an AI to one-shot an implementation, but that is a claim, not a verified fact. You should verify that the spec actually covers your use case before adopting.

Alternatives: how re-frame and Redux differ

The direct alternative is the original re-frame, which is the same axe but with different bits, as the README puts it. re-frame is a mature ClojureScript framework with a large community and years of production use. The difference is that re-frame is implementation-first. The code is the truth, and the documentation describes it. re-frame2 is spec-first. That changes how you approach the framework. You can read the spec and understand the entire pattern before writing any code. With re-frame, you learn by reading source and examples. Another alternative is Redux, which the README says was directionally right but clunky and incomplete. Redux also uses a single store and pure reducers, but it does not have the same managed effect model. Redux effects are typically handled by middleware like redux-thunk or redux-saga, which are separate integrations. re-frame2's managed effects are built into the core, and they all share the same shape. That is a real difference in approach.

Maintenance and licensing

The project is MIT licensed, which is permissive. You can use it, modify it, and fork it. The README encourages forking the spec. The maintenance cost depends on the spec. If the spec changes, the implementation must change to match. The README does not mention a versioning policy or a migration guide. The repository has no published GitHub releases, so you should treat it as pre-1.0. The spec is the durable artefact, but the code is what you run. You will need to track changes in the spec and the implementation manually. The trace bus is a deep integration, so if you build tooling around it, you will be tied to the spec's trace format. That is a maintenance risk. The MIT license gives you the freedom to fork, but you also take on the maintenance burden if the upstream project stalls.

Editorial conclusion

Adopt re-frame2 if you are building a React SPA in ClojureScript and you want a strict, event-driven architecture where views stay derivative and effects are managed as data. Do not adopt it if you need a mature, battle-tested framework with a large ecosystem, or if you cannot accept the extra ceremony of a spec-driven design that is still under active development. Before committing, verify that the current implementation covers the exact external surfaces you need (HTTP is built in, WebSockets are not), and check the spec for the trace bus policies to ensure you can elide sensitive data as required. The project is MIT licensed, so you can fork it, but the real value is in the spec, which you can also fork and reimplement in another language.

Frequently asked questions

What is a re-frame?

In this repository re-frame2 is an architectural pattern for building single-page apps on a virtual-DOM substrate, React in practice, in which the specification is the artefact and the ClojureScript implementation is downstream of it rather than the source of truth.

What is the relationship between re-frame2 and the original re-frame?

The README describes re-frame2 as the same axe as the earlier re-frame, made from different bits and with new ornamentation. A migration/ directory at the repository root holds the path from the older library.

What is a frame in re-frame2?

A frame is a small virtual machine. Registered handlers are loaded into it as an instruction set, and events from user actions and other sources run through the same pipeline with no exceptions or escape hatches. One turn of that pipeline is called an epoch.

How does re-frame2 handle HTTP and other calls to the outside world?

Through managed external effects. Effects are data returned from handlers rather than callbacks, and the framework owns retry, abort, fan-out, the in-flight registry, teardown, trace events, elision of sensitive and oversized values, and a failure taxonomy under each surface's :rf.<surface>/* namespace.

Does re-frame2 ship a managed WebSocket?

No, deliberately. It ships a focused set of surfaces, and spec/Pattern-WebSocket.md shows how to build one from the primitives so that it composes exactly like the built-ins.

How is the re-frame2 documentation site built?

With MkDocs, pinned exactly: mkdocs 1.6.1, mkdocs-material 9.5.44, pymdown-extensions 10.21.3 and pygments 2.20.0. The imaging extra needs Pillow and CairoSVG, and CairoSVG needs the Cairo and Pango system libraries, which CI installs before the pip step.

Official sources

  1. Official README
  2. Project repository
  3. README
  4. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/day8-re-frame2.svg)](https://hysenlabs.com/projects/day8-re-frame2)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/day8-re-frame2.svg)](https://hysenlabs.com/projects/day8-re-frame2)

Was this useful?