Stu

Displays the output of CLJS compilation in an interactive UI. The artifact produced is static so it can be viewed without a server and even emailed as an attachment.

Try it out using this sample. This page was generated by Stu against a few iterations of Stu's viz app.

Observations you can see in the Stu sample:

• cljs.pprint was used in Stu in early versions. After seeing how much code it generated, it was removed from all app code. compare 0.5 and 0.7
• Stu was code-split, becoming two modules. Code split apps show one treemap for each module. compare 0.8 and 0.9
• Using a minified version of d3 has no effect on overall artifact size. compare 0.9 and 1.0

Stu is invoked using the command line (or the REPL), intended to be run in a CI server.

Initially supports Shadow CLJS but can support any compilation source.

Usage

Prerequisite

Stu works by scanning a directory for bundle-info.edn files and transforming them. These files are called snapshots and can be generated by Shadow CLJS.

Stu assumes you have already generated one or more snapshots. These are typically in the .shadow-cljs/release-snapshots/ directory. To generate snapshot(s) using Shadow CLJS you invoke:

(shadow/release-snapshot :app {:tag "0.8"}) with your own tag or...

(shadow/release-snapshot :app {}) to generate a latest snapshot.

In future this manual step will be automated into another CLI by some genius developer whose help will be greatly appreciated.

Illumination (i.e. static file generation)

CLI Options

-h or --help shows this message
-d or --dir <directory> is the directory where Shadow snapshots are read from. defaults to .shadow-cljs/release-snapshots/app
-f or --file <file name> is the name of the file to be generated. defaults to target/stu.html

Leiningen

Add the Stu dependency [stu "0.1.0"] to your project.clj.

Then generate the html report, use the illuminate CLI.

lein run -m stu.illuminate invokes the command line with default args.

Deps

Include a dependency on this project in your deps.edn. You will probably wish to put it in a dev alias.

{:aliases {:dev {:extra-deps {github-stevebuik/Stu {:git/url "https://github.com/stevebuik/Stu.git"
                                                    :sha     "1a06621813209a17848ed43f9fd28e5471ddf36f"}}}}}

Then generate the html report, use the illuminate CLI.

clj -Adev -m stu.illuminate invokes the command line with default args.

Other

Any other way of invoking stu.illuminate/-main is valid e.g. the Shadow CLJS clj-run feature.

The CLI will print the location of the generated file.

Questions Stu can answer

Stu was built to answer questions about your javascript artifacts. All features exist to answer these questions:

All enhancement issues in this project should be written in terms of Question/Answer to ensure valuable features are added.

Design

Stu is a reagent component which is passed protocol impl to provide data. That data is checked using a spec to ensure it's correct.

This provides two benefits:

1. The component can be run in devcards using different/simple impls of the protocol to display different behaviours.
2. The spec allows any other CLJS compiler capable of generating the data to also use Stu. e.g.
   • cljs.main
   • cljs-build

Stu uses react faux dom to simplify the use of D3 interop. Instead of worrying about how to handle D3s join mutations vs Reacts dom diff based mutations, this allows the d3 interop code to be copied directly from javascript examples, including mutations. This makes the d3 charts much simpler to write.

Using Stu on a large app with many snapshots could generate a large dataset. The generated data is appended to the static output file using a JSON map with the treemap data encoded using transit. This allows the GlobalsSource to load only one dataset at a time which mimimises memory consumption. The use of transit reduces the data size due to it's keyword caching.

In practice, these space savings are small compared to the size of the Stu app javascript but that may improve in future as npm deps can be processed by Google Closure advanced compilation.

Naval Gazing

Since Stu is a CLJS app, it can be used on itself. This is great because it provides a good example but can also be used to test and develop itself. Examples include:

1. The sample app above
2. The development app running with recorded data
3. The (meager) tests can use a "latest" snapshot to ensure a valid transformation

Development

• start a lein REPL and (start-dev!)
• navigate your browser to http://localhost:8280/devcards.html and explore.
• notice the Run Viz Application link which runs the full App in dev mode, with hot code-loading, same as devcards

Roadmap

All new features are logged as issues and tagged as enhancements.

Any help would be greatly appreciated.

Who is Stu?

He was an internet pioneeer who used technology to bring light to the shadows

License

Copyright © 2018 Steve Buikhuizen

Distributed under the Eclipse Public License either version 1.0 or (at your option) any later version.