Debugging ClojureScript

A quick cheatsheet of approaches to debug ClojureScript code I’ve found useful.

Error messages and Source Maps

Error messages are pretty good in ClojureScript, especially in conjunction with source maps. Enabling source maps will get you a stack trace which points to a place where an error occurred in ClojureScript rather than in JavaScript compiled output.

Wrong number of args (0) passed to cljs.core/map at line 31 /Users/roman01la/projects/om-react/src/om_react/core.cljs

TIP: Use Figwheel. Because it’s an incredible productivity booster and it nicely logs out compilation errors into the browser.

Logging

Sometimes you want to use plain old console.log. You can do it in two ways in ClojureScript.

Call it directly from JavaScript:

(js/console.log "message")

Or use ClojureScript’s println:

(enable-console-print!)
(println "message")

While console.log is more familiar to JavaScript developers, println is much more useful. Because it knows how to print out ClojureScript specific things, like, for example, data structures.

console.log prints out ClojureScript’s hash map representation in JavaScript
println prints out the contents of ClojureScript’s hash map as console.log would do for plain JavaScript object

Breakpoints

Setting up a breakpoint is totally possible but I didn’t found it useful at all. Because scopes and variable names are messed up in compiled JavaScript. This happens due to the fact that ClojureScript is a very different language, it’s not one-to-one mapping with JavaScript. But the compiler tries to be smart and sometimes it is good enough to provide meaningful information.

The simplest and always working approach is to put JavaScript debugger statement into the code. It could be done like this:

(js* "debugger;")

With source maps enabled you can inspect ClojureScript code in DevTools and set a breakpoint. But in certain cases it would fail to stop on that breakpoint. Even though it stops, a call stack and variable names are not helpful all the time.

Bonus: in Chrome’s DevTools ClojureScript is automatically syntax highlighted.

A good example where things worked fine. The breakpoint worked in event handler and the name of the var in the Scope panel corresponds to the argument name in the code.

Third-party tools

cljs-devtools is a custom formatter utility for better presentation of ClojureScript values in Chrome’s DevTools. It’s smarter than println’s simple string representation: deep data structures are collapsable and everything is syntax highlighted. Because it relies on Chrome’s custom formatters feature this kind of formatting is present everywhere in DevTools where values could be seen: Scope pane, popup when hovering variable in Source pane, etc. Basically you’ll get same experience as you’d get with plain JavaScript objects when inspecting them in DevTools.

dirac is a DevTools fork which is developed specifically for ClojureScript development needs.

Also Closure Library’s debug utility has a list of interesting features. I’m not aware about it, but it might be worth to give it a try.

Conclusion

Debugging ClojureScript code looks like not much of a fun. But, in my experience (which is not that huge), I’ve never had to dig so much deeply into debugging to use something more than simple logging. That’s probably a beauty of Clojure: I’ve never been forced to debug the code as much as I did it to JavaScript.