Re-Frame: Build web apps in ClojureScript and React

I think the parent is correct to point out two things. That re-frame is useful in bigger teams and it is useful for larger apps.

Re-frame is somewhat more complex than inline and vanilla reagent. I suppose with hooks a lot of the simpler use cases for state management also go away.

That said, as a discipline the indirection re-frame encourages you to use helps you architect a purely functional* application. My observation is a lot of larger user facing applications will tend towards something that is event-driven and possibly loosely a state machine. Which incidentally also is one of the implementations of "functional core imperative shell"

Ultimately YMMV. If you just want a static site with a tiny bit of sparkle then you probably don't need reframe. (possibly you don't need cljs/reagent)

If you're tending towards a large full blown SPA with lots of interactivity and IO plus failure states, then reframe probably isn't a bad solution IMO.

* subscribe and dispatch are strictly not pure and actually use global state so purely functional isn't actually accurate. But it is a reasonable stab at being purely functional, while strongly quarantining the side-effecting bits.

Two main considerations:

Does the bundle size matter? CLJS bundles are not terribly huge but if you need a very lightweight bundle you're out of luck. Vs plain JS there is just no comparison. Vs plain JS + just a few libraries CLJS will probably do worse too. But for anything bigger it starts to catch up. Say I'd never use CLJS for a landing page, but for most kinds of apps there shouldn't be a problem.

How do you plan to interact with the wider JS ecosystem? One problem with CLJS is while you can pull in most JS stuff, it doesn't work the other way around. Your CLJS library will not be a first class citizen in the JS world. It can be done but it's not a good idea. You can contribute to the CLJS world, but forget about contributing anything significant back to the JS world.

If these two don't bother you, you should be fine.

> In my experience, this an unusual opinion

It can't be too unusual; I've seen this critique shared in forums, to which you've replied, for years.

I've seen developers remark how turned off they got by reading stuff like this on its front page, which is frankly just noise and undermines the goals of a serious project:

> re-frame is lucky enough to enjoy an unfair advantage...When we use Lisp, we get to leverage 50 years of foliated excellence from the very best minds available.

I mean, come on. The very best minds work in many different fields with many different languages. Lisp doesn't own the best minds, and neither does re-frame. The fact that lisp or Fortran or other languages have been around for many decades is kinda irrelevant, and this writing style permeates all the docs.

> Travel the geodesic.

> an immaculate hammock conception

The heart of the how-tos is often hidden in lengthy prose that celebrates itself.

Very happy re-frame user here - I was pleased to see the 1.0 release recently and I like the sound of the new developments.

Personally I do appreciate the amount of conceptual framing (pun intended!) contained in the re-frame docs. It's one thing to know the syntax for, say, declaring a subscription, but it's something else to know what subscriptions are for. For me, Re-frame's value-add is that it provides a bunch of sensible patterns for structuring an app, so this stuff clearly matters more than it would for other libraries.

That said, I think some of the basic elements of how to use re-frame are harder to find than they should be. There's the instant gratification "just show me some code so I know what I'm dealing with here" problem, where I think people just want to see a bit of sample code in order to orient themselves.

Re-frame has a very positive story here, because the API is very concise: you could show registering an event and a subscription, and subscribing and dispatch in the view layer in maybe 15 lines of code. For a new developer, the understanding that the API is mostly just two functions and two macros makes the whole thing look much less intimidating.

The reference docs are also a bit tricky to work with. The generated docs tell you about functions that you will probably never call, and crucially the generated docs don't include built-in effects. I'm sure there is some documentation on how to use `dispatch-n` somewhere, but I'm damned if I can find it and so I normally just read the source code to remind myself.

I've run a team with re-frame and a team with reagent (and a convention of a single state atom.) Reagent by itself scaled far better. I use re-frame if it's a company convention, but I'd far rather just ditch it.

Plain reagent has no unnecessary function registry; mutations are done with `(swap! my-cursor foo/update-foo bar)` rather than the extra overhead of `(dispatch [::foo/update-foo bar])`. This also helps new people who rely on cursive to jump to definitions, and don't have a preferred emacs setup.

Reagent testing can be scoped to a single DB. In re-frame, you can clear the subscription queue (which will not handle callbacks from network calls putting events on to the queue when the callback fires, leading to flaky tests that receive unexpected events.) In reagent, you have more power, since you can call `(reagent/atom {})` with your test state and any callbacks specfic to the test will see their DB, regardless of when they resolve.

Re-frame's single events/subscriptions files scaled horribly; once we got beyond a few hundred business-logic-filled events, velocity on changes involving that file slowed down a lot. We broke convention and moved events into namespaces closer to the code.