dev-tools 8 min read

Biff: a Clojure web framework built to be taken apart

Biff 2.0 ships a Clojure web framework as independent libraries: SQLite by default, Datastar rendering, and a graph-based data model you can swap out.

#clojure#web-framework #sqlite #self-hosted
By
Share: X in
The word Biff rendered as large white 3D letters on a dark background

TL;DR: Biff is a Clojure web framework that ships as a stack of independent libraries instead of one monolith, so you can replace the database, the rendering layer, or the auth flow without fighting the framework. Version 2.0 makes SQLite the default store, renders with Datastar, and adds biff.graph for querying your data model. It is MIT licensed with roughly 1,100 GitHub stars, and the whole stack runs from a single clj -M:run dev.

What it is

Biff is a full-stack web framework for Clojure, written by Jacob O’Bryant and released under the MIT license. The repository went live in March 2020 as version 1.x. Version 2.0 landed on September 10, 2026 and was more or less a rewrite from scratch.

The positioning is narrow on purpose. The GitHub description says “A Clojure web framework for solo developers”, and the site says Biff helps solo developers move fast by providing as much functionality as possible out of the box without becoming something you have to take apart later.

What makes 2.0 different is the packaging. Biff is not one library with a Biff.new() call. Every piece ships on its own Maven coordinate, is documented separately, and is meant to work without the rest of the framework:

LibraryWhat it handles
biff.coreSystem composition, modules, Malli validation
biff.configA light wrapper around Aero for config files
biff.fxTurns effectful functions into pure state machines
biff.graphQueryable data model, inspired by Pathom
biff.sqliteSQLite wrapper with rich column types and migrations
biff.ringRing, Reitit and Jetty wiring plus a default middleware stack
biff.datastarServer-side rendering with Datastar over SSE
biff.backgroundIn-memory job queues and scheduled tasks
biff.authenticateSign in via email, including a default form
biff.adminAdmin dashboard with usage and performance metrics
biff.run and biff.tasksA lightweight clj task runner and the default tasks
biff.xtdbA drop-in alternative to biff.sqlite

All of the library artifacts are currently published at version 2.0.5.

Why it matters

Most frameworks force a choice between batteries included and no framework at all, and the second option gets worse as the project grows, because the parts you eventually need to replace (database, auth, rendering) are the parts wired deepest into the core.

Biff’s answer is to keep the coupling shallow. In the 2.0 launch post the author describes Biff as now being “just” a collection of independent libraries rather than a single monolithic framework, which makes it much easier to swap out the various parts. Swapping SQLite for XTDB means depending on a different library, not rewriting against a different ORM.

There is a second thread worth noticing. The starter project ships agent skills for development and code review, generated by the framework’s own task runner. The framework describes itself in a form a coding agent can read, which is becoming a real expectation for tools people use with LLMs.

The author is also candid that the rewrite was partly a reaction to trying to build a Clojure web app without Biff, to find out whether web frameworks still pull their weight. His conclusion was that they absolutely do.

Getting it running

You need Java 21 or later and a Clojure install.

git clone https://github.com/jacobobryant/biff-starter my-project
cd my-project
clj -M:run dev

The first run asks you to pick a namespace for the project, then starts the app on localhost:8080. Open it and sign in with the code printed to the console. The dev task evaluates your code whenever you save a file, so there is no manual reload step.

Every task lives behind the same runner, and clj -M:run -h lists them. The production ones cover the unglamorous half of shipping a small service:

CommandWhat it does
clj -M:run devRun the app with eval-on-file-save
clj -M:run formatFormat the code with cljfmt
clj -M:run lintLint with clj-kondo
clj -M:run testRun the tests with kaocha
clj -M:run docsGenerate markdown API docs from docstrings
clj -M:run prod-setupProvision an Ubuntu server
clj -M:run deployDeploy the app to that server
clj -M:run prod-logsTail logs from the server
clj -M:run prod-restartRestart the deployed app
clj -M:run uberjarBuild an uberjar

One thing to know before you deploy anywhere: SQLite is the default store, and biff.sqlite handles backups through Litestream and migrations through sqldef, so the database story is covered out of the box.

The module pattern

Every namespace in the starter returns a module map, and modules.clj collects them into a vector. A module is a plain map with namespaced keys, which is what keeps the whole system composable.

