Releases: binaryage/cljs-devtools
0.8.3
Configurability via environmental variables
In this release I started using env-config library to allow flexible configuration overrides via environmental variables. Read more about configuration via env variables.
Also this new version will refuse to install into :advancedbuilds. Read more here.
Notable commits:
4e3cf26 print internal errors as collapsed group
1619c66 refuse to install under advanced builds
87571dd :tooling-config > :devtools/config works also with manual installation
92fd2e1 take advantage of binaryage/env-config for configuration via env vars
All new work: v0.8.2...v0.8.3
0.8.2
0.8.1
0.8.0
deftypes and more!
My main goal of this release was to add support for ClojureScript types. It turned out that rendering type fields, protocols and their details is somewhat complex. So I decided to rewrite rendering subsystem to use hiccup-like templates instead of rendering raw JSON-ML templates by hand. And when I was at it, I decided to do other major changes and refactoring. Please refer to upgrading section below and report any unexpected breaking issues.
deftypes, defrecords and protocols
Please consider this code:
In the console you can see that logged items have azure wrapping with white type name on the right.
The first log statement logs just the MyType type (a javascript constructor function). We can drill down and see its details in the expanded body:
You can see basis of three fields p1, p2 and p3, namespace in which the type was defined and have possibility to drill down to underlying javascript object.
Let's inspect the second logged value, it was an instance of MyType:
The header displays abbreviated field values, more details can be seen in expanded body. For example protocols are presented there as well. We can inspect some. Let's look at MyProtocol:
Neat! It gives us a list of defined methods, their arities and a possibility to drill down into individual anonymous functions.
Let's look at the third logged value, which was an instance of MyRecord:
Because records implement ISequable protocol, we get offered an extra disclosure triangle in front of the type to inspect sequable representation. Also note that yellow part in header. That part was printed because records implement IPrintWithWriter.
We can still drill down into type details (records are "rich" types with bunch of implemented protocols):
As you can see, our record implements 14 protocols. Note that yellow-ish protocols are implemented using fast-path dispatch.
And as the last example, let's look at MyMinimalType instance which has no fields:
The empty set symbol should hint at no fields. We can drill down into raw javascript representation to inspect guts of the underlying javascript object. Please note the white background when we get back in javascript lands.
Experimental :async feature
I'm a heavy user of core.async, this new :async feature allows display of long chains of async stack traces in Chrome DevTools Sources Panel.
Read more details in the FAQ.
Upgrading
If you have installed cljs-devtools without custom configuration you have nothing to do. Easy!
Have you used :preloads as described in the previous release? If you did some config overrides, please change :tooling-config key to :external-config (:external-config still works, but it will be deprecated in the future). This change is for Figwheel compatibility.
Full documentation for using preloads has been add to the installation docs.
Also I decided to change keyword names for individual features:
:custom-formatters -> :formatters
:sanity-hints -> :hints
Old keys still work, but will be deprecated in the future.
If you have used devtools.format.IDevtoolsFormat protocol for writing your own custom rendering, please use devtools.protocols.IFormat instead.
In case you used some functions from devtools.format namespace while implementing custom rendering, please look at the deprecated versions of those functions and consider using new hiccup-like APIs from markup.cljs. After composing markup template data, you want to use render-markup function to render final JSON-ML. Look for inspiration in this commit.
Notable commits:
86dbbbb add experimental :async feature
ccb9f8d wrap IPrintWithWriter products as references if needed (#21)
8dbb865 use devtools.protocols.IFormat instead of IDevtoolsFormat
e5e963e rename template to make-template
2b09ecd rename surrogate to make-surrogate
e230645 treat js objects with selected cljs protocols as coming from cljs land
55b4d0b read configuration from :external-config, deprecate :tooling-config
952d6c6 initial types/instances support
5583bf8 move defaults-pref to devtools.defaults
01908f4 rename custom-formatters to formatters
3820bfe rename sanity-hints to hints
ca5296f rename prefs.clj to defaults.clj
b630d01 provide complete list of :well-known-types
2598c2c implement proper-demunge which is js-reserved? aware
b7b0ce2 introduce proper-arg-demunge, which is aware of leading underscore
82d2055 dance around issue #22
95b9578 introduce :min-expandable-sequable-count-for-well-known-types
3a92c64 do not offer expanding of empty sequables
806dd24 allow control of rendering atomic templates via prefs
62e412f reimplement some old apis in devtools.format and mark them as deprecated
All new work: v0.7.2...v0.8.0
0.7.2
Easier installation via preloads
ClojureScript newly supports :preloads compiler option which allows you to require namespaces prior your :main namespace. Now you can use this feature to add cljs-devtools support to your project without modification of your code. You simply add devtools.preload into the :preloads list.
Here is an example how cljs-devtools-sample was modified to use this new feature:
binaryage/cljs-devtools-sample@4cb1f56
Configuration
The whole point of preloads is to allow adding tools without a need to modify your project source code.
Ok, but how to specify a custom tool configuration if needed?
It is easy. You may specify additional configuration options under your compiler options.
For example cljs-devtools expects its custom config under :tooling-config > :devtools/config.
For example:
:tooling-config {
:devtools/config {
:features-to-install [:sanity-hints]
:fn-symbol "F"
:print-config-overrides true}}This overrides default :features-to-install, sets custom :fn-symbol and instructs cljs-devtools to print overridden config values during installation.
Here is a full example in a working project, here is the list of available configuration keys.
Notable commits:
16d52cf introduce new prefs
bd16392 instruct install! to use :features-to-install pref as defaults
e0fcb9b print-config-overrides-if-requested! during install
26736b0 introduce devtools.preload namespace
All new work: v0.7.1...v0.7.2
0.7.1
A maintenance release
When our rendering code throws for some reason, you should see related exception message in the console with a proper stack trace. I have also updated some styles.
Also there is a new helper function available in the toolbox: devtools.toolbox/force-format
Notable commits:
58ac191 wrap api calls with our own exception guard
62dddce make custom formatters more robust in face of "weird" inputs
081593c introduce toolbox/force-format (close #17)
49b9023 introduce more tweakable prefs for toolbox/envelope
6648487 implement present-function-name and related functionality
3a9eaeb improve warning about custom formatters not rendering (close #18)
All new work: v0.7.0...v0.7.1
0.7.0
Friendly rendering of functions
Major improvement of this release is custom formatting for ClojureScript functions.
Custom formatters for functions
A picture is worth thousand words:
Implemented features in this release:
- formatting is applied to functions from ClojureScript only
- distinction between named functions and unnamed (lambda) functions
- display of namespace if available
- support for reverting munged names
- support for multiple arities
- support for renaming macro-generated parameters with subscript indices
- support for IFn protocols
- access to native function object after expanding
In case of troubles you can disable custom formatting of functions by settings this pref prior installation:
(devtools.core/set-pref! :disable-cljs-fn-formatting true)Detect if custom formatters are enabled
Sometimes people are too busy with their lives that they forget to enable custom formatters in their Chrome DevTools and then wonder what went wrong.
Newly we can detect this uncomfortable situation and confront the user with this warning (after opening the console):
You can disable this warning by setting this pref prior installation:
(devtools.core/set-pref! :dont-detect-custom-formatters true)Feature groups
Newly you can use a keyword for specifying what features to install. Currently we support :all and :default feature groups.
So instead of listing all features by hand, you can substitute it with :all:
(devtools.core/install! :all)
; equivalent to (devtools.core/install! [:custom-formatters :sanity-hints])(devtools.core/install!)
; equivalent to (devtools.core/install! :default)Notable commits:
37dacef reimplement core install-related api same way as in dirac runtime
20c9d86 introduce :bypass-availability-checks tweak (close #15)
f15603a detect if custom-formatters are active and warn if not (close #16)
c406b8a implement formatting of cljs functions
b0d0098 allow :disable-cljs-fn-formatting
All new work: v0.6.1...v0.7.0
0.6.1
0.6.0
Dirac support removed
Dirac runtime support was moved into the Dirac project itself. Since this release, the Dirac DevTools is not dependent on CLJS DevTools anymore. But both tools still remain complementary (Dirac users are expected to use CLJS DevTools as well).
Also with 0.6 release I have changed the api for enabling/disabling features. Newly you just pass a list of desired features into the devtools/install! call. See the installation instructions. The install! method also newly reports CLJS DevTools version being installed into console.
Additionally I have introduced devtools.toolbox namespace. There is a new helper method envelope for logging objects with "busy" default presentation. You can prevent their default console presentation and print your own header instead. Object details will be expanded upon clicking on its disclosure triangle.