https://github.com/flow-storm/flow-storm-cljs-compiler-plugin
A FlowStorm plugin to debug the ClojureScript compiler
https://github.com/flow-storm/flow-storm-cljs-compiler-plugin
Last synced: about 2 months ago
JSON representation
A FlowStorm plugin to debug the ClojureScript compiler
- Host: GitHub
- URL: https://github.com/flow-storm/flow-storm-cljs-compiler-plugin
- Owner: flow-storm
- Created: 2025-02-28T14:27:33.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2025-09-24T13:09:31.000Z (9 months ago)
- Last Synced: 2025-09-24T15:16:55.813Z (9 months ago)
- Language: Clojure
- Size: 624 KB
- Stars: 5
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: Readme.md
Awesome Lists containing this project
README
# FlowStorm ClojureScript compiler plugin
The ClojureScript compiler plugin helps you visualize and move aruod your ClojureScript compilations recordings
by representing them as an interactive graph.
It can help you troubleshoting the compiler, develope it or just help you learn how it works.
**Requires FlowStorm >= 4.3.0**
# Quick start
Clone the ClojureScript compiler somewhere :
```bash
git clone git@github.com:clojure/clojurescript.git
```
Add an extra alias to the deps.edn file :
```
{...
:aliases
{...
:storm {:classpath-overrides {org.clojure/clojure nil}
:extra-deps {com.github.flow-storm/flow-storm-dbg {:mvn/version "4.3.0"} ;; checkout the latest version
com.github.flow-storm/clojure {:mvn/version "1.12.0-9"} ;; checkout the latest version
com.github.flow-storm/flow-storm-cljs-compiler-plugin {:mvn/version "1.0.0-beta4"}} ;; checkout the latest version
:jvm-opts ["-Dvisualvm.display.name=CLJSCompiler"
"-Dclojure.storm.instrumentEnable=true"
"-Xms5000m" "-Xmx5000m"
"-Dflowstorm.startRecording=false"
"-Dclojure.storm.instrumentOnlyPrefixes=cljs."
"-Dflowstorm.plugins.namespaces=flow-storm.plugins.cljs-compiler.all"]}}}
```
You can see the latest dependency for the plugin here [](https://clojars.org/com.github.flow-storm/flow-storm-cljs-compiler-plugin)
Start a repl with the new `:storm` alias and start the debugger UI with recording stopped (default):
```bash
$ clj -A:storm
...
user=> :dbg
```
Now convert that repl into a ClojureScript one :
```clojure
user=> ((requiring-resolve 'cljs.main/-main) "--repl")
ClojureScript 0.0.398608251
cljs.user=>
```
A browser window should popup, and you should now have a ClojureScript repl.
Try to evaluate some forms to make sure everything is working smoothly.
# Usage
Let's say you want to understand the compilation of `(defn sum [a b] (+ a b))`.
- First start recording on the flow storm UI
- Now evaluate the form on the ClojureScript repl
- You should see recordings poping up on the FlowStorm UI Flows tab
- You can now safely stop recording
- Go to the `ClojureScript compiler` plugin tab
- Select the flow id you recorded in (0 by default) and click the refresh button
- You should see a graph rendering like in the screenshots above
## High level overview
The graph is composed of 4 main stages, some of them with their own sub graph.
- Reader (the output of the reader for your repl form)
- Repl wrapping (the wrapping the compiler does en every form that is typed at the repl)
- Analysis and parsing (analisys, parsing and optimizations)
- Emission (javascript code strings generation)
You can use the mouse left click for panning and the wheel for zooming.
Clicking on each stage `View return` should show the return value on the right data window, while
clicking `Goto return` should take you to the code stepper at that point in time.
## Understanding analysis and parsing
The analysis/parsing subgraph is composed of nodes that represent calls to `cljs.analyzer/analyze*` and `cljs.analyzer/parse`.
The greyed out nodes are the analysis/parsing of the wrapping parts while the highlighted ones represent your form analysis and parsing,
which is probably the most interesting one.
Each node shows the sub-form it is working with. Use the buttons to quickly view call arguments, return values and jumping
to the code stepper at those points in time.
Analysis nodes also contains a list of the `passes` which applied at that analysis instance. Double clicking on a pass will also take you
to that point in time.
## Understanding emission
The emission sub-graph is similar to the analysis one, but its nodes represent calls to `cljs.compiler/emit` for a certain AST `:op`.
It also contains a list of the javascript strings generated by that instance of emission. Double clicking on each strings will take
you to that point in time.
# Notes
It will also automatically snapshot some important mutable values used by the compiler :
- java.io.StringWriter
- java.lang.StringBuilder
- cljs.vendor.clojure.tools.reader.reader_types.SourceLoggingPushbackReader