What is the difference between figwheel-main and figwheel-sidecar


I’m pretty new to Clojure and ClojureScript, while exploring ClojureScript I discovered figwheel an excellent tool in my novice opinion. When I create a project with leiningen I have the option to create two different templates as follow:

lein new figwheel hello-world

lein new figwheel-main hello-world

this creates two different project.clj one with sidecar and the other with main.

Also as I’m using Nvim I need to piggyback to either main or sidecar repl.

At first look they seem to do the same thing, thus my questions what is the difference between the two?


1 Like

I think figwheel-main is a rewrite of the original figwheel. Not sure why both projects exist, but it’s probably because it wasn’t possible to migrate the old API without introducing breaking changes (breaking changes are a big nono in Clojure land). Just use figwheel-main - or perhaps consider shadow-cljs which I switched to myself at the beginning of the year.

What are the big differences between shadowcljs and figwheel? (that question should still being the domain of this thread). I’ve used shadowcljs lightly, and am by no means a power-user of figwheel, but they seemed about the same to me.

Me too. So far the only difference I’ve found is figwheel being a leningen plugin vs. shadow-cljs being an npm package and a newer project… but nothing about how to choose one over the other

Shadowcljs is a build tool for ClojureScript. Figwheel-main is a way to add REPL reloading to the browser.

Shadowcljs happens to have its own browser reload mechanisms built in, so no need for anything else like Figwheel-main.

The thing is, for any browser reload tool to work, it needs to have a way to rebuild, because you can only reload JavaScript inside the browser, not ClojureScript.

So change some .cljs file, or send something to the REPL, and you need the reloadable tool to call into the ClojureScript compiler to compile the new code back to JS and then swap the page’s JS with the new JS.

This means that any reloadable tool must know how to re-compile your ClojureScript. Re-compiling ClojureScript means knowing about all the dependencies needed for the code being compiled, etc.

So you can see how it becomes non-trivial to separate reloadable tool from build tool.

That’s why a lot of the Figwheel-main config itself is defining build like things.

Now Figwheel-main has to work with lein or tools.deps and standard ClojureScript compiler build configs and tool chains. That can be a disadvantage in that it’s just harder to do what it wants, it has to play nice with all these things.

Shadowcljs is a ClojureScript build tool first and foremost. It knows how to compile and bundle ClojureScript code. Its specialty is letting you use NPM dependencies with ease. It has a lot of auto-magic and useful extras for working with NPM deps. In that regard, it is better than standard ClojureScript with lein or tools.deps. Though newer ClojureScript with webpack support has gotten a lot better at this as well.

Now Shadowcljs being a build tool, also added reloadable features to itself. Since it is in charge of the whole build chain, it’s much easier for it to add browser reloadable functionality.

Ok, so major difference:


  • A full ClojureScript build tool specialized in working with NPM dependencies.
  • Also includes a browser reloadable feature built in that is perfectly integrated with all its other build features.


  • Not a build tool, only a library that lets you add browser reloadable functionality to existing build tools like lein + standard ClojureScript compiler.
  • Need to work harder to find ways to fit in with the build tools it supports.


  • I think this was the old figwheel, which only worked with lein. Figwheel-main was a rewrite to try and decouple Figwheel from lein so it could be used with tools.deps and boot as well.

Hello all,

Thanks a lot for your replies, things are now clear, I will keep using Figwheel-main for now, but I will definitely take a look to shadowcljs.


This topic was automatically closed 182 days after the last reply. New replies are no longer allowed.