Biff

Understanding Datastar

2026-10-01T15:00:00.000Z

Previously I wrote Understanding htmx which was meant to explain htmx conceptually, what the main tradeoffs are, and when you might want to use or not use it. This post is a followup to that for Datastar. Both of these posts describe how I personally think of these tools; if others disagree with my framing, I make no apologies.

Also note that the web apps I make do not typically include collaborative or real-time features, yet I still think Datastar is nice for this case. My explanation here focuses on things that matter for people like me who make boring apps.

htmx and Datastar are both tools for doing server-side rendering instead of e.g. using React; they both ask "what if we went back to how things were pre-jquery and tried to extend that model of thin-client web development instead of moving toward SPAs." They differ in how they implement that vision.

make an MPA
each page is a resource
keep a stream open on the current state of that resource

-- a guy from the Datastar community

Imagine: it's 2005. You have an MPA. Each page in your web app--a social network for Tapirs--has a GET request handler (which returns a bunch of HTML for the page) and an assortment of POST request handlers that do stuff and then redirect back to that HTML endpoint. But then you run into the problems I brought up in Understanding htmx:

You need to implement the heart button so that people can heart their favorite posts. However, if your heart button is a plain-old-form that causes the entire page to reload, there are several potentially undesirable consequences:

All the posts in the feed will have to be fetched again.

The posts that get fetched might be different.

The user might lose their scroll position.

The user might lose their draft if they were in the middle of typing a post.

The Datastar approach looks something like this:

The initial page load opens a long-lived SSE connection. Whenever backend state changes (e.g. a database transaction is committed), the entire page is re-rendered and pushed up to the client over the SSE connection—a bit like telling the client to refresh the page but without doing an actual browser refresh.
When the user takes an action, like hearting a post, Datastar makes an ajax request to a POST request handler which updates the database. Since that triggers a re-render by the SSE connection, the POST handler doesn't redirect or return any HTML; it simply returns an empty 204 response.
Any state on the page that you don't want to recompute (e.g. a list of recommended posts) can be stored in server-side "tab state," keyed by some ID that's unique to a single browser tab. For example, on page load, you could trigger an action/POST request that computes the recommended posts and stores them in tab state. The GET request handler does not compute recommended posts; it just reads tab state. If tab state hasn't been populated yet, it shows a loading indicator.
If you have an interaction that needs to be fast and you don't want to wait for a server round-trip before re-rendering happens, you can have the interaction update some "signals," which are Datastar's mechanism for handling frontend-only state. A common use case for this is storing form field values: when you're typing into a text field, you don't want to wait for the network before the characters show up.

Your application code has the same structure as the MPA-in-2005-thing; the main differences are that your POST handlers return 204 instead of 303, and you instrument all your form fields so they're bound to signals. You get to keep the single page rendering endpoint/function which gives you the whole "view is a function of your state" thing, and then you can get rich interactivity on top thanks to the SSE stuff.

The cost: more moving parts on the backend, which means more work to set up your codebase and more opportunities to screw something up. And your page rendering function needs to be fast since it's going to get called a bunch of times; that could require some restructuring (such as the example above of using an action on page load to compute recommended posts).

htmx on the other hand doesn't try to overhaul your backend architecture. You're typically doing standard request/response rather than this SSE thing. The downside is that your application code has to do more stuff. You click a button, htmx triggers a POST request, then the backend request handler has to know what chunk(s) of html needs to be re-rendered and where those chunks should be inserted in the DOM. Which is kind of imperative! You no longer have this dead simple "the page is rendered by a single function" thing.

So when should you use Datastar? My take: I don't think the downsides of Datastar I've mentioned above are that big of a deal, especially if you're using a library that sets up the plumbing for you (ahem). The main situation in which I'd be tempted to not use Datastar is if I'm building something very small where plain-old form-posts-with-redirects is fine.

I'm not sure I see any cases where I would use htmx again: I figure if I'm making something complex enough to warrant htmx instead of plain form posts etc, then the overhead of setting up Datastar is probably negligible.

Biff 2.0 is released

2026-09-10T16:00:00.000Z

Last April I outlined some changes I had planned for Biff, which included making SQLite the default database, splitting the monolithic com.biffweb namespace into a bunch of independent libraries, using Datastar by default, introducing some new approaches for keeping large codebases maintainable, blah blah blah, and bumping the version to 2.0.0. I'm pleased and slightly exhausted to announce that those changes are SHIPPED and you can try them out like this:

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

