faq.md

CLJS DevTools FAQ

What is the :formatters feature?

You can log some javascript objects with your own printing routine. Basically you can register a javascript handler which will be called by DevTools console to present object in the console. This handler can output rich formatting / expandable-structure (JsonML).

Read more in this Google Doc.

CLJS DevTools provides a rich set of custom formatters tailored to ClojureScript.

What is the :hints feature?

Sometimes your DevTools displays cryptic errors like Cannot read property 'call' of null. The problem is in the way how ClojureScript compiler emits function calls.

The :hints feature is an attempt to augment uncaught exceptions and error object to include a bit of additional knowledge related to such errors. It tries to fetch the original source file, extract relevant part to show you more context and mark the javascript error there. This is expected to work only with :optimizations none compiler mode and it is disabled by default because it relies on monkey patching. But it is worth it:

Note <<< ☢ RETURNED NULL ☢ <<< part which points to error location. The uncaught error was raised by calling sanity-test-handler in the following code:

(defn fn-returns-nil [])

(defn sanity-test-handler []
  ((fn-returns-nil) "param"))

You can enable the feature in the config:

:external-config {
  :devtools/config {
    :features-to-install    [:formatters :hints]
    :fn-symbol              "F"
    :print-config-overrides true}}

Or you can enable the feature when calling install!:

(devtools.core/install! [:formatters :hints])

Technical details are described in the source file.

What is the :async feature?

This is an experimental feature. Please note that this feature is no longer needed in Chrome 65.0.3321 and newer.

Chrome DevTools support async call stacks. It would be great to see full chains of async stack traces for code generated by ClojureScript compiler, especially when using core.async library. To give you concrete picture, we want to see this instead of this.

There are currently following problems:

1. core.async uses goog.async.nextTick which is not recognized by Chrome DevTools as async operation participating in async stack traces.
2. Chrome DevTools UI has hard-coded limit for displaying max 4 chained async stack traces which is not enough for common state-machines generated by core.async go macros.
3. go-loop tends to generate state-machines which have very long chains of async stack traces but with repeated patterns for each loop iteration.

CLJS DevTools cannot solve problems #2 and #3, but it can help with #1 by monkey-patching goog.async.nextTick.

The trick is to replace goog.async.nextTick with a promise-based implementation. ES6 promises participate in Chrome DevTools “async” feature and we can use immediately resolving promises to emulate nextTick behaviour.

For problems #2 and #3. I have raised the issue in Chromium issue tracker as issue #622506. If you want to follow the issue it is also issue #20 in our issue tracker.

Realistically I don't expect Google people to resolve this somehow anytime soon. It is not really that big concern for typical javascript code at the moment.

That is why I'm going to implement experimental support in Dirac DevTools for this. I have already increased maxAsyncStackChainDepth limit and eventually I will write some code to reduce number of stack traces in go-loop chains.

That is why this feature is currently experimental and does not make a lot of sense to enable it without using Dirac DevTools as well.

Why some custom formatters were not rendered?

BREAKING:

Are you using Chrome 84 or later?

Enabling custom formatters in the devtools settings is not longer sticky. Custom formatters are likely to be removed later this year.

Please follow the issue here

UPDATE:

Chrome developers reconsidered removing the custom formatters feature.

All works the same as before for now. Please make sure you are using the latest Chrome (Canary) update.

---

First, custom formatters must be enabled in DevTools Settings:

> DevTools menu > Settings (F1) > Console > Enable custom formatters

The feature is disabled by default and it is easy to forget to enable it after starting with a new Chrome profile.

Second, please note that custom formatters is a feature of DevTools UI, but console logging is a general feature of Javascript runtime. When logging happens while DevTools is not attached a different logging system is used for recoding console logs in background. When DevTools later attaches, existing recorded logs are replayed in the DevTools Console UI. Unfortunately during this replay process no custom formatters are applied, so you can see only raw logs. There are probably some technical reasons for this behaviour.

To see properly formatted logs you have to refresh your page while DevTools are attached. Any newly printed logs should have custom formatters applied assuming you have enabled the feature in the DevTools Settings.

This behaviour caused some confusion among users so I implemented a detection and since v0.7 we print a warning when custom formatters seem not to get rendered.

You can disable this warning by setting this pref prior installation or via config map:

(devtools.core/set-pref! :dont-detect-custom-formatters true)

Why custom formatters do not work for advanced builds?

There is a technical glitch which currently prevents CLJS devtools to work under :advanced optimizations. Some ClojureScript type hints are not preserved in advanced builds and that is why CLJS DevTools cannot recognize objects belonging to CLJS land.

Normally you should not include debug/diagnostics code in your production builds anyways.

Since version 0.8.3, cljs-devtools detects advanced build situation and refuse to install. If you want to disable this check set :disable-advanced-mode-check to true prior installing.

How do I elide the library in my :advanced builds?

Please read installation.md#advanced-builds.

Does this work in other browsers than Chrome?

No, AFAIK.