Documentation?! about shadow-cljs

[thheller]

I tried capturing the essence of it in the README
https://github.com/thheller/shadow-cljs#rationale

I'm not in a position to make comparisons with other tools since I have never actually used any of them other than a few test runs. I stopped using standard CLJS tools a few weeks after emezeske/lein-cljsbuild#173. I'm sorry I exposed everyone to a bad version multiple :source-paths.

shadow-build has been my only CLJS tooling since then. I merged all of it into shadow-cljs a few weeks ago to add the configuration layer since the API of shadow-build was a bit too low level.

I also focused a lot more on the internals and the user-facing stuff like the pretty warnings is all new. I cared much more about correct/optimal builds that don't need lein clean constantly.

Since I don't actually know what figwheel does I don't want to make too many claims about anything.

[pedrorgirardi]

How about starting with why shadow-cljs exist, which problems it tries to solve that other tools do not? And for those who already have their project setup with tools like leiningen and figwheel, what shadow-cljs has to offer?

More in-depth documentation on HOW TO do things are important too, no doubt about that, but I think it makes sense to start with a clear rationale for why you are investing your time on this project and how it can help other developers.

I believe you did see some problems with the current state of tooling for ClojureScript and decided to do something about it, so why not share more about that and how you are tackling some of the problems? I think developers could relate to that, I personally do.

[thheller]

I don't have an actual job title, independent Consultant maybe fits best. I build (and maintain) software projects for small companies that trust me enough to let me choose the tech I want to use.

shadow-cljs happened because I saw many things where I thought "it would be cool if ..." while working with CLJS. It made it easier for me to do experiments with CLJS itself and most of the features I then used for work.

[thheller]

nREPL is horrible but oh well. ;)

I have no real thoughts on editors. Not a big fan of the fancy "instaREPL" from Lighttable (or cider these days). Most tools try to do too much and get in the way of the simple things I want to do. I have used VIM for many years and only switched to emacs+evil because of paredit. Cursive nowadays since I had about 5 years experience with IntelliJ previously and never quite "clicked" with emacs.

[tiye]

I would suggest a quick start for a counter app with dev and prod environments, with a minimal example for cloning and playing with, which consist the "Guide" part.

update: I would definitely show off the example to my friends here in China that ClojureScript is much easier to pick up today.

[thheller]

FWIW this rather short discussion made it very clear to me that David has a completely different definition/vision of "tooling" than I do. My goals were/are different so this is what you get with shadow-cljs. I'm not saying that it is any better than the official API just a different take on it.

[tiye]

@thheller that made me curious about what your work is like, and how it led you to a solution like shadow-cljs?

[pedrorgirardi]

Thank you @thheller !

I have always usedleiningen and figwheel, maybe I could help with that. I should try to add shadow-cljs to my project and see how it works out. The only missing thing I suppose it would be nREPL support.

[thheller]

I'd love to do some before/after comparison but that would need open-source projects that are actually complex enough to notice the differences (ie. multiple source paths, multiple builds). Simple projects won't have many differences.

figwheel still does some things that shadow-cljs doesn't do "officially" (eg. css, http file server). I'll probably add a simple file server as well but I'm not sure how to tackle the css. I have a sketchy solution in my work project but I'm not too happy with it (also requires sassc).

nREPL is scary still. A simple connector is easy but middleware scares me. Do tools expect certain middleware or would it work if there are just the basics?

[pedrorgirardi]

I don't know if a before/later in my case will be that interesting, but I can try that. Since I had only "exposure" to lein and figwheel I would try to write something more towards programmers that are familiar with both lein and figwheel.

@thheller don't you think that the work you are doing with shadow-cljs could be used to create a very nice integration with VSCode for example? What would it be like to try to implement a VSCode LSP extension, let's say vscode-shadow-cljs? This doesn't have much to do with nREPL, but I've been thinking a bit about what would be like to create a very nice experience for working with ClojureScript and I would be keen to help with that. I don't know much but I think you already did the hard part with shadow-cljs. 😄

*Sorry for talking this kind of thing here, since you already have created an issue for LSP.

[thheller]

I actually thought about writing a VSCode plugin myself (maybe with commercial support option).

The LSP plugin is very easy since vscode-languageclient just works out of the box. Some of the old server code is here: https://github.com/thheller/shadow-cljs/blob/master/src/main/shadow/lang/protocol/text_document.clj

It only supported one feature though: on file open/save it would use those events from LSP and re-compile the file and report any warnings back to the editor. About 50 LoC for the Client gets you:

The proof-of-concept felt valid enough to try and do more but I got frustrated with VSCode pretty quickly. It does everything they want you to do well but everything else is basically forbidden. You can't add custom UI elements (eg. no REPL window, must use editor). At the end of the day VSCode really isn't setup for a lisp-y REPL workflow. Paredit was pretty broken as well, Parinfer works great though. VSCode didn't even know about .cljc until recently.

There are LSP clients for emacs and neovim as well so writing the LSP server is still on my list but for now it is more important to integrate with the "usual" CLJ/CLJS tools and not rewriting everything from scratch. FWIW if you squint a little you can treat nREPL as just another protocol which uses bencode over JSON-RPC. It has similar building blocks, just take out the REPL related things. Tools just need to stop sending random code to eval and send actual commands instead.

That being said the nREPL thing is almost done. No piggieback madness since that basically drove me crazy the last time. I did (js/alert "foo") over nREPL yesterday. I'll probably finish and release that today. It would be so much easier if tools used "cljs/eval" instead of "eval" for CLJS but oh well ... maybe I can convince them to do so at some point. shadow-cljs is still basically unknown so tool authors aren't very interested in my crazy ideas (understandably so).

[pedrorgirardi]

Very nice! I appreciate your comments, you always give some context and I can usually learn something about CLJS build/tools.

Yeah, nREPL support will be neat, no reason to not use shadow-cljs then 🎉

I see what you mean about VSCode limitations, in that case, which editor you think would be more suitable to build a ClojureScript IDE upon? Do you have any thoughts about Lighttable?

[pedrorgirardi]

Same here.. :) I'm used to IntelliJ because of my previous work experience with Java.

Well, alright then 👍

[thheller]

https://shadow-cljs.github.io/docs/UsersGuide.html

Using https://github.com/shadow-cljs/shadow-cljs.github.io to track all documentation related issues.