I have tweaked the landing page, written the documentation, and even started, just barely, to actually use Biff 2 to make a new app.

If you've used Biff 1, then please be advised that there are technically no breaking changes (since everything is in new namespaces) and that I've written up some guidance on gradually introducing Biff 2 into a Biff 1 codebase, if you so desire. There are some breaking changes if you've already been trying out the Biff 2 prereleases.

A few things from Biff 2 that I find particularly interesting, some of which are covered in more detail by the aforementioned blog post:

This demo.clj file from the starter project gives a short yet representative taste of what application code in a Biff project actually feels like. Note the parameters injected into demo-page by biff.graph; the POST request handlers that return their side effects as data via biff.fx; the fact that only a single handler needs to return HTML and those POST request handlers don't need to concern themselves with rendering at all, and yet the page is fully reactive--thanks to Datastar.
The starter project is now a standalone repo and can be easily forked and modified if you want to create an alternative starter project (with, say, a different database).
Speaking of using different databases, there is a guide on writing a database adapter. This makes switching out the default database much easier than it was in Biff 1 (no need to rewrite the authentication module, for example).
biff.core's new module system. The flip side of making Biff more modular is that there's an increased need to have well-defined interfaces for the modular pieces to plug into. I decided to extract Biff's "framework" logic into a library not just to reduce boilerplate but also to ensure things are being done the way that Biff 2 libraries expect.
defpipeline, a very recent addition to biff.fx that cuts down the boilerplate and IMO makes using biff.fx feel pretty ergonomic.
biff.graph of course. The whole thing.
biff.run and biff.tasks, the latter of which has a video demo of using the prod-setup and deploy tasks to deploy a vanilla (non-Biff) Clojure app to a fresh VPS.

My overall thoughts on where Biff has ended up: I'm definitely taking some bets here. biff.fx and biff.graph are a bit weird. Awesome, but weird. Will the benefits really matter for the projects people use Biff for? biff.core's module system, despite being fairly lightweight, is still not as lightweight as the 5-line reduce call that Biff 1 used. Does that similarly push Biff further out of good-for-a-weekend-project territory? At the same time as I'm adding these features to benefit large codebases, does switching to SQLite--an embedded database--make Biff less attractive for projects that are likely to end up with large codebases?

My north star is still "what do I want for myself," so despite the hypotheticals above, I'm not actually that concerned: I think all this new stuff is ridiculously sweet. And I do think the modularity and the related ease of making alternative starter projects is somewhat huge. Biff is much more evolvable now. If I've gotten anything wrong, it really shouldn't be that difficult for anyone (including my future self) to fork my starter project and fix whatever it is that needs fixing.

Except for biff.core; we're stuck with that part now.

A bundle of CLI tasks for tools.deps projects

2026-08-18T17:00:00.000Z

I've just released biff.run, a very light clj-based task runner; and biff.tasks, a bunch of default CLI tasks that can be used in tools.deps projects.

The tasks are mostly the same as what I've already been including with Biff projects for the past several years. I've reworked them a bit, added a few new tasks, and have structured them to be hopefully useful for tools.deps projects in general rather than being coupled to "Biff projects."

The biff.tasks docs linked above gives a good overview of what tasks it includes. Some unorganized thoughts/random stuff I think is interesting/design opinions:

biff.run is an answer to the question "what's an ergonomic way to publish a curated collection of tasks rather than a single task." Instead of one deps.edn alias per task, there's a single :run alias for all your tasks.
A criticism of tools.deps is that it's lacked various functionality that lein has had built in (simple but not necessarily easy). biff.tasks is my take on addressing that, and I'm interested in if it could help people get going with Clojure more smoothly. However Biff users specifically are still the main audience I'm designing stuff for; time's limited.
Startup time has been fine. I've settled on a few approaches for managing it: each task goes in a separate namespace so biff.run can load only the code for the task you're running; tasks use requiring-resolve when they have heavy dependencies that are used conditionally; some tasks shell out to pre-compiled binaries (like cljfmt and clj-kondo). In return, being able to do everything in plain Clojure and use the regular dependency tooling is nice.
I did tinker with passing the classpath to Babashka like bb -cp $(clj -A:run -Spath) -m com.biffweb.tasks.lib -h. Seems like it'd be kinda cool to default to plain clj but then say "push this button to get instant startup times with Babashka instead." It hasn't been a huge need for me though so I haven't explored it too much.
Speaking of pre-compiled binaries, biff.tasks uses some internal machinery that makes working with these binaries pretty seamless. biff.tasks specifies a default version for each binary, users can set a different version in their project config if desired, and whenever a task needs to use that binary, biff.tasks ensures the right version is installed. If not, biff.tasks downloads the correct version. Example.
biff.tasks doesn't include a task for creating a new project because IMO project templates should provide a way to use them without having to install another tool first. That's perhaps the one bit of functionality that might be nice to have baked into clj; only then could I as a project template author safely assume that all my users will already have the task installed.
biff.tasks does come with an init task that renames the current project's main namespace from com.example to a namespace that the user provides. The idea is that you use project templates by doing git clone <some template>; rm -rf .git; git init; clj -M:run init. (The project template would have biff.tasks already installed in its deps.edn). Probably with that all wrapped up into a little script so you get a nice one-liner.
For library projects, I settled on a docs task that turns your docstrings into markdown files like this one. I'm quite fond of it.

