status-im
/
re-frame-10x
mirror of https://github.com/status-im/re-frame-10x.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

Readme Tweaks

This commit is contained in:
Mike Thompson 2017-12-02 23:27:29 +11:00 committed by GitHub
parent 74bfc1d491
commit d95591e97d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 12 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
README.md
View File

@ -1,7 +1,5 @@
# re-frame-trace # re-frame-trace
A debugging dashboard for re-frame epochs.
**Status:** Alpha. **Status:** Alpha.
[![Clojars Project](https://img.shields.io/clojars/v/day8.re-frame/trace.svg)](https://clojars.org/day8.re-frame/trace) [![Clojars Project](https://img.shields.io/clojars/v/day8.re-frame/trace.svg)](https://clojars.org/day8.re-frame/trace)
@ -10,13 +8,22 @@ A debugging dashboard for re-frame epochs.
## What Is It? ## What Is It?
`re-frame` applications have a regular computational path - first an event happens, `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 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 thereafter. reached. Nothing happens without an event, but when one does happen, it is the same process each time thereafter.
`re-frame-trace` is a programmer's dashboard `re-frame-trace` is a programmer's dashboard
which renders this regular computational process, allowing it to be inspected, understood and debugged. which renders this regular computational process, allowing it to be inspected, understood and debugged.
## A Dashboard?
`re-frame` generates detailed "trace data" as it runs, but most of it will be low level and uninteresting, much of the time.
As a "dashboard", `re-frame-trace` shows interesting, aggregated information "at a glance", while also allowing you to drill down and explore the detail as necessary.
## What's An Epoch?
Each `re-frame` event and its consequent computation forms a logically discrete "epoch" which should be analysed and inspected independently of other epochs. The dashboard design is epoch-oriented.
## Aspirational goals ## Aspirational goals
Here's the vision for what we'd like `re-frame-trace` to deliver (eventually): Here's the vision for what we'd like `re-frame-trace` to deliver (eventually):
@ -28,14 +35,6 @@ Here's the vision for what we'd like `re-frame-trace` to deliver (eventually):
- Debugging assitance. Particularly assitance for writing event handlers which hold most of the application logic. - 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. - A method for finding performance problems and detecting where there is unnecessary computation.
## A Dashboard?
`re-frame` generates detailed "trace data" as it runs, but much of it will be low level and uninteresting, much of the time.
As a "dashboard", `re-frame-trace` shows interesting, high level information "at a glance", while also allowing you to drill down and explore the detail as necessary.
## What's An Epoch?
Each `re-frame` event and its consequent computation forms a logically discrete "epoch" which can be analysed and inspected independently. The dashboard design is epoch-oriented.
## Sampler ## Sampler
@ -91,9 +90,9 @@ If you are using leiningen, modify `project.clj` in the following ways. When puz
## How does it work? ## 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. re-frame is instrumented - all important activity generates trace data. `re-frame-trace` consumes this trace data and 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. 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](https://github.com/clojure/clojurescript/wiki/Compiler-Options#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. The [preloads](https://github.com/clojure/clojurescript/wiki/Compiler-Options#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.