Philosophy of Biff
biffweb.com
biffweb.com
https://en.wikipedia.org/wiki/Biff_(Unix)
But this is obviously not that...
at least it's short and easy to type
Luminus, for instance, is able to handle project creation, development, and deployment all within Leiningen (a build tool) itself. All you need to get started is to install Leiningen (a single command to install on any popular package manager) then run
lein new luminus my-app
cd my-app
lein run
I visited the "Getting Started" section of Biff and I am immediately met with "install Babashka then run this random script off the internet". It doesn't help that they already use tons of Clojure-specific terminology like "jacking in" and assume you are using CIDER (hence Emacs). While I use Emacs and Clojure, this documentation reads like it's intended for Emacs users with years of experience in Clojure. In my opinion, this contradicts the design philosophy of "what would be helpful for ... those who are relatively new to Clojure."
I'll admit the plugin architecture of Biff is really nice, and I welcome decisions like using HTMX. However, there is also questionable design decisions like choosing XTDB on behalf of the user as opposed to something like SQLite or PostgreSQL, which would drastically lower the mental overhead for Clojure newcomers and even Clojure devs themselves. Although this is anecdotal evidence, most people I talked with at Clojure/conj 2023 use PostgreSQL and aren't too familiar with Datomic or even XTDB. (The fact XTDB 2.0 emphasizes SQL support says enough about the situation, I think). Out of dozens of people I talked with, I met exactly one person who actually uses Datomic in production. Nobody I met used XTDB.
I could go on, but I hope I've gotten my point across about three things;
1. as someone with several years of professional experience using Clojure, there is seemingly lots of disjoint, moving parts involved
2. like existing Clojure "frameworks", it still fails to feel like a Rails / Django / Laravel and feels more like "here is a project template with a bunch of decisions baked in for you". Some decisions are awesome (HTMX instead of a complicated CLJS frontend) and others are questionable (XTDB and Babashka instead of simply using PostgreSQL and Bash scripts).
3. the documentation feels like it's written for experienced Clojure devs, not a general audience
The main reason I switched from Bash to Babashka for the project tasks (`bb dev`, `bb deploy` etc) is that it allows me to put the task implementations in a library and have Biff projects depend on it, as opposed to copying all the task implementations into new projects (which is what previously happened). This way people can upgrade the tasks by bumping the lib dependency. Some of the tasks also have somewhat complex logic and IMO benefit from being written in Clojure/Babashka.
The only bash script is `server-setup.sh`. I suppose I could rewrite that in Babashka for the sake of consistency, but it doesn't really seem like that big of a deal to me (?).
In response to "install a variety of tools without clear purpose" -- isn't it just one tool, Babashka? I believe that puts it on par with Luminus :).
Agreed that the docs could be better written for those new to Clojure. To really do a good job of this I'd want to do some actual user testing with people as they try out Biff for the first time. Main constraint here is just time. I'm always happy to get specific pieces of feedback and try to act on those (perhaps I could make the jacking-in section less prominent). I actually would love to make a course/series of guides for complete Clojure newbies, but until someone hires me full-time to work on Biff I think I'll have to rely on others to write the beginner resources.
In response to your three points:
1. There's a lot of stuff that goes into a web app :). It's also not clear to me that switching from Babashka to Lein templates + Bash scripts would improve this situation (if anything that sounds like it would involve more disjoint parts).
2. To act on this I'd need more specifics about how things are different in Rails / Django / Laravel.
3. Addressed above. There is a step-by-step tutorial at least (https://biffweb.com/docs/tutorial/build-a-chat-app/).
A common pattern in tools.deps based projects, for instance, is to use Babashka as a sort of Makefile replacement and make it act as a thin wrapper around tools.build. I don't like this because it's yet another tool to understand and install on top of tools.build, whereas sticking with the Clojure CLI itself means all you need is...the Clojure binary on your PATH. I am fine with projects that use a Makefile instead of Babashka since pretty much every Mac and Linux machine has `make` installed and it is widely used outside of Clojure, too. So it is not too foreign of a concept when getting people started with Clojure.
As for your response with (2), here is an example with Rails:
The example app doesn't start with a chat or anything complicated really. Instead, `rails new myapp` gives you a well-organized folder structure, one command to start your web app, and a simple landing page making use of the MVC patterns. The landing page immediately directs you to official Rails documentation for learning what everything in your myapp folder is. When it comes to time to extend a Rails application (add a new model, add a new view, add a new route, etc.), there is pretty much always a "canonical" choice of action. In the case of Biff, there is technically many ways to go about doing each of these things, partly due to the plugin architecture, and partly due to the fact that Biff is built out of independent software and making them synergize for a web app. Does this help?
The description of Rails is helpful--thanks.
I use Emacs but I discovered to my surprise that the creator of Biff does not. I don't see a lot of Emacs specific stuff in the documentation.
I recommend the tutorial project (eelchat). Otherwise, they are really helpful in Slack... someone usually answers any issue in a couple of hours or much less.
What's most important is that Biff brought me was a working front-end out of the box that I could start tweaking right away. When I used Luminus I had more steps and they were really hard to figure out as a beginner. However, shout out for Luminus... it was my go-to before Biff and I have huge gratitude.
I didn't know about htmx and it has been a game changer. This is probably my favorite feature.
This was the first time I was able to fluidly get something going, tweak the backend and UI, and deploy. Other approaches had some but not all of those.
The deployment situation is a dream. It was incredible to have my site up with a few steps. For a less skilled developer like me this was totally awesome. Biff has a continous code-push/deploy feature that is incredible.
Sorry if this seems like a fanboy post. It's probably because for Biff I am one. My feeling is that for Clojure to grow userwise there need to be a lot more projects like this one.
I don't find this accurate. Biff is not dependent on any bash scripts at all. There is one(1) bash script, server-setup.sh, which you can run to configure a server. It's a 112loc script which installs dependencies, configures nginx, sets up a systemd service and git deploys. I don't call this a dependency since it's literally the exact same thing as running these commands by yourself. Once you've ran it, neither your server or development env depends on it in any way. It's just a handy way to set up a server.
As for the bb scripts, yes you need to install babashka to run them. I don't see how this is different from having to install lein to run luminus apps? clojure-cli is the defacto standard tool these days after all.. babashka's deps are declarativively defined in bb.edn, i don't find it accurate to describe as "moving pieces" .
> like existing Clojure "frameworks", it still fails to feel like a Rails / Django / Laravel and feels more like "here is a project template with a bunch of decisions baked in for you".
"Strong defaults, weakly held."