re-frame applications have a regular computational path - first an event happens, and then boom, boom, boom go a series of dominos, before a final quiescent state is reached. Nothing happens without an event, but when one does happen, it is the same process each time.

re-frame-trace is a programmer's dashboard which renders this regular computational process, allowing it to be inspected, understood and debugged.

Aspirational goals

Here's the vision for what we'd like re-frame-trace to deliver (eventually):

Learning. If I'm new to re-frame, the dashboard should assist me to understand the dominoes and the data flows involved.
Codebase familialisation. It should help me to explore how an unfamiliar application is wired together. When I click on this button "X", it shows me what event is dispatch-ed and in what namespace the associated event handler is registered. And, "oh look, that's interesting - four subscriptions recalculated". Etc.
Debugging assitance. Particularly assitance for writing event handlers which hold most of the application logic.
A method for finding performance problems and detecting where there is unnecessary computation.

Sampler

Installation

If you are using leiningen, modify project.clj in the following ways. When puzzling over the various possible leiningen configurations, it's often helpful to look at a sample project.clj.

Add re-frame-trace as a dev dependency by placing [day8.re-frame/trace "VERSION"] within :profiles :dev :dependencies. For example:

:profiles
   {:dev
      {:dependencies [[some-other-package  "0.0.0"]
                      [day8.re-frame/trace "0.0.0 (see version above)"]] }}

Locate the :compiler map under :dev and add:

:closure-defines {"re_frame.trace.trace_enabled_QMARK_" true}
:preloads [day8.re-frame.trace.preload]

For example:

{:builds
   [{:id           "dev"
     :source-paths ["src" "dev"]
     :compiler     {...
                    :closure-defines      {"re_frame.trace.trace_enabled_QMARK_" true}
                    :preloads             [day8.re-frame.trace.preload]}}]}

cljs-devtools is not required to use re-frame-trace, but it is highly recommended.

Usage

Make sure you have followed all of the installation instructions above.
Start up your application.
Once it is loaded, focus the document window and press ctrl-h to slide open the trace panel and enable tracing.
When the panel is closed, tracing is disabled.

Troubleshooting

Try a lein clean
Make sure you have followed all the installation steps.

How does it work?

re-frame is instrumented - all important activity generates trace data. re-frame-trace is a consumer of this trace data which renders useful visualisations of the re-frame process. Currently, re-frame's tracing capabilities are in alpha and are subject to change at any time. We're testing the utility of the the trace by building an app on top.

By default, re-frame tracing is compiled out, so it won't impose a performance cost in production. The trade-off here is that you need to explicitly enable it in development.

The preloads option (:preloads [day8.re-frame.trace.preload]) has to be set in order to automatically monkeypatch Reagent to add appropriate lifecycle hooks. Yes this is gross, and yes we will try and make a PR to reagent to add proper hooks, once we know exactly what we need. The preload namespace also injects a div containing the devtools panel into the DOM.

Developing/Contributing

If you want to work on re-frame-trace, see DEVELOPERS.md.

Citations

open by Bluetip Design from the Noun Project