Deploy an app with biff.tasks

2026-08-18T16:00:00.000Z

I demonstrate how to provision a new Ubuntu server on DigitalOcean and deploy a hello-world Clojure web app to it with biff.tasks.

biff.tasks

biff.datastar, biff.ring

2026-08-10T15:15:00.000Z

A couple more Biff 2 libraries are out the door:

biff.datastar: the dumbest/awesomest possible way to make a reactive, server-side-rendered web app. Over the past several years I haven't put much priority on making it easy to make fancy reactive/real-time/collaborative UIs since my UI needs are typically pretty simple. But this architecture is actually really nice even when you don't need the fancy stuff.
biff.ring: mostly some Biff-related plumbing code. I think the defroute macro is pretty nice. There's a cool wrap-csrf-protection middleware that doesn't use tokens.

The last "big" Biff 2 library I need to fix up and release will be biff.tasks, the one for all the CLI tasks. Other than that there's biff.authentication, the email-powered authentication module thing (now with a default sign-in form included) and a few other doodads. And then a starter app. And some documentation that ties all the libraries together, not just documentation for the individual libraries (which I've been writing as I go).

I'm still shooting to have all that released before the conj, which is... coming up. On the bright side, in the window of time between writing the first draft of this post and sending it out, I've already finished editing the biff.tasks code and only need to write the documentation. So I'd say we're well on our way.

Database adapters in Biff 2

2026-07-23T14:30:00.000Z

I've released two new Biff libraries, both database adapters: biff.sqlite and biff.xtdb. Both of them implement some interfaces used by various other Biff libraries, and they also both implement additional functionality that can be useful to Clojure apps even if they aren't using Biff.

The interfaces

So far, modifying a Biff app to use a different database than the default has been kind of inconvenient, as a result of my philosophy about modularity for Biff 1. The ability to swap out defaults was more of an escape hatch so that starting out with Biff doesn't mean you're locked into all its choices forever. So that meant if you wanted to swap out the database, you had to, for example, copy and paste all of Biff's sign-in-via-email code and rewrite the queries.

With Biff 2, modularity is becoming more of a first-class citizen. Hence these new "interfaces." And the main interface here addresses the question of, you know, how do you put things in a database. And get them back out. For Biff 2, I wanted be able to package up shared application functionality that needs persistence (such as the authentication module) in a database-agnostic way.

So Biff 2 now defines a key-value store interface which can be implemented by database adapter libraries like the two I've just released:

And my two implementations: sqlite and xtdb. These KV-store functions are exposed via a biff.core module, for example.

In general I try to avoid adding layers to things unnecessarily, so it took a little thinking to arrive at this solution. My main thought was that I'm primarily interested in database-agnosticism for libraries, not applications. Migrating a single application's database is a different use case than wanting to provide functionality for multiple applications using different databases, and it's the latter use case that I'm trying to address.

So I didn't want to introduce some sort of "Biff query/transaction language" that you'd use whenever writing a Biff app; that would be overkill. The database-agnostic libraries I wanted to write have only basic persistence needs, so a key-value interface is sufficient. And that's an easy interface for database adapters to implement.

The second biggest interface-type-thing is that both adapters come with make-resolvers functions (sqlite / xtdb) which generate a set of biff.graph resolvers for the tables in your application schema.

The features

Besides the key-value functions and a couple other doodads, the remaining functionality in these database libraries is just whatever stuff I thought would be nice to have when writing a Clojure app using the respective databases. From biff.sqlite's README:

Sane defaults like WAL mode, STRICT tables, etc.

