One objective of my Clojurists Together funding is creating a proper template solution for shadow-cljs to easily and quickly create baseline project scaffolds without too much work.
While there are already a few community templates available they all require lein (or clojure) which the typical JS developer won’t have installed and I don’t want to force them to install either. So one of the base requirements is that it doesn’t rely on anything besides node+npm and java installed.
So my current plan is this:
create a npm package that can be invoked directly and does the basic project generation
generate some demo content + configuration on demand
Part #1 I have more or less figured out and you can try it today by just running
This will create a foo-bar directory and create the package.json + shadow-cljs.edn configs. It will also install the latest shadow-cljs version into the project.
Part #2 is much more tricky. My role model currently is the vue cli which does all this exceptionally well. Only problem is that the vue cli is for vue the framework. I don’t want to create something that is tied to a specific framework and making something more generic quickly gets way more complex too. Replicating what the usual lein-templates do is not that hard but I’m curious about other options. One other really cool onboarding experience I saw was metabase.
Basically at this point I’m looking for ideas around project templates.
What are your favorite project templates?
What are the best setup processes you have seen to date?
I’ve always enjoyed create-react-app. It may be a lot, but when starting projects in the React world, in my experience everyone uses it and appreciates it.
I have used in the past a classic copy and fill the holes approach with mustache the templating language. Tht is a simple JS lib so you could just use ClojureScript for everything.
But I’m not so much looking for info on how to build templates. That part is easy. I’m looking for inspiration on what template to build.
create-react-app is another good example but its also exactly only for building react web apps. I encourage anyone to try the vue cli (especially vue ui) to get an idea about what I’m after. It might be overkill to build this kind of UI but who knows.
From a node point of view an example of all the node targets + azure target would be cool (can contribute that one) especially to see how to do testing. Or mixed JS-Cljs examples.
One under-appreciated aspect of create-react-app is that it upgradable, unlike standard templates. All you have to do is update the react-scripts version in package.json (instead of updating 10 different packages and their configuration files). The typical templating solutions you’ll find in the cljs ecosystem copy a bunch of stuff to your disk, and then you never interact with the template again. There isn’t a lot of user pressure to keep the template up to date because users go away after that first interaction.
I’m not even sure if it is technically possible to get the same effect with cljs, as so much of create-react-app is done with webpack & babel, but it is certainly something to think about.
Agreed that most templates generate way too much boilerplate code that gets out of sync easily.
Problem however with create-react-app or react-scripts is that its not very customizable. You do it their way or eject which leaves you with a whole mess of things that you can’t upgrade anymore. Overall something like create-react-app is way out of scope for shadow-cljs since I don’t want something framework specific.
There could totally be a create-reagent-app that could use shadow-cljs but thats not what I’m going to build since I’m not a reagent user myself and wouldn’t know where to begin.
I guess the question then (what I’m still unclear on, anyway) is: what is the scope?
Is the idea that it would just create a simple shadow-cljs.edn + core.cljs that would implement a simple “hello world”?
Is the idea that it would have additional plugins/generators, similar to how lein allows you to add additional parameters to a template like +reagent +reframe +macchiato?
It sounds like we’re talking a lot about how when it’s not clear what the goal is yet. Simple demo content, or a full-fledged plugin / feature generation service a la vue-cli?
Well the scope is that I want something usable in 2.5 months
I’m unsure on how extensible this should be. I definitely cannot maintain a template for every single framework myself. I could maybe copy some popular lein templates and translate them to shadow-cljs configs but thats not exactly ideal. I’m also quite opinionated on how a project should be structured which may not suit everyone.
I really like the vue-cli stuff though. yo looks nice too. I wonder however how much value there really is in such things for the Clojure world since we usually write much much less boilerplate code than typical OOP-ish frameworks/languages.
I haven’t used a single template beyond basic lein new project since starting with Clojure and there is definitely value in knowing how your project is structured by building it yourself. There is also value in starting out with a single namespace and figuring out why you split things into multiple namespaces. Lots of that is lost when you just start out with a pre-generated set of namespaces. Which then begs the question of who the templates should target: the expert users that already know all the details or “beginners” that just want to get started doing something?
I really wonder how many people actually understand their generated project.clj (or deps.edn). I have trouble grasping some of the stuff generated by lein templates.
I may drop the template idea entirely and instead focus on a “config wizard” style UI that lets you edit your build config by clicking through some basic options. Configs in shadow-cljs are already reduced to the bare minimum but a UI could still help by providing smart auto-complete or just inline documentation for each option.
Still just interested in how other people view/use templates (and which).
I like this last idea. Maybe REPL based first, just to grasp the post of it.
It would basically be a way to build a user-friendly dsl on top of the configuration files (both deps/project.clj and shadow) and receive useful feed back in case of error or REPL restarts (say you add a dep in the REPL, dynamic load is not yet there, you receive “please restart the REPL for this to take effect”).
This could improve usability a lot. It can be further extended to a UI definitely.
EDIT: if thought of a separate library it could even be used only with lein or only with deps actually. It would be super cool. Kind of like rebel but for configurations. Nice.
lein new re-frame upvote +garden +10x +cider +test +handler +routes
and it was amazing to get up with a templated and wired up re-frame app. There were samples to follow along and get the basics working and then i knew where to look to modify these parts. It was quite nice.
I don’t use project templates like Vue CLI or react-create-app. Instead, I’m maintaining myself two repos. When I need to start a new project, I just clone them, regenerate .git/ folder, modify configs, and new project is ready.
create-react-app is another good example but its also exactly only for building react web apps. I encourage anyone to try the vue cli (especially vue ui ) to get an idea about what I’m after. It might be overkill to build this kind of UI but who knows.
IMO one should avoid templates. Templates break versioning since a change in the template generator lib / cli usually doesn’t provide a git-like upgrade path to all projects that have been made with it. create-react-app has a solution to this, packaging default files into its source and allowing developers to run commands to copy them incrementally into their own apps as they need to be changed. The fewer files get generated, the less there is to maintain.
