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.
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/<app name> 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.
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.
Stu was built to answer questions about your javascript artifacts. All features exist to answer these questions:
| Question | Feature |
|---|---|
| How big are my artifacts and how have they grown? | The bar chart |
| How big are they when gzipped? | The "Uncompressed" toggle |
| What are the largest parts of my javascript artifact? | The treemap |
| How big are my artifacts when code split? | Multiple treemaps |
| How much does Google Closure reduce the size of my artifacts | The "Compiled" toggle |
| How much does Google Closure affect npm deps? | The "Compiled" toggle |
| Is using minified npm deps reducing my artifact size? | The treemap |
| How has my artifact grown over the last 10 weeks? | TODO The snapshot generator |
| How did that code end up in my artifact? | TODO path data in tooltip |
| Is there any code in my artifact that should not be there? | TODO CLI checks for disallowed code |
| Your question here? | TODO |
All enhancement issues in this project should be written in terms of Question/Answer to ensure valuable features are added.
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:
- The component can be run in devcards using different/simple impls of the protocol to display different behaviours.
- 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.
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:
- The sample app above
- The development app running with recorded data
- The (meager) tests can use a "latest" snapshot to ensure a valid transformation
- 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
All new features are logged as issues and tagged as enhancements.
Any help would be greatly appreciated.
He was an internet pioneeer who used technology to bring light to the shadows
Copyright © 2018 Steve Buikhuizen
Distributed under the Eclipse Public License either version 1.0 or (at your option) any later version.