Backup/restore via Litestream.

Migrations via sqldef.

Rich schema types: define columns as e.g. booleans, instants, nested maps, etc; and biff.sqlite converts them to/from SQLite's supported types (ints, blobs, etc).

Validate transactions based on centralized authorization rules you define (helps to keep LLM code secure).

And for biff.xtdb:

Start up an in-process node with high-level config defaults.

Custom :biff/upsert and :biff/assert-unique transaction operations.

Optionally enforce Malli schemas on write.

Define centralized authorization rules for validating transactions.

biff.sqlite is a chonkier library due to all the logic needed for supporting rich schema types.

Write your own database adapter

Finally, I have written a database adapter guide which lists all the interfaces that adapters should implement and suggests additional features that may or may not be relevant for any given database. Between that guide and the two sqlite/xtdb reference implementations, I'm hoping it should be straightforward to implement an adapter for whatever database you want to use. I will probably only maintain the SQLite and XTDB adapters, but I might publish some as-is code for other databases which could be picked up and maintained anyone who so chooses.

Plug: my team is hiring for a senior software engineer, writing ClojureScript and Python. We make optimization software for clean energy projects.

biff.fx: lightweight effects system

2026-06-16T17:20:00.000Z

I'm releasing another Biff 2 library: biff.fx. It's a lightweight approach to removing effects from your application logic, which makes that logic easier to understand, test, and reuse.

There are basically two ideas here. First is the common approach of having your code return data describing effects (http requests, database queries/transactions, etc) it wants to run instead of running those effects directly. So for example, instead of calling (http/request "https://example.com" {:query-params {:foo "bar"}}), you would return a vector like [:my-application.fx/http "https://example.com" {:query-params {:foo "bar"}}], and then some sort of orchestrator would call http/request for you. Then it's easy to unit-test your code since it's pure, and if you wanted to swap out certain effect implementations when running integration tests, that's easy to do too.

You could set something like that up with Ring middleware where effects run before and after the handler. Handler functions could somehow declare what input data they need/what database query they need to run, if any, and then they could return some effect data for any database transactions etc they need to do afterward.

That works as long as you can structure your logic and effects like a sandwich, with effects on the outside and gooey, pure logic on the inside. What if you need logic on either side of an effect though, i.e. what if you need to interleave logic and effects? For example, in one of my apps I have some code to initialize a Stripe checkout session. It has to:

Query our database to see if the current user has a Stripe customer ID
If not: hit the Stripe API to create a new customer and save the returned ID in our database
Hit the Stripe API to create a new checkout session
Save the session ID in our database and redirect to a URL returned by the Stripe API

The database bits can be pushed before and after our logic, however the HTTP requests can't. So what do we do?

One approach would be to just have a special case for situations like this under the assumption that most of your code can in fact be structured as a sandwich. i.e. write a plain-old-impure-function and be on with your day.

Another approach is to use data not just to describe effects but also to describe control flow. One of the shapes that approach can take is:

Each "chunk" of logic from a previously impure function is extracted into a separate, pure function.
Those functions can return data that describes both (1) what effects they need to run, and (2) which pure logic function should run next.

i.e. you make a state machine where the states are pure logic and effects happen in the transitions. And that's what biff.fx does.

Plug: my team is hiring for a senior software engineer, writing ClojureScript and Python mostly. We make modeling software for renewable energy projects.

New library: biff.core

2026-06-09T17:00:00.000Z

As I wrote about previously, I've been working on splitting Biff up into a bunch of separate libraries and changing various things along the way. I've completed a rough draft of all twelve libraries and am now going through them one-by-one to polish and release them. The first library is now ready.

biff.core: system composition and other interfaces for Biff projects. This is the glue that holds all the other libraries together, and that's why I'm releasing it first.

For a long time Biff has had this "modules and components" structure where each application namespace in your project exposes a "module" map, then you have a bunch of boilerplate to combine stuff from those modules into a single "system" map, and then we thread the system map through your "component" functions on startup. Biff 2 retains that structure, and it has some additional stuff to deal with that boilerplate.

For an example of what I'm talking about, see this code which takes the :routes (and :api-routes) keys from your modules and turns them into a :biff/handler value for the system map. I wanted a first-class way to be able to extract that kind of logic cleanly into a library so that the library's instructions can just be "add this module to your project" without an accompanying "and then paste all this stuff into your main namespace."