(def modules
  [{:biff.core/init {:biff.ring/on-error #'lib.ui/on-error}}
   (biff.config/module)
   (biff.ring/module)
   (biff.datastar/module)
   (biff.fx/module)
   (biff.graph/module)
   model.global/module
   model.request/module
   model.session/module
   model.sqlite/module
   app.admin/module
   app.landing/module
   app.auth/module
   app.demo/module])

A module can contribute routes, own a stateful resource through start and stop functions, or add to the system map. That map starts empty and gets built up by init functions. The init functions receive the modules var rather than the modules value, so a module can rebuild its handler when other modules change.

Routes are declared the same way, with a defpath so the path and the handler stay together:

(def module
  {:biff.ring/routes
   ["" {:middleware [mid/wrap-redirect-signed-in]}
    [(home-path) {:get home}]]})

The starter keeps app code, shared library code, and data models in separate directories (app, lib, model) and wires them together through that module list. Nothing in the framework requires you to follow that layout.

Pure handlers with biff.fx

biff.fx is the piece that decides whether you can test your handlers. It splits an effectful function into a set of pure state functions, and the effects happen in the transitions between states. A state is a plain function of its input, so a test is an ordinary equality check with no mocking layer.

The library’s own example reads a number from a file, increments it, and writes it back:

(defmachine increment-file
  :start
  (fn [{:keys [path]}]
    {:content      [:example.fx/slurp path]
     :biff.fx/next :increment})

  :increment
  (fn [{:keys [path]} {:keys [content]}]
    (let [n     (or (some-> content parse-long) 0)
          new-n (inc n)]
      {:_              [:example.fx/spit path (str new-n)]
       :biff.fx/return new-n})))

Callers never see the difference, since the pure states stay wrapped in one effectful function. That means you can adopt it one handler at a time and drop it if the extra verbosity does not suit you.

A data model you query instead of traverse

biff.graph is a deliberately small take on Pathom, which the author used to love at work but did not want to force on people who had never heard of it. Resolvers declare an input query and an output query, and the engine works out which resolver supplies which attribute.

(defresolver user
  {:output [{:session/user [:user/id]}]}
  [{:keys [session]} _]
  (when-some [uid (:uid session)]
    {:session/user {:user/id uid}}))

The caller asks for the shape it needs and does not care whether an attribute came from a SQL table or from a derived function. biff.sqlite can also generate resolvers straight from your table definitions, so a query like the one above becomes a select rather than hand-written plumbing.

The tradeoff is honest: biff.graph has no query planning step, so it may not execute some queries as efficiently as Pathom does. It does support batch resolvers and caching. The whole library is about 600 lines, with the query execution itself around 200.

What to watch for

Clojure is not optional, and if your JVM and Clojure fundamentals are thin, you will be learning two things at once. The library count is a real learning curve too, and the docs recommend reading them in a specific order, starting with biff.core.

Datastar is the less-traveled path. The author writes that he has not personally used it at scale, and that for a Serious Project you should take your own measurements. The architecture is immediate-mode: each page holds a long-lived SSE connection, and any change to backend state re-renders the page and pushes compressed HTML to the client. That gives you realtime and collaborative features nearly for free, but it is not the request-response setup most Clojure developers have muscle memory for.

The “built for maintainability at enterprise scale” claim comes from the author’s own background working on enterprise SaaS rather than from a large user base, since the project has about 1,100 stars. Version 2.0 is roughly seven weeks old at the time of writing, and the last 1.x release was v1.9.0 in September 2025. If you are migrating, the project publishes a guide for moving from Biff 1.0.

Source and Accuracy Notes

  • Project page: https://biffweb.com/ (verified by direct visit on 2026-11-01)
  • Source repository: github.com/jacobobryant/biff (MIT license, Clojure, 1,125 stars, 57 forks, 2 open issues)
  • Starter project: github.com/jacobobryant/biff-starter, used for the module and resolver examples above
  • Latest release: v2.0.0, published 2026-09-10. Library artifacts are published separately at 2.0.5
  • HN launch thread: https://news.ycombinator.com/item?id=49647635 (29 points, 2026-09-10)
  • Design background: https://biffweb.com/p/biff2/
  • Library versions, task names and code samples read from the project READMEs and API docs on 2026-11-01