ClojureScript Function Instrumentation

Function instrumentation is also supported when developing ClojureScript browser applications.

The implementation works by collecting function schemas using a ClojureScript macro which registers the function schemas available in the application.

Instrumentation happens at runtime in a JavaScript runtime. The functions to instrument are replaced by instrumented versions.

Dev Setup

For the best developer experience make sure you install the latest version of binaryage/devtools and use a chromium based browser:

https://clojars.org/binaryage/devtools

if you are using shadow-cljs just ensure this library is on the classpath.

For an application that uses React.js such as Reagent you will typically declare an entry namespace and init function in your shadow-cljs.edn config like so:

{...
:modules {:app {:entries [your-app.entry-ns]
:init-fn your-app.entry-ns/init}}
...}

In your application's entry namespace you need to tell the compiler to always reload this namespace so that the macro will rerun when you change schemas and function definitions in other namespaces while developing.

We do this with the {:dev/always true} metadata on the namespace:

(this was pointed out by Thomas Heller here. If you're still running into stale code issues during development you can try requiring all namespaces in a preload like he suggests in that comment)

(ns co.my-org.my-app.entry
  {:dev/always true}
  (:require [malli.dev.cljs :as md]))

and require the malli.dev.cljs namespace.

In your init function before rendering your application invoke malli.dev.cljs/start!

(defn ^:export init [] 
  (md/start!)
  (my-app/mount!)

When you save source code files during development and new code is hot-reloaded the non-instrumented versions will now overwrite any instrumented versions.

To instrument the newly loaded code with shadow-cljs we can use the lifecylce hook :after-load by adding metadata to a function and invoking malli.dev.cljs/start! again:

(defn ^:dev/after-load reload []
  (md/start!)
  (my-app/mount!))

Errors in the browser console

When you get a schema validation error and instrumentation is on you will see an exception in the browser devtools.

A validation error looks like this:

If you click the arrow that is highlighted in the above image you will see the error message:

and if you click the arrow highlighted in this above image you will see the stracktrace:

the instrumented function is the one with the red rectangle around it in the image above.

If you click the filename (instrument_app.cljs in this example) the browser devtools will open a file viewer at the problematic call-site.