For the impatient: just show the tutorial, how to compile and run(with shadow-cljs)?
There was a poll on Twitter I tried to ask people why they don’t like ClojureScript,
Many people responded with “Not known how to build it”. By the word “build”, I mean mostly “compiling”. Not sure if someone takes it like “structuring” or something.
The “compiling” problem is much easier today I would explain later. For the “structuring” part, I don’t think I can really answer it. To create a browser project you will need a UI library like Reagent, Rum, Om, or even use React(with hooks) directly.(I made a virtual DOM library too if you want to try. To create a Node.js projects, you would need to call Node.js APIs and import npm modules. Not much I can tell.
I’m going to talk about the “compiling” part, trying to guide you through the first steps with my experiences. Might be a bit inaccurate, but supposed to be helpful.
The core library of compiling ClojureScript is
cljs.main provided by the ClojureScript compiler. You may see it in the official guide, telling you how to compile project, how to turn on optimizations, how to start REPL in Node.js code, etc.
ClojureScript - Quick Start
However it’s not quite enough if you want to build a larger project. You may known Webpack already, so you think there’s hot module replacement as you save files, you may need to grab packages from npm and put in your projects.
cljs.main does not help with such needs. There are a few projects to help which are listed in ClojureScript beginner page:
Meanwhile shadow-cljs has a configuration file written in EDN format. That means you can turn on hot code swapping and optimizations. It also handles externs for you. If you haven’t used Google Closure Compiler and not familiar with externs, it might be freaky. shadow-cljs can handle that.
There was lein-figwheel before figwheel-main. “Lein” refers to “Leiningen”, which is a popular build tool on JVM Clojure side. Lein has problems like starting-up very slow, so fighwheel-main come as result since we have Clojure CLI now.
Figwheel was created long before shadow-cljs released in 2017. It has many nice features, especially for how code swapping. Many of the features just inspired shadow-cljs.
I’m not that familiar with figwheel-main after switching to shadow-cljs. But you can take a look at Figwheel’s Tutorial to know how it works.
It’s like a very early build tool which wraps APIs from ClojureScript compiler. I was using it when I was first learning ClojureScript. To be honest, I don’t like it. But writing Lein configurations is an easier way in the old days.
Boot-cljs and Boot-reload
Boot another build tool, like Lein, but composable, which makes it a little more powerful than Lein and people can write code to define how the workflow is like. The features are similar, just more flexible. boot-reload is the part to perform hot code swapping paired with boot-cljs.
The bad part is boot-cljs, as well as lein-cljsbuild, are simpler wrappers on ClojureScript APIs. When you want to add long term caching like Webpack, you have to implement your own. shadow-cljs actually can generate MD5 hash appending to the filename, so I switched.
Other things to know
Clojure has macros, which mean in compiling ClojureScript, there’s a change to define macros in
Might be more you would need to know to compile ClojureScript, but I have to stop here. Reply if you got ideas.
If you want a simple suggestion, I would just recommend shadow-cljs. It’s much like Webpack, if you are familiar with Webpack, you will file shadow-cljs has quite some familiar parts. Otherwise figwheel is also cool.