So this new biff.core library includes a concept of "init functions." These are functions that take a collection of modules and return a single map that can be merged into your system map. Ta da. Here's an example. Init functions are stored in the :biff.core/init key in your module maps, so we get that nice "all you need are modules (well, and components)" effect.

The main complication here is that the boilerplate of defining a (def handler ...) var in your application code actually has a nice side benefit: late binding. If you change any of your modules, the handler var will get updated, and if you set :biff/handler in your system map to the var instead of the value (#’handler), incoming Ring requests get the latest handler without you having to restart the web server. If we extract that boilerplate into library code, we don't get the var.

I ended up on this solution:

Init functions take a var of your modules vector, not the vector value itself.
Anything in the system map that you want to get updated without a restart needs to be a function. In some cases this means instead of setting a :com.example/my-thing key on the system map, you need to set a :com.example/get-my-thing function which returns my-thing.
That function on the system map should dereference the modules var and pass it to a memoized function that builds whatever thing it is you need (like the Ring handler).

Again, see this example. The result is kind of aesthetically pleasing: you get a nice clean main namespace that shouldn't need to change much, and all you do is add modules and components.

There's always the temptation to consolidate things further. Why even have a separate components vector? Why not have modules support :biff.core/on-start and :biff.core/on-stop keys and then have some way to express dependencies between these lifecycle functions so we can call them in the right order?

And the answer is so that we don't have to have some way to express dependencies between these lifecycle functions so we can call them in the right order. It's not that hard to put the components in the right order yourself (especially since the Biff starter project does that for you), and then it's easier to understand how components work. It's just a sequence of functions that you pass a map through. If you work on a project with so many stateful resources that it's hard to keep track of them all, you can always layer something on top that figures out what your components vector should be before you pass it to biff.core.

Plug: my team is hiring for a senior software engineer, writing ClojureScript and Python mostly. We make modeling software for renewable energy projects.

Biff 2.0 sneak peak

2026-04-20T18:25:00.000Z

I have for the past year or two been working on some large Biff changes, such as those discussed in Structuring large Clojure codebases with Biff and Biff support for XTDB v2 is in pre-release. Now that coding agents have gone mainstream (and in particular, now that I personally have started using them heavily), I've had a few more ideas for changes I'd like to make to Biff. And also thanks to coding agents, I've actually been able to make consistent progress instead of my Biff development time being bottlenecked by how late I can stay awake on weekend nights after my kids are sleeping. So we, fingers crossed, are getting close to some major Biff updates, and I figure I may as well slap a 2.0 label on it.

Here's what I've got in the works.

SQLite will be the default database

This is the biggest change. Biff will retain first-class support for XTDB, but it'll also have first-class support for SQLite, and I'll update the starter project to use SQLite by default. There will still be a (non-default) starter project that uses XTDB.

Biff has used XTDB since its (Biff's) initial release in 2020, back when the database was still called Crux. About a year ago I started working on migrating Biff from XTDB v1 to XTDB v2, which brings a whole new architecture, including column-oriented indexes that make analytical queries faster. Besides writing some Biff-specific helper code for XTDB v2, I migrated Yakread (a 10k-LOC article recommender system) to v2 and did a bunch of benchmarking for Yakread's queries. (A big thank you to the XTDB team who responded to lots of my questions during this time and also made a bunch of query optimizations!)

Long-story short: despite the optimizations, I had trouble getting Yakread's page load times to be as quick as I wanted. For the particular queries Yakread runs—which are mostly row-oriented—I've generally found v2's performance to be slower than v1. There is also a larger per-query latency overhead, perhaps another design tradeoff of the new architecture (you can still run v2 as an embedded node within your application process, but it’s designed primarily to be run on a separate machine like more traditional networked databases).

I also will admit that before this benchmarking exercise I had not actually used SQLite much, and I was unaware of how ridiculously fast it is. And one of the main downsides of SQLite when compared to XTDB—that SQLite is a mutable database—is mitigated by Litestream, which streams changes to object storage and lets you restore from (and even run ad-hoc queries on) historical snapshots saved with 30-second granularity.

I could see myself switching back to XTDB at some point in the future. It's still the early days for v2 and the XTDB team is doing lots of work, including on query performance. And SQLite's speed comes with tradeoffs:

Scaling beyond one machine is an unsolved problem. Litefs can let you put SQLite nodes in a cluster where writes get forwarded to a single leader and changes are streamed to the other nodes. However, to use it with Litestream, you have to disable automatic leader failover. So you basically have to choose between HA or PITR.
SQLite only supports a few basic datatypes: ints, floats, strings, and blobs (byte arrays). A large part of my work in integrating SQLite into Biff has been to set up automatic data type coercion so you can use richer types (UUID, boolean, instant, enum, map/set/vector) in your schema without having to do manual coercion when reading and writing.
Litestream's snapshots-at-30-second-granularity is fine for recovering from bad transactions like a DELETE FROM without the WHERE, but it's less helpful than XTDB/Datomic for the debugging-weird-production-issues use case: you can't include a transaction ID or similar in your production logs and then re-run queries with 100% confidence that the results you're seeing are what the application saw when it e.g. threw an unexpected exception.

I was chatting with Jeremy from the XTDB team last week, and he mentioned they've been working on having XTDB ingest changes directly from Postgres. It sounds like it shouldn't be much work to make that work with SQLite too, which means that you could stick an XTDB node alongside your SQLite-powered Biff app and then get more granular historical queries. Maybe XTDB could be a replacement for Litestream?

That could get even more interesting if eventually we can do the inverse as well, where data from our immutable XTDB log could be sent both to a bitemporal index for historical queries and also to SQLite "indexes"/databases for the application servers to use. That would solve the HA problem too.

Anyway. However it happens, I'm looking forward to the glorious future when we finally have an inside-out database that's fast for all query shapes, highly available, models time correctly, and can even do advanced things like let you put a UUID in it. In the meantime, I think SQLite is a reasonable default given Biff's focus on solo developers, and I would absolutely consider XTDB today for situations in which modeling time correctly is a top concern.

Alternate starter projects will get easier

Biff consists of a starter project, a bunch of helper code exposed through a single com.biffweb namespace, tooling for CLI tasks and deployment, and a big pile of documentation. The com.biffweb namespace is on its way out: I'll be publishing Biff helper code as individual libraries like com.biffweb.sqlite (and com.biffweb.xtdb), com.biffweb.authentication, com.biffweb.middleware, com.biffweb.config, etc.

Part of the motivation for this change is that Biff is more mature than it was five years ago and it's become more clear what the different cohesive parts of Biff should actually be. I started out with a single kitchen-sink library because splitting it up felt premature; I didn't think it would realistically make sense to use one of them outside a standard Biff project that would already be depending on all the Biff libraries anyway.

But over the past few months, I've been developing a couple new side projects from scratch without even using Biff. As I've done this, I've started extracting various things into standalone libraries, and this time I do see them as useful libraries in their own right. For example, the new biff.authentication library will be an easy way to add email-based authentication to any Clojure web app that uses Reitit—it even comes with a default sign-in page.

The other factor behind this change is agent-driven development. The difficulty of mixing-and-matching different libraries is dramatically easier now to the point where I wondered briefly if Biff was even needed anymore. Developing those new side projects via agent has disabused me of that notion: agents still need a lot of structure (e.g. in the form of these Biff libraries) to guide them. Even for starting new projects, why have everyone generate a different starter project via some prompt when you could have a single person generate the starter project, make sure it actually works, and then publish that?

That's still a meaningful change though: the effort required to create and maintain new project templates has decreased significantly. So I think it makes more sense for Biff to be split up into multiple libraries that can themselves be mixed-and-matched. I will myself provide Biff starter projects for SQLite and XTDB, respectively. If anyone else wants to make a Biff starter project variant with different library choices, they'll similarly be able to do that without much effort.

For vanity reasons, I'll need to continue having a single "main" Biff repo of some sort (did I mention Biff hit 1,000 github stars recently?). Maybe I'll have that repo be the default starter project.

New approaches for structuring application logic

Two of these Biff libraries that happen to contain some new stuff—instead of being a splitting-out of code that was already in Biff—are biff.graph, which lets you structure your domain model as a queryable graph, inspired by Pathom; and biff.fx, which helps you remove effectful code from your application logic via state machines.

Both libraries help you write purer code (and thus code that's easier to understand and test). biff.graph is a higher-level abstraction that helps with code that reads data. biff.fx is a lower-level thing that I mostly use when writing data. However they're also useful together: e.g. my GET request handlers are typically biff.fx machines that run a biff.graph query and pass the results to the (now pure) rendering code:

(def some-route
  ["/some-page/:id"
   {:get
    (fx/machine ::some-page

      :start
      (fn [{:keys [path-params] :as request}]
        {:stuff [:biff.fx/graph
                 {:stuff/id (parse-uuid (:id path-params))}
                 [:stuff/foo :stuff/bar]]
         :biff.fx/next :render-stuff})

      :render-stuff
      (fn [{:keys [stuff] :as request}]
        {:status 200
         :headers {"content/type" "text/html"}
         :body (render-html
                [:div "foo: " (:stuff/foo stuff)
                 ", bar: " (:stuff/bar stuff)])}))}])

biff.fx provides a defroute macro to make this kind of thing more concise, so the code I actually write looks more like this:

(fx/defroute some-page "/some-page/:id"
  [:biff.fx/graph
   {:params/stuff [:stuff/foo :stuff/bar]}]

  :get
  (fn [request stuff]
    [:div
     "foo: " (:stuff/foo stuff)
     ", bar: " (:stuff/bar stuff)]))

I'll save a fuller explanation for later; hopefully that gives you the flavor of what these libs do.

I've been using Pathom heavily over the past few years, both for work and pleasure. I've started referring to the code structure it enables as “data-oriented dependency injection.” It helps you structure your application in small easy-to-understand chunks that declare exactly what data they need as input and what data they provide as output. The main downside in my experience is that it can be difficult to understand exactly what Pathom is doing and debug when things go wrong.

For “serious” projects, that's a price worth paying. For the kinds of solo projects that Biff is aimed at, I've felt apprehensive about foisting another layer of abstraction on people for code structure benefits that they may or may not notice.

However, my own experience is that even for small apps, the benefit is real. So biff.graph is an attempt to provide the same graph computational model / “data-oriented dependency injection” with as small of an implementation as possible: biff.graph is about 400 lines of code currently, whereas Pathom is closer to 10k.

The main tradeoff I've made in service of that goal is to omit the query planning step that Pathom uses. biff.graph traverses directly over your input query, looking up which resolver(s) to call for each attribute as it goes. For each resolver, biff.graph runs what is more-or-less a separate query to get that resolver's inputs. This hopefully makes biff.graph easier to trace and understand what it's doing, but it also means biff.graph isn't able to optimize the query plan the way Pathom does. (biff.graph does support batch resolvers and caching at least).

biff.fx is more of an original creation. Instead of a single function, you have a map of functions, one for each state. Effects happen in the transitions. You define global “fx handlers” that do things like HTTP requests, database queries/transactions, etc, represented by keywords (e.g. :biff.fx/graph in the example). I’ve changed up the format for describing effects a few times; I think I've finally landed on something that feels ergonomic ([:do-something arg1 arg2] as a replacement for (do-something! ctx arg1 arg2)).

Authorization rules are so back

Biff entered this world as a replacement for Firebase, which I had enjoyed using but left me with the desire for a regular long-lived clojure backend. Firebase lets your frontend submit arbitrary transactions from the frontend, and then they're checked against some centralized authorization rules you define (e.g. “documents in the stuff table can only be edited if the current user's ID is the same as stuff.user_id”). I implemented a similar thing where you would submit transactions in a format similar to Firebase's, then I would translate them to XTDB's transaction format and pass a diff of the database changes to your authorization functions.

I ended up abandoning the SPA approach altogether for server-side rendering (with htmx), and that made authorization rules unnecessary since transactions were originating from the backend: I no longer needed to validate completely arbitrary transactions.

Once again, coding agents have changed the game. When working on mature codebases, of course we all read our generated code carefully before submitting a pull request. But when I've got a new app idea, I want to mostly just vibe code it until I get to the MVP. I'd like to be able to do a light review just to make sure the structure of the code is reasonable. With authorization rules, you can carefully review those central rules in the same way you'd carefully review the database schema, and then you can have confidence that the feature code isn't missing an authorization check. (Of course you still have to make sure the agent didn't bypass the authorization rules...)

This is only for writing data. For reading data, I typically have a few Pathom/biff.graph resolvers that e.g. read an entity ID from the incoming request's path parameters and ensure the user has access to that entity (like the :param/stuff resolver alluded to in the example above). Other related entities are queried as joins against that root entity, so if the authorization check fails, the rest of the query will fail too. So once again you have a way to put authorization logic in a central place that can be reused by your feature-specific code.

oh yeah and datastar

As mentioned above, Biff uses htmx. I like server-side rendering and I think it's a particularly good fit for Biff's solo developer focus. htmx however has a critical flaw: it's too popular. It has 47k github stars—that's half of what Tailwind has.

Datastar fixes this problem by being a much younger project—a niche of a niche. There is a much smaller chance that your colleagues will have heard of it. Datastar also has some smaller but still tangible benefits:

It has some frontend reactivity built in. With htmx, you typically use another tool like _hyperscript or Alpine.js to provide interactivity in cases where you really don't want to wait for a server roundtrip (e.g. a dropdown menu). Datastar has a concept of "signals" baked in so you don't need a second tool.
It has a smaller API surface; much of what htmx offers is replaced by "just use out-of-band swaps." So it might be easier to learn?
It works well for fancy CQRS stuff (still on my list of things to try out).

Of the changes I've mentioned, this one is the most experimental. I actually haven't even made an official decision if I really will switch Biff from htmx to Datastar; at this point I'm just making a prediction that I probably will.

More broadly I would like to explore how far I can push the server-side rendering model before I feel it breaking down. e.g. what approach would I use with it to handle forms with 50+ fields and lots of conditional logic, complex validation logic etc? How about charts? (What I'm getting at: would I regret asking an LLM to migrate our large codebase at work over to htmx/Datastar?).

I’d like to give an honorable mention to inline snapshot testing which I’ve been excited about for a year and a half but now find unnecessary—counterproductive, even—with coding agents. I had started working on some updates to my test code so you could do inline snapshot tests in plain .clj files instead of in .edn files (turns out that tooling support is best when you put your code in files meant for code). But with coding agents, I’ve found that I don’t want tests that auto-update when the actual result changes: it’s too easy for agents to ignore new results that are obviously incorrect. And of course I don’t care if my coding agent finds updating unit tests to be tedious. So the test-related stuff that Biff does will be limited to making your application code more pure so you (your agent) can write dumb (is (= (f x) y)) tests. I might add some structure/patterns for integration tests, though.

Another change driven by coding agents, not a change to the code but a change to my philosophy: I'm more interested in smaller projects. As mentioned, my time for working on personal projects has been extremely limited until a few months ago. I've only ever had a single Biff project at a time that I have attempted to work on regularly; new projects started after the old one failed. So the primary use case I designed Biff for was “serious side projects,” applications that may be solo projects now but will definitely be bringing in a 6-figure income and fulfilling all your entrepreneurial desires at... some point. That one project is the only thing I've ever had a chance of having time for.

Now I can code up an MVP for something over a weekend without ever sitting down at my desk. I built an app that helps me find good Star Wars: Unlimited decks to play. I'm building a blogging platform next. After that maybe I'll build a music recommender system. Or a state legislation tracker/summarizer.

I'm having a blast. Maybe that will affect design decisions I make down the road? I certainly am interested in the use case of doing agent-driven development from a mobile device, so maybe expect something in that area.

Biff support for XTDB v2 is in pre-release

2025-11-09T11:00:00.000Z

I've been working on/preparing for migrating Biff to XTDB v2 since that became generally available in June. After investigating the deployment options and performance characteristics, I've added some XTDB v2 helper functions to the Biff library (under a new com.biffweb.experimental namespace) and I've made a version of the starter project that uses XTDB v2.

You can create a new XTDB v2 Biff project by running clj -M -e '(load-string (slurp "https://biffweb.com/new.clj"))' -M xtdb2. See this gist for a diff between the old/main starter project and this new one.

To give you a quick overview of what Biff provides:

There are use-xtdb2 and use-xtdb2-listener components, roughly the same as we have already for XTDB v1.
The ctx map will have a :biff/conn key in it (a Hikari connection pool object) which you can pass to xtdb.api/q to do queries.
There is no longer a custom Biff transaction format. There is still a lightweight wrapper function, com.biffweb.experimental/submit-tx, which will apply Malli validation to any :put-docs / :patch-docs operations.

There's still plenty of work to do before XTDB v2 support in Biff is officially released and becomes the default:

Next up, I'm migrating Yakread to XTDB v2. This will help me find any more issues that need to be addressed/make sure that Biff is indeed ready for XTDB v2.
After that I need to update a bunch of documentation, including the tutorial project.

Since those next two steps will take a while, I wanted to do this "pre-release" for anyone who would like to get a head start on trying out Biff with XTDB v2. If you do so, let me know whatever questions/comments you have. Just note that the new functions in Biff's API are still experimental and might have breaking changes before I do the official release.

And for anyone who would rather not deal with migrating an existing app, Biff will still support XTDB v1. It's totally fine to stay on that.

Finally: I'll be at Clojure/Conj next week, at least if my flight doesn't get canceled. Come say hi.