Saying Hello You with ClojureScript

Notes

• Code
• Why am I learning Clojure Script?
• Google Closure manintained by Clojure community
• Learn ClojureScript
• Data Star

Permalink

Time-Travel Debugging in State Management: Part 1 — Foundations & Patterns

📖 Series: Time-Travel Debugging in State Management (Part 1 of 3)

From debugging tool to competitive UX advantage

Introduction

Imagine: you're testing a checkout form. The user fills in all fields, clicks "Pay"... and gets an error.

You start debugging. But instead of reproducing the scenario again and again, you simply rewind the state back — to the moment before the error. Like in a video game where you respawn from the last checkpoint.

This is Time-Travel Debugging — the ability to move between application states over time.

💡 Key Insight: In modern applications, time-travel has evolved from exclusively a developer tool to a standalone user-facing feature that becomes a competitive product advantage.

💡 Note: The techniques and patterns in this series work for both scenarios — debugging AND user-facing undo/redo.

Use Cases

In this article, we'll explore architectural patterns that work across all these domains — from simple forms to complex multimedia systems.

Terminology

This article uses the following terms:

💡 Note: "State unit" is used as a universal abstraction. Depending on your library, this might be called:

• Atom (Jotai, Recoil, Nexus State)
• Slice / state key (Redux, Zustand)
• Observable property (MobX, Valtio)
• Signal (Solid.js, Preact)

Terminology Mindmap

mindmap
  root((State Unit))
    Atom
      Jotai
      Recoil
      Nexus State
    Slice
      Redux Toolkit
      Zustand
    Observable
      MobX
      Valtio
    Signal
      Solid.js
      Preact

Code Examples Across Libraries

// Nexus State / Jotai / Recoil
const countAtom = atom(0);

// Zustand (state unit equivalent)
const useStore = create((set) => ({
  count: 0, // ← this is a "state unit"
}));

// Redux Toolkit (state unit equivalent)
const counterSlice = createSlice({
  name: 'counter',
  initialState: { value: 0 },
  //              ^^^^^^^^^^^ this is a "state unit"
});

// MobX (state unit equivalent)
const store = makeObservable({
  count: 0, // ← this is a "state unit"
});

Why "state unit"?

1. Universality — works for any library (not just atom-based)
2. Precision — emphasizes minimality and indivisibility
3. Neutrality — not tied to specific library terminology

What is Time-Travel Debugging?

Definition

Time-Travel Debugging is a debugging method where the system preserves state history and allows developers to:

• View previous application states
• Navigate between states (forward and backward)
• Analyze differences between states
• Replay action sequences

Key Capabilities

interface TimeTravelAPI {
  // Navigation
  undo(): boolean;
  redo(): boolean;
  jumpTo(index: number): boolean;

  // Availability checks
  canUndo(): boolean;
  canRedo(): boolean;

  // History
  getHistory(): Snapshot[];
  getCurrentSnapshot(): Snapshot | undefined;

  // Management
  capture(action?: string): Snapshot;
  clearHistory(): void;
}

Use Cases

1. Debugging complex states — when bugs reproduce only after specific action sequences
2. Regression analysis — understanding which change caused an issue
3. Training & demos — step-by-step user scenario replay
4. Automated testing — sequence reproduction for tests

Historical Context

Early Implementations

Time-travel debugging isn't new. First significant implementations appeared in mid-2000s:

Evolution of Approaches

timeline
    title Time-Travel Debugging Evolution
    2010-2015 : Simple Undo/Redo
              : Full snapshots
              : Limited depth
    2015-2020 : DevTools Integration
              : Redux DevTools
              : Action tracking
    2020+     : Optimized Systems
              : Delta compression
              : User-facing features

Generation 1 (2010-2015): Simple undo/redo stacks

• Full state copy storage
• Limited history depth
• No async support

Generation 2 (2015-2020): DevTools integration

• Change visualization
• Redux-like architecture support
• Action-based tracking

Generation 3 (2020+): Optimized systems

• Delta compression
• Smart memory cleanup
• Atomic state support
• State visualizer tools

Architectural Patterns

1. Command Pattern

Classic approach where each state change is encapsulated in a command object:

interface Command<T> {
  execute(): T;
  undo(): void;
  redo(): void;
}

// For atom-based libraries (Jotai, Recoil, Nexus State)
class SetAtomCommand<T> implements Command<T> {
  constructor(
    private atom: Atom<T>,
    private newValue: T,
    private oldValue?: T
  ) {}

  execute(): T {
    this.oldValue = this.atom.get();
    this.atom.set(this.newValue);
    return this.newValue;
  }

  undo(): void {
    this.atom.set(this.oldValue!);
  }

  redo(): void {
    this.execute();
  }
}

// For Redux / Zustand (equivalent)
class SetStateCommand<T extends Record<string, any>> implements Command<T> {
  constructor(
    private store: Store<T>,
    private slice: keyof T,
    private newValue: any
  ) {}

  execute(): void {
    this.oldValue = this.store.getState()[this.slice];
    this.store.setState({ [this.slice]: this.newValue });
  }

  undo(): void {
    this.store.setState({ [this.slice]: this.oldValue });
  }

  redo(): void {
    this.execute();
  }
}

Pros:

• Explicit operation representation
• Easy to extend with new commands
• Macro support (command grouping)

Cons:

• Object creation overhead
• Complexity with async operations

2. Snapshot Pattern

Preserving full state copies at key moments:

interface Snapshot {
  id: string;
  timestamp: number;
  action?: string;
  state: Record<string, AtomState>;
  metadata: {
    label?: string;
    source?: 'auto' | 'manual';
  };
}

class SnapshotManager {
  private history: Snapshot[] = [];

  capture(action?: string): Snapshot {
    const snapshot: Snapshot = {
      id: generateId(),
      timestamp: Date.now(),
      action,
      state: deepClone(this.store.getState()),
      metadata: { label: action },
    };

    this.history.push(snapshot);
    return snapshot;
  }
}

Pros:

• Simple implementation
• Fast restoration (direct state replacement)
• Easy to serialize for export

Cons:

• High memory consumption
• Data duplication

3. Delta Pattern

Storing only changes between states:

interface DeltaSnapshot {
  id: string;
  type: 'delta';
  baseSnapshotId: string;
  changes: {
    [atomId: string]: {
      oldValue: any;
      newValue: any;
    };
  };
  timestamp: number;
}

class DeltaCalculator {
  computeDelta(before: Snapshot, after: Snapshot): DeltaSnapshot {
    const changes: Record<string, any> = {};

    for (const [key, value] of Object.entries(after.state)) {
      const oldValue = before.state[key]?.value;
      if (!deepEqual(oldValue, value)) {
        changes[key] = { oldValue, newValue: value };
      }
    }

    return {
      id: generateId(),
      type: 'delta',
      baseSnapshotId: before.id,
      changes,
      timestamp: Date.now(),
    };
  }
}

Pros:

• Significant memory savings (up to 90% for small changes)
• Precise change tracking
• Ability to "apply" deltas

Cons:

• Complex restoration (requires delta chain application)
• Risk of "chain break" (if base snapshot is deleted)

4. Hybrid Approach

Modern approach combining snapshots and deltas:

flowchart LR
    A[State Change] --> B{Full Snapshot<br/>Interval?}
    B -->|Yes| C[Create Full Snapshot]
    B -->|No| D[Compute Delta]
    C --> E[History Array]
    D --> E
    E --> F{Restore Request}
    F -->|Full| G[Direct Return]
    F -->|Delta| H[Apply Delta Chain]
    H --> I[Reconstructed State]

class HybridHistoryManager {
  private fullSnapshots: Snapshot[] = [];
  private deltaChain: Map<string, DeltaSnapshot> = new Map();

  // Every N changes, create a full snapshot
  private fullSnapshotInterval = 10;
  private changesSinceFull = 0;

  add(state: State): void {
    if (this.changesSinceFull >= this.fullSnapshotInterval) {
      // Create full snapshot
      const full = this.createFullSnapshot(state);
      this.fullSnapshots.push(full);
      this.changesSinceFull = 0;
    } else {
      // Create delta
      const base = this.getLastFullSnapshot();
      const delta = this.computeDelta(base, state);
      this.deltaChain.set(delta.id, delta);
      this.changesSinceFull++;
    }
  }

  restore(index: number): State {
    const full = this.getNearestFullSnapshot(index);
    const deltas = this.getDeltasBetween(full.index, index);

    // Apply deltas to full snapshot
    return deltas.reduce(
      (state, delta) => this.applyDelta(state, delta),
      full.state
    );
  }
}

When to use:

State Storage Strategies

1. Full Snapshots

// Universal example for any library
function createFullSnapshot(store: Store): Snapshot {
  return {
    id: uuid(),
    state: JSON.parse(JSON.stringify(store.getState())),
    timestamp: Date.now(),
  };
}

// For Redux / Zustand
const snapshot = {
  state: {
    counter: { value: 5 },  // Redux slice
    user: { name: 'John' }  // Redux slice
  },
  timestamp: Date.now()
};

// For Jotai / Nexus State
const snapshot = {
  state: {
    'count-atom-1': { value: 5, type: 'atom' },
    'user-atom-2': { value: { name: 'John' }, type: 'atom' }
  },
  timestamp: Date.now()
};

Characteristics:

• Memory: O(n × m), where n = snapshots, m = state size
• Restoration: O(1) — direct replacement
• Serialization: Simple

2. Deltas

// Universal example
function computeDelta(before: State, after: State): Delta {
  const changes: Record<string, Change> = {};

  for (const key of Object.keys(after)) {
    if (!deepEqual(before[key], after[key])) {
      changes[key] = {
        from: before[key],
        to: after[key],
      };
    }
  }

  return { changes, timestamp: Date.now() };
}

// Example: Redux slice
const delta = {
  changes: {
    'counter.value': { from: 5, to: 6 },
    'user.lastUpdated': { from: 1000, to: 2000 }
  }
};

// Example: Jotai atoms
const delta = {
  changes: {
    'count-atom-1': { from: 5, to: 6 }
  }
};

Characteristics:

• Memory: O(n × k), where k = average change size (k << m)
• Restoration: O(d) — applying d deltas
• Serialization: Requires context (base snapshot)

3. Structural Sharing (Immer example)

Using immutable structures with shared references:

// Example with Immutable.js
import { Map } from 'immutable';

const state1 = Map({ count: 1, user: { name: 'John' } });
const state2 = state1.set('count', 2);

// state1 and state2 share the user object
// Only count changed

// For React + Immer (more popular approach)
import { produce } from 'immer';

const state1 = { count: 1, user: { name: 'John' } };
const state2 = produce(state1, draft => {
  draft.count = 2;
  // user remains the same reference
});

Characteristics:

Note: Characteristics may differ by implementation. For ClojureScript, Mori, and other persistent data structure libraries, complexity will vary.

4. Strategy Comparison

What's Next?

In Part 2 ("Performance & Advanced Topics"), we'll cover:

• Memory Optimization: Delta Snapshots, compression, smart cleanup
• Navigation Algorithms: Undo/Redo, jumpTo, large history optimization
• Transactionality: Rollback restoration, checkpoints
• Performance Issues: Benchmarks, optimizations
• Time-Travel as User-Facing Feature: From debugging to UX

🤔 Food for Thought

Which pattern would you choose for your project?

Think about your current project:

• How often does state change?
• What's the state size (small/medium/large)?
• Do you need deep history (100+ steps)?

Share your choice in the comments!

To be continued... → Part 2: Performance & Advanced Topics

Resources

Libraries with Time-Travel Support

• Redux DevTools Documentation
• Elm Time Travel
• Nexus State Time Travel
• Zustand Middleware
• Jotai Documentation
• Recoil Documentation

Immutable Data Structures

• Immutable.js
• Immer

This is Part 1 of 3 in the Time-Travel Debugging article series.

Tags: #javascript #typescript #state-management #debugging #architecture #react #redux #performance

Permalink

The Power of Framing: Why BigConfig is Rebranding as a Package Manager

BigConfig began as a simple Babashka script designed to DRY up a complex Terraform project for a data platform. Since those humble beginnings, it has evolved through several iterations into a robust template and workflow engine. But as the tool matured, I realized that technical power wasn’t enough; the way it was framed was the true barrier to adoption.

BigConfig is powerful as a library, but I’ve faced a hard truth: very few developers will learn a language like Clojure just to use a library. However, history shows that developers will learn a new language if it solves a fundamental deployment problem.

People learned Ruby to master Homebrew ; they learn Nix for reproducible builds. Meanwhile, tools like Helm force users to juggle the awkward marriage of YAML and Go templates—a “solution” many endure only because no better alternative exists. To get developers to cross the language barrier, you have to offer more than a tool; you have to offer a total solution.

I noticed a significant shift in engagement depending on how I framed the project. When I describe BigConfig as a library, it feels abstract—like “more work” added to a developer’s plate. When I introduce it as a package manager, the interest is immediate.

In the mind of a developer, a library is a component you have to manage. A package manager is the system that manages things for you. By shifting the perspective, BigConfig goes from being a “Clojure utility” to an “Infrastructure Orchestrator.”

Like Nix and Guix , BigConfig embraces a full programming language. However, it avoids the “two-language architecture” common in those ecosystems—where you often have a compiled language for the CLI and a separate interpreted one for the user.

BigConfig is Clojure all the way down (in the spirirt of Emacs). This allows it to support three distinct environments seamlessly:

1. The REPL: For interactive development and real-time exploration.
2. The Shell: For traditional CLI workflows and CI/CD pipelines.
3. The Library: For embedding directly into your own control planes or APIs.

Beyond the language, BigConfig introduces robust client-side coordination, featuring an Atlantis-style locking mechanism that uses GitHub tags to prevent developer collisions in shared environments.

The level of abstraction is where BigConfig truly shines. When you adopt the system, you aren’t locked into a rigid schema; you can adapt the entire engine to your specific needs. Complex tasks—like deploying the same architecture across different hyperscalers—are reduced from massive refactors to simply updating a property. It moves the conversation from how to deploy to what to deploy.

The next phase is focused on expanding the ecosystem and making package discovery seamless:

• Hyperscaler Support: Having already added DigitalOcean , Hetzner , and Oracle Cloud , I am now prioritizing AWS , Google Cloud , and Azure .
• Application Packages: While the first “app”—a remote development environment—is a niche use case, I’m expanding into high-demand stacks like Airflow and Rama .
• The Ecosystem: I am currently defining the formal package manifest and building a registry where users can discover, version, and publish their own infrastructure packages.

The evolution of BigConfig is a testament to the idea that the right abstraction is just as important as the right code. By reframing the tool from a utility you have to manage into a system that manages for you, we bridge the gap between complex cloud resources and developer productivity.

As we expand our hyperscaler support and formalize our package registry, the goal remains the same: to move infrastructure management away from the “how” and toward the “what.” Whether you are deploying a niche remote environment or a massive data stack like a Data Lake, BigConfig provides the language and the logic to make your infrastructure as versionable and reproducible as your software.

Would you like to have a follow-up on this topic? What are your thoughts? I’d love to hear your experiences.

Permalink

Clojure Inheritance… Sort Of

Disclaimer

I want to start off by saying that I don't expect anyone to read this. However, neither OpenAI nor Anthropic's models get this right on the first try, so I figure that writing about it might get picked up in future training runs.

Inheritance

A pattern that I sometimes want in Clojure is to implement the same function for multiple types (defined by either defrecord or deftype). A simple way to do this is to do the work in an external function, and then have every implementation call it.

For instance, say I want to get a list of feet from several animal types. I can create a protocol for this, with the function get-feet:

(defprotocol Footed
  (get-feet [animal] "Get a sequence of feet"))

Then, I may have a few different groups of animals, each sharing a number of feet. I can create a function for each of these groups:

(defn get-2-feet [] [:left :right])

(defn get-4-feet [] [:front-left :front-right
                     :back-left :back-right])

(defn get-6-feet [] [:front-left :front-right
                     :middle-left :middle-right
                     :back-left :back-right])

Then the different record types will call the function they need:

(defrecord Ape [name]
  Footed
  (get-feet [_] (get-2-feet)))

(defrecord Bird [name]
  Footed
  (get-feet [_] (get-2-feet)))

(defrecord Cat [name]
  Footed
  (get-feet [_] (get-4-feet)))

(defrecord Ant [name]
  Footed
  (get-feet [_] (get-6-feet)))

…and so on.

This works, but it is very unsatisfying. It also gets noisy if the protocol has more than one function.

Instead, it would be nice if we could implement the protocol once, and then inherit this in any type that needs that implementation. Clojure doesn't support inheritance like this, but it has something close.

Protocols

A Protocol in Clojure is a set of functions that an object has agreed to support. The language and compiler have special dispatch support around protocols, making their functions fast and easy to call. While many people know the specifics of protocols, this often comes about through exploration rather than documentation. I won't go into an exhaustive discussion of protocols here, but I will mention a couple of important aspects.

Whenever a protocol is created in Clojure, two things are created: the protocol itself, and a plain-old Java Interface. (ClojureScript also has protocols, but they don't create interfaces). The protocol is just a normal data structure, which we can see at a repl:

user=>  (defprotocol Footed
  (get-feet [animal] "Get a sequence of feet"))
Footed
user=> Footed
{:on user.Footed,
 :on-interface user.Footed,
 :sigs {:get-feet {:tag nil, :name get-feet, :arglists ([animal]), :doc "Get a sequence of feet"}},
 :var #'user/Footed,
 :method-map {:get-feet :get-feet},
 :method-builders {#'user/get-feet #object[user$eval143$fn__144 0x67001148 "user$eval143$fn__144@67001148"]}}

This describes the protocol, and each of the associated functions. This is also the structure that gets modified by some of the various protocol extension macros. You may see how the :method-map refers to functions by their name, rewritten as a keywords.

Of interest here is the reference to the interface user.Footed. I'm using a repl with the default user namespace. Because we are already in this namespace, that Footed interface name is being shadowed by the protocol object. But it is still there, and we can still do things with it.

Common Operations

Protocols are often "extended" onto new datatypes. This is a very flexible operation, and allows new behavior to be associated with any datatype, including those not declared in Clojure (for instance, new behavior could be added to a java.util.String). This applies to Interfaces as well as Classes, which is something we can use here.

First of all, we want a new protocol/interface for each type of behavior that we want:

(defprotocol Feet2)
(defprotocol Feet4)
(defprotocol Feet6)

These protocols don't need functions, as they just serve to "mark" the objects that want to implement the desired behavior.

Next, we can extend the protocol with our functions onto the types described by each of these Interfaces:

(extend-protocol Footed
user.Feet2
(get-feet [_] [:left :right])
user.Feet4
(get-feet [_] [:front-left :front-right :back-left :back-right])
user.Feet6
(get-feet [_] [:front-left :front-right :middle-left :middle-right :back-left :back-right]))

Going back to the Footed protocol, we can see that it now knows about these implementations.

user=> Footed
{:on user.Footed,
 :on-interface user.Footed,
 :sigs {:get-feet {:tag nil, :name get-feet, :arglists ([animal]), :doc "Get a sequence of feet"}},
 :var #'user/Footed,
 :method-map {:get-feet :get-feet},
 :method-builders {#'user/get-feet #object[user$eval143$fn__144 0x67001148 "user$eval143$fn__144@67001148"]},
 :impls {
    user.Feet2 {:get-feet #object[user$eval195$fn__196 0x24fabd0f "user$eval195$fn__196@24fabd0f"]},
    user.Feet4 {:get-feet #object[user$eval199$fn__200 0x250b236d "user$eval199$fn__200@250b236d"]},
    user.Feet6 {:get-feet #object[user$eval203$fn__204 0x61f3fbb8 "user$eval203$fn__204@61f3fbb8"]}}}

Note how the :impls value now maps each of the extended interfaces to the attached functions.

A Comment on Identifiers

You might have noticed that I had to use the fully-qualified name for these interfaces due to the protocol name shadowing them. When a protocol is not in the same namespace, then it can be required, and referenced by its namespace, while the Interface can be imported from that namespace. For instance, a project that I've been working on recently has require/imports of:

(ns my.project
 (:require [quoll.rdf :as rdf])
 (:import [quoll.rdf IRI]))

In this example I am able to reference the protocol via rdf/IRI while the interface is just IRI.

Attaching

Now that the Footed protocol has been extended to each of these interfaces, the protocols associated with those interfaces can be attached to any type that wants that behavior.

Going back to our animals, we can do the same thing again, but this time without the stub functions that redirect to the common functionality:

(defrecord Ape [name] Feet2)
(defrecord Bird [name] Feet2)
(defrecord Cat [name] Feet4)
(defrecord Ant [name] Feet6)

Instances of these types will now pick up the implementations extended to these marker protocols:

(def magilla (Ape. "Magilla"))
(def big-bird (Bird. "Big"))
(def garfield (Cat. "Garfield"))
(def atom-ant (Ant. "Atom"))

user=> (get-feet magilla)
[:left :right]
user=> (get-feet big-bird)
[:left :right]
user=> (get-feet garfield)
[:front-left :front-right :back-left :back-right]
user=> (get-feet atom-ant)
[:front-left :front-right :middle-left :middle-right :back-left :back-right]

Final Declarations

After explaining so much of the mechanism, the code has been scattered widely across this post. Putting the declarations together, we have:

(defprotocol Footed (get-feet [_]))
(defprotocol Feet2)
(defprotocol Feet4)
(defprotocol Feet6)

(extend-protocol Footed
 user.Feet2
 (get-feet [_] [:left :right])
 user.Feet4
 (get-feet [_] [:front-left :front-right :back-left :back-right])
 user.Feet6
 (get-feet [_] [:front-left :front-right :middle-left :middle-right  :back-left :back-right]))

(defrecord Ape [name] Feet2)
(defrecord Bird [name] Feet2)
(defrecord Cat [name] Feet4)
(defrecord Ant [name] Feet6)

Wrap Up

Functional programming in Clojure is not generally served by having multiple types like this, but it does happen. While this is a trivial example, with only a single function on the protocol, the need for this pattern becomes apparent when protocols come with multiple functions.

I've called it inheritance, but that is only an analogy. It's not actually inheritance that we are applying here, but it does behave in a similar way.

Permalink

core.async and Virtual Threads

Permalink

How to start a Polylith project from scratch

A complete step-by-step guide to creating project called cat (or workspace, in Polylith terms) with a filesystem component, a main base, and a cli project using the Polylith architecture.

What You Will Build

cat/                          ← workspace root
├── components/
│   └── filesystem/              ← reads a file and prints its content
├── bases/
│   └── main/                 ← entry point (-main function)
└── projects/
    └── cli/                  ← deployable artifact (uberjar)

Data flow: java -jar cli.jar myfile.txt → main/-main → filesystem/read-file → stdout

Prerequisites

Install the following before starting:

• Java 21+ — verify with java -version
• Clojure CLI — install from clojure.org/guides/getting_started, verify with clojure --version
• git — verify with git --version; also configure user.name and user.email:

  git config --global user.name "Your Name"
  git config --global user.email "you@example.com"
  

• poly tool — see below

Installing the poly tool

macOS:

brew install polyfy/polylith/poly

For other OS/platforms please refer to the official Installation doc.

Verify:

poly version

Step 1 — Create the Workspace

Run this outside any existing git repository:

poly create workspace name:cat top-ns:com.acme :commit

Move into the workspace:

cd cat

Your directory structure will look like:

cat/
├── .git/
├── .gitignore
├── bases/
├── components/
├── deps.edn
├── development/
│   └── src/
├── projects/
├── readme.md
└── workspace.edn

Enable auto-add in workspace.edn

Open workspace.edn and set :auto-add to true so that files generated by poly create commands are automatically staged in git:

{:top-namespace "com.acme"
 :interface-ns "interface"
 :default-profile-name "default"
 :dialects ["clj"]
 :compact-views #{}
 :vcs {:name "git"
       :auto-add true}       ;; <-- change this to true
 :tag-patterns {:stable "^stable-.*"
                :release "^v[0-9].*"}
 :template-data {:clojure-ver "1.12.0"}
 :projects {"development" {:alias "dev"}}}

Step 2 — Create the filesystem Component

poly create component name:filesystem

This creates:

components/filesystem/
├── deps.edn
├── src/
│   └── com/acme/filesystem/
│       └── interface.clj
└── test/
    └── com/acme/filesystem/
        └── interface_test.clj

2a. Write the interface (public API)

The interface namespace is the only file other bricks are allowed to call. Edit components/filesystem/src/com/acme/filesystem/interface.clj:

(ns com.acme.filesystem.interface
  (:require [com.acme.filesystem.core :as core]))

(defn read-file
  "Reads the file at `filename` and prints its content to stdout."
  [filename]
  (core/read-file filename))

2b. Write the implementation

Create the file components/filesystem/src/com/acme/filesystem/core.clj:

(ns com.acme.filesystem.core
  (:require [clojure.java.io :as io]))

(defn read-file
  "Reads the file at `filename` and prints its content to stdout."
  [filename]
  (let [file (io/file filename)]
    (if (.exists file)
      (println (slurp file))
      (println (str "Error: file not found — " filename)))))

2c. Register the component in the root deps.edn

Open the root ./deps.edn and add the filesystem component:

{:aliases {:dev {:extra-paths ["development/src"]
                 :extra-deps  {com.acme/filesystem {:local/root "components/filesystem"}
                               org.clojure/clojure {:mvn/version "1.12.0"}}}

           :test {:extra-paths ["components/filesystem/test"]}

           :poly {:main-opts ["-m" "polylith.clj.core.poly-cli.core"]
                  :extra-deps {polyfy/clj-poly {:mvn/version "0.3.32"}}}}}

Step 3 — Create the main Base

poly create base name:main

This creates:

bases/main/
├── deps.edn
├── src/
│   └── com/acme/main/
│       └── core.clj
└── test/
    └── com/acme/main/
        └── core_test.clj

3a. Write the base code

A base differs from a component in that it has no interface — it is the entry point to the outside world. Edit bases/main/src/com/acme/main/core.clj:

(ns com.acme.main.core
  (:require [com.acme.filesystem.interface :as filesystem])
  (:gen-class))

(defn -main
  "Entry point. Accepts a filename as the first argument and prints its content."
  [& args]
  (if-let [filename (first args)]
    (filesystem/read-file filename)
    (println "Usage: cat <filename>"))
  (System/exit 0))

Key points:

• (:gen-class) tells the Clojure compiler to generate a Java class with a main method.
• The base calls com.acme.filesystem.interface/read-file — never the core namespace directly.
• System/exit 0 ensures the JVM terminates cleanly after running.

3b. Register the base in the root deps.edn

Add the main base alongside filesystem:

{:aliases {:dev {:extra-paths ["development/src"]
                 :extra-deps  {com.acme/filesystem {:local/root "components/filesystem"}
                               com.acme/main    {:local/root "bases/main"}
                               org.clojure/clojure {:mvn/version "1.12.0"}}}

           :test {:extra-paths ["components/filesystem/test"
                                "bases/main/test"]}

           :poly {:main-opts ["-m" "polylith.clj.core.poly-cli.core"]
                  :extra-deps {polyfy/clj-poly {:mvn/version "0.3.32"}}}}}

Step 4 — Create the cli Project

poly create project name:cli

This creates:

projects/cli/
└── deps.edn

4a. Register the project alias in workspace.edn

Open workspace.edn and add a cli alias to :projects:

:projects {"development" {:alias "dev"}
           "cli"         {:alias "cli"}}

4b. Wire the bricks into the project

Edit projects/cli/deps.edn to include the filesystem component, the main base, the uberjar entry point, and the build alias:

{:deps {com.acme/filesystem {:local/root "components/filesystem"}
        com.acme/main    {:local/root "bases/main"}
        org.clojure/clojure {:mvn/version "1.12.0"}}

 :aliases {:test    {:extra-paths []
                     :extra-deps  {}}

           :uberjar {:main com.acme.main.core}}}

Step 5 — Add Build Support

The poly tool does not include a build command — it leaves artifact creation to your choice of tooling. We will use Clojure tools.build.

5a. Add the :build alias to the root deps.edn

Your final root ./deps.edn should look like this:

{:aliases {:dev {:extra-paths ["development/src"]
                 :extra-deps  {com.acme/filesystem {:local/root "components/filesystem"}
                               com.acme/main    {:local/root "bases/main"}
                               org.clojure/clojure {:mvn/version "1.12.0"}}}

           :test {:extra-paths ["components/filesystem/test"
                                "bases/main/test"]}

           :poly {:main-opts ["-m" "polylith.clj.core.poly-cli.core"]
                  :extra-deps {polyfy/clj-poly {:mvn/version "0.3.32"}}}

           :build {:deps {io.github.clojure/tools.build {:mvn/version "0.9.6"}}
                   :ns-default build}}}

5b. Create build.clj at the workspace root

Create the file build.clj under the workspace root:

(ns build
  (:require [clojure.tools.build.api :as b]
            [clojure.java.io :as io]))

(defn uberjar
  "Build an uberjar for a given project.
   Usage: clojure -T:build uberjar :project cli"
  [{:keys [project]}]
  (assert project "You must supply a :project name, e.g. :project cli")
  (let [project     (name project)
        project-dir (str "projects/" project)
        class-dir   (str project-dir "/target/classes")
        ;; Create the basis from the project's deps.edn.
        ;; tools.build resolves :local/root entries and collects all
        ;; transitive :paths (i.e. each brick's "src" and "resources").
        basis       (b/create-basis {:project (str project-dir "/deps.edn")})
        ;; Collect every source directory declared across all bricks.
        ;; basis :classpath-roots contains the resolved paths.
        src-dirs    (filterv #(.isDirectory (java.io.File. %))
                             (:classpath-roots basis))
        main-ns     (get-in basis [:aliases :uberjar :main])
        _           (assert main-ns
                             (str "Add ':uberjar {:main <ns>}' alias to "
                                  project-dir "/deps.edn"))
        jar-file    (str project-dir "/target/" project ".jar")]
    (println (str "Cleaning " class-dir "..."))
    (b/delete {:path class-dir})
    (io/make-parents jar-file)
    (println (str "Compiling " main-ns "..."))
    (b/compile-clj {:basis     basis
                    :src-dirs  src-dirs
                    :class-dir class-dir})
    (println (str "Building uberjar " jar-file "..."))
    (b/uber {:class-dir class-dir
             :uber-file jar-file
             :basis     basis
             :main      main-ns})
    (println "Uberjar is built.")))

Step 6 — Validate the Workspace

Run the poly info command to see the current state of your workspace:

poly info

You should see both bricks (filesystem and main) listed, along with the cli project. Then validate the workspace integrity:

poly check

This should print OK. If there are errors, the command will describe what to fix.

Step 7 — Build the Uberjar

From the workspace root:

clojure -T:build uberjar :project cli

Expected output:

Compiling com.acme.main.core...
Building uberjar projects/cli/target/cli.jar...
Uberjar is built.

Step 8 — Run the CLI

Create a test file and run the app:

echo "Hello from Polylith!" > /tmp/hello.txt
java -jar projects/cli/target/cli.jar /tmp/hello.txt

Expected output:

Hello from Polylith!

Test the missing-file error path:

java -jar projects/cli/target/cli.jar /tmp/nonexistent.txt

Expected output:

Error: file not found — /tmp/nonexistent.txt

Test the no-argument path:

java -jar projects/cli/target/cli.jar

Expected output:

Usage: cat <filename>

Final Workspace Layout

cat/
├── bases/
│   └── main/
│       ├── deps.edn
│       └── src/com/acme/main/
│           └── core.clj              ← -main, calls filesystem/read-file
├── components/
│   └── filesystem/
│       ├── deps.edn
│       └── src/com/acme/filesystem/
│           ├── interface.clj         ← public API (read-file)
│           └── core.clj              ← implementation
├── projects/
│   └── cli/
│       ├── deps.edn                  ← wires filesystem + main, :uberjar alias
│       └── target/
│           └── cli.jar               ← generated artifact
├── build.clj                         ← tools.build script
├── deps.edn                          ← dev + test + poly + build aliases
└── workspace.edn                     ← top-ns, project aliases, vcs config

Key Concepts Summary

• Workspace is the monorepo root containing all bricks, in this project is cat/
• Component is a reusable building block with a public interface ns, such as filesystem
• Base is an entry-point brick that bridges the outside world to components, like main
• Project is a deployable artifact configuration; assembles bricks, the cli
• Interface is the only namespace other bricks may import from a component, like com.acme.filesystem.interface

Useful poly Commands

poly info          # overview of bricks and projects
poly check         # validate workspace integrity
poly test          # run all tests affected by recent changes
poly deps          # show dependency graph
poly libs          # show library usage
poly shell         # interactive shell with autocomplete

Going Further

• Add more components — e.g. poly create component name:parser for argument parsing
• Add tests — on a component level, add tests against the interface and not the implementation. You can have additional tests for the implementation to test internal functions etc. but use a different test file.
• Tag stable releases — git tag stable-main after a clean poly test
• CI integration — run poly check and poly test in your pipeline; tag as stable on success
• Multiple projects — add another project that reuses the same components
• Visit the official Polylith project documentation
• Read the Polylith book
• Ask questions and connect with other Polylith users on #polylith Slack channel.

Permalink

Simple over easy for operations

Building a workflow engine for infrastructure operations is not trivial. Most people start with a simple mental model: a desired state and a sequence of functions that produce side effects. In Clojure, this looks like a simple thread-first macro:

(-> {}
    fn1
    fn2
    ...)

Your state {} is threaded through fn1 and fn2. However, real-world operations are rarely linear. They require complex branching, error handling, and conditional jumps (e.g., “if success, continue; otherwise, jump to cleanup”).

To handle non-linear flows, we associate functions with qualified keywords (steps). Together with the next step, they form the “wiring”. You can override sequential execution by providing a next-fn to handle custom branching.

The core execution loop looks like this:

(loop [step first-step
       opts opts]
  (let [[f next-step] (wire-fn step step-fns)
        new-opts (f opts)
        [next-step next-opts] (next-fn step next-step new-opts)]
    (if next-step
      (recur next-step next-opts)
      next-opts)))

Here is how we use this engine to create a client-side lock for Terraform using Git tags. The opts map represents our “World State”, shared across all functions.

We invoke it like this: (lock [] {}). The first argument is a list of middleware-style step functions, and the second is the starting state.

(->workflow {:first-step ::generate-lock-id
             :wire-fn (fn [step _]
                        (case step
                          ::generate-lock-id [generate-lock-id ::delete-tag]
                          ::delete-tag [delete-tag ::create-tag]
                          ::create-tag [create-tag ::push-tag]
                          ::push-tag [push-tag ::get-remote-tag]
                          ::get-remote-tag [(comp get-remote-tag delete-tag) ::read-tag]
                          ::read-tag [read-tag ::check-tag]
                          ::check-tag [check-tag ::end]
                          ::end [identity]))
             :next-fn (fn [step next-step opts]
                        (case step
                          ::end [nil opts]
                          ::push-tag (choice {:on-success ::end
                                              :on-failure next-step
                                              :opts opts})
                          ::delete-tag [next-step opts]
                          (choice {:on-success next-step
                                   :on-failure ::end
                                   :opts opts})))})

In many CI/CD systems, debugging is a nightmare of “print” statements and re-running 10-minute pipelines. Because Clojure data structures are immutable and persistent, we can use a debug macro provided by BigConfig and a “spy” function to inspect the state at every step.

(comment
  (debug tap-values
    (create [(fn [f step opts]
               (tap> [step opts]) ;; "Spy" on every state change
               (f step opts))]
            {::bc/env :repl
             ::tools/tofu-opts (workflow/parse-args "render")
             ::tools/ansible-opts (workflow/parse-args "render")})))

Using tap>, you get the result “frozen in time”. You can render templates and inspect them without ever executing a side effect.

Operations often require calling the same sub-workflow multiple times. If every workflow uses the same top-level keys, they clash. We solve this with Nested Options.

By using the workflow’s namespace as a key, we isolate state. However, sometimes a child needs data from a sibling (e.g., Ansible needs an IP address generated by Terraform). We use an opts-fn to map these values explicitly at runtime.

The specialized ->workflow* constructor uses this next-fn to manage this state isolation:

(fn [step next-step {:keys [::bc/exit] :as opts}]
  (if (steps-set step)
    (do
      (swap! opts* merge (select-keys opts [::bc/exit ::bc/err]))
      (swap! opts* assoc step opts))
    (reset! opts* opts))
  (cond
    (= step ::end) [nil @opts*]
    (> exit 0)     [::end @opts*] ;; Error handling jump
    :else
    [next-step (let [[new-opts opts-fn]
                     (get step->opts-and-opts-fn next-step [@opts* identity])]
                 (opts-fn new-opts))]))

This logic ensures that if a step is a sub-workflow, its internal state is captured within the parent’s state under its own key. The opts-fn allows us to bridge the gap—for instance, pulling a Terraform-generated IP address into the Ansible configuration dynamically.

In operations, you must render configuration files before invoking tools. If you compose multiple workflows, you run into the “Maven Diamond Problem”: two different parent workflows sharing the same sub-workflow. To prevent them from overwriting each other’s files, we use dynamic, hashed prefixes for working directories:

.dist/default-f704ed4d/io/github/amiorin/alice/tools/ansible

The hash f704ed4d is dynamic. If a workflow is moved or re-composed, the hash changes, ensuring total isolation during template rendering.

Tools like AWS Step Functions , Temporal , or Restate are powerful workflow engines, but for many operational tasks, they are not a good fit. BigConfig has an edge because it is local and synchronous where it counts. It turns infrastructure into a local control loop orchestrating multiple tools.

In the industry, “Easy” (using the same language as the backend, like Go) often wins over “Simple”. But Go lacks a REPL, immutable data structures, and the ability to implement a debug macro that allows for instantaneous feedback.

Infrastructure eventually becomes a mess of “duct tape and prayers” when the underlying tools aren’t built for complexity. If you choose Simple over Easy, Clojure is the best language for operations—even if you’re learning Clojure for the first time.

Would you like to have a follow-up on this topic? What are your thoughts? I’d love to hear your experiences.

Permalink

Clojure Deref (Mar 10, 2026)

Permalink

Just What IS Clojure, Anyway?

Look at this line of code:

processCustomerOrder(customer, orderItems)

Any developer with six months of experience knows roughly what that does. The name is explicit, the structure is familiar, the intent is readable. Now look at this:

(reduce + (map f xs))

The reaction most developers have is immediate and unfavourable. Parentheses everywhere. No obvious structure. It looks less like a programming language and more like a typographer's accident. The old joke writes itself: LISP stands for Lost In Stupid Parentheses.

That joke is, technically, a backronym. John McCarthy named it LISP as a contraction of LISt Processing when he created it in 1958. The sardonic expansion came later, coined by programmers who had opinions about the aesthetic choices involved. Those opinions have not mellowed with time.

And yet Clojure – a modern descendant of Lisp – ranked as one of the highest-paying languages in the Stack Overflow Developer Survey for several consecutive years around 2019. Developers walked away from stable Java and C# positions to build production systems in it. A Brazilian fintech used it to serve tens of millions of customers. Something requires explaining.

The ancestry: Lisp reborn

Clojure only makes sense against the background of Lisp, and Lisp only makes sense as what it actually was: not merely a programming language, but a direct implementation of mathematical ideas about computation.

McCarthy's 1958 creation introduced concepts that took the rest of the industry decades to absorb. Garbage collection, conditional expressions, functional programming, symbolic computation – all present in Lisp before most working developers today were born. Many programmers encounter Lisp's descendants daily without being aware of it.

The defining feature is the S-expression:

(+ 1 2)

Everything is written as a list. This is not merely a syntactic preference. Because code and data share the same underlying structure, a Lisp program can manipulate other programs directly. This property – homoiconicity – is the technical foundation of Lisp macros: code that generates and transforms other code at compile time, with a flexibility that few conventional infix languages match. It is the reason serious Lisp practitioners regard the syntax not as a historical curiosity but as a genuine technical advantage.

Lisp also, however, developed a reputation for producing work that individual experts could write brilliantly and teams could not maintain at all. The tension between expressive power and collective readability never fully resolved. Clojure inherits this tradition knowingly, and is aware of the cost.

What Clojure actually is

Rich Hickey created Clojure in 2007. His central design decision was not to build a new runtime from scratch but to attach Lisp to an existing ecosystem.

This host strategy gave Clojure immediate access to decades of mature Java libraries without needing to rebuild any of them. A Clojure developer can call Java code directly. The same logic drove two later variants: ClojureScript, which compiles to JavaScript and found real traction in teams already working with React, and ClojureCLR, which runs on .NET. Rather than fight the unwinnable battle of building its own ecosystem from scratch, Clojure attached itself to three of the largest ones that already existed.

Clojure does not attempt to displace existing ecosystems. It operates inside them.

Central to how Clojure development actually works is the REPL – Read–Eval–Print Loop. Rather than the standard write–compile–run–crash cycle, developers send code fragments to a running system and modify it live. Functions are redefined while the application continues executing. For experienced practitioners this is a material productivity difference: the feedback loop is short, and the distance between an idea and a tested result is small. Experienced Clojure developers report unusually low defect rates, a claim that is plausible given the constraints immutability places on the ways a programme can fail.

The Hickey doctrine: simple versus easy

Hickey's 2011 Strange Loop talk Simple Made Easy is the philosophical engine behind every design choice in Clojure. It draws a distinction that most language design ignores.

Most languages pursue easy. They aim to resemble natural language, minimise cognitive friction at the point of learning, and reduce the effort required to write the first working programme. This also means that languages favoured by human readers tend to be the hardest for which to write parsers and compilers.

Clojure instead pursues simple. Its goal is to minimise tangled interdependencies in the resulting system, even at the cost of an unfamiliar surface. Writing parsers for Lisps is comparatively straightforward, at the cost of human readability.

Hickey's specific target is what he calls place-oriented programming: the treatment of variables as named locations in memory whose values change over time – mutability, in more formal terms. His argument is that conflating a value with a location generates incidental complexity at scale, particularly in concurrent systems. When you cannot be certain what a variable contains at a given moment, reasoning about a programme becomes difficult in proportion to the programme's size.

The design of Clojure follows directly from this diagnosis. Immutable data, functional composition, minimal syntax, and data structures in place of object hierarchies are all consequences of the same underlying position. The language may not feel easy. The resulting systems are intended to be genuinely simpler to reason about.

The real innovation: data and immutability

Clojure's core model is data-oriented. Rather than building class hierarchies, programmes pass simple structures through functions:

(assoc {:name "Alice" :age 30} :city "London")

This creates a new map. The original is untouched. That is the default behaviour across all of Clojure's data structures – values do not change; new versions are produced instead.

This is made practical by persistent data structures, which use structural sharing. When a new version of a data structure is produced, it shares most of its internal memory with the previous version rather than copying it entirely. The comparison that makes this intuitive for most developers: Git does not delete your previous commits when you push a new one. It stores only the difference, referencing unchanged content from before. Clojure applies the same principle to in-memory data.

The consequence for concurrency results directly from this. Race conditions require mutable shared state. If data cannot be mutated, the precondition for the most common class of concurrency bug does not exist. This was Clojure's most compelling practical argument during the multicore boom of the 2010s, when writing correct concurrent code had become a routine industrial concern rather than a specialist one. Clojure let developers eliminate that entire class of problem.

The functional programming wave – and why easy beat rigorous

Between roughly 2012 and 2020, functional programming moved from academic discussion to genuine industry interest. The drivers were concrete: multicore processors created pressure to write concurrent code correctly; distributed data systems required reasoning about transformation pipelines rather than mutable state; and the sheer complexity of large-scale software made the promise of mathematical rigour appealing.

Clojure was among the most visible representatives of this movement, alongside Haskell, Scala, and F#. Conference talks filled. Engineering blogs ran long series on immutability and monads. For a period it seemed plausible that functional languages might displace the mainstream ones.

What actually happened was different. Mainstream languages absorbed the useful ideas and continued. And the majority of working programmers, it turned out, rarely needed to reason about threading and concurrency at all.

Java gained streams and lambdas in Java 8. JavaScript acquired map, filter, and reduce as first-class patterns, and React popularised unidirectional data flow. C# extended its functional capabilities across successive versions. Rust built immutability and ownership into its type system from the outset. The industry did not convert to functional programming – it extracted what it needed and kept the syntax it already knew.

A developer who can obtain most of functional programming's benefits inside a language they already know will rarely conclude that switching entirely is justified.

The deeper reason functional languages lost the mainstream argument is not technical. It is sociological. Python won because it is, in the most precise sense, the Visual Basic of the current era. That comparison is not an insult – Visual Basic dominated the 1990s because it made programming accessible to people who had no intention of becoming professional developers, and that accessibility produced an enormous, self-reinforcing community. Python did exactly the same thing for data scientists, academics, hobbyists, and beginners, and for precisely the same reason: it is easy to learn, forgiving of error, and immediately rewarding to write. Network effects took care of the rest. Libraries multiplied. Courses proliferated. Employers specified it. The ecosystem became self-sustaining.

Clojure is the antithesis of this process. It is a language for connoisseurs – genuinely, not dismissively. Its internal consistency is elegant, its theoretical foundations are sound, and developers who master it frequently describe it with something approaching aesthetic appreciation. Mathematical beauty, however, has never been a reliable route to mass adoption. Narrow appeal does not generate network effects. And Clojure, by design, operates as something of a lone wolf: it rides atop the JVM rather than integrating natively with the broader currents of modern computing – the web-first tooling, the AI infrastructure, the vast collaborative ecosystems built around Python and JavaScript. At a moment when the decisive advantages in software development come from connectivity, interoperability, and the accumulated weight of shared tooling, a language that demands a clean break from everything a developer already knows is swimming directly against the tide.

Compare this with Kotlin or TypeScript, both of which succeeded in part because they offered a graduated path. A developer new to Kotlin can write essentially Java-style code and improve incrementally. A developer new to TypeScript can begin with plain JavaScript and add types as confidence grows. Both languages have, in effect, a beginner mode. Clojure has no such thing. You either think in Lisp or you do not write Clojure at all.

Where Clojure succeeded

Despite remaining a specialist language, Clojure has real industrial presence.

The most prominent example is Nubank, a Brazilian fintech that reached a valuation of approximately $45 billion at its NYSE listing in December 2021. Nubank runs significant portions of its backend in Clojure, and in 2020 acquired Cognitect – the company that stewards the language. That acquisition was considerably more than a gesture; it was a statement of long-term commitment from an organisation operating at scale.

ClojureScript found parallel influence in the JavaScript ecosystem. The Reagent and re-frame frameworks attracted serious production use, demonstrating that the Clojure model could be applied to front-end development at scale and not merely to backend data pipelines.

The pattern that emerges from successful Clojure deployments is consistent: small, experienced teams working on data-intensive systems where correctness and concurrency matter more than onboarding speed. That is a narrow niche. It was also, not coincidentally, a well-paid one – for a time.

Verdict: the ideas won

Clojure did not become a mainstream language. By any measure of adoption – survey rankings, job advertisements, GitHub repositories – it remains firmly in specialist territory. Even F#, a functional rival with the full weight of Microsoft's backing, has not broken through.

But the argument Clojure made in 2007 has largely been vindicated. Immutability is now a design principle in Rust, Swift, and Kotlin. Functional composition is standard across modern JavaScript and C#. Data-oriented design has become an explicit architectural pattern in game development and systems programming. The industry did not adopt Clojure, but it has been grateful for Hickey's ideas and has quietly absorbed them.

What did not transfer was the syntax – and behind the syntax lay an economic problem that no philosophical vindication could resolve.

A CTO evaluating a language does not ask only whether it is technically sound. The questions are: how large is the available talent pool? How long does onboarding take? What happens when a key developer leaves? Clojure's answers to all three were uncomfortable.

There is a further cost that rarely appears in language comparisons. A developer with ten years of experience in Java, C#, or Python carries genuine accumulated capital: hard-won familiarity with idioms, libraries, failure modes, and tooling. Switching to a Lisp-derived language does not extend that knowledge – it resets it. Clojure keeps the JVM underneath but discards almost everything a developer has learned about how to structure solutions idiomatically. The ten-year veteran spends their first six months feeling like a junior again. Recursion replaces loops. Immutable pipelines replace stateful objects. The mental models that took years to build are, at best, partially transferable. That cost is real and largely invisible in adoption discussions, and it falls on precisely the experienced developers an organisation most wants to retain. Knowledge compounds most effectively when it is built upon incrementally. Clojure does not permit that. It demands a clean break, and most organisations and most developers are not willing to pay that price.

The high wages Clojure commanded were not, from a management perspective, a straightforward mark of quality. They were also a warning of risk. They reflected something less flattering than productivity: the classic dynamic of the expert who becomes indispensable by writing systems that only they can maintain. At its worst this approaches a form of institutional capture – a codebase so entangled with one person's idiom that replacing them becomes prohibitively expensive, something uncomfortably close to ransomware in its commercial effect.

That position has been further undermined by the rise of agentic coding tools. The practical value of writing in a mainstream language has quietly increased, because AI coding assistants are trained on the accumulated body of code that exists – and that body is overwhelmingly Python, JavaScript, Java, and C#. The effect is concrete: ask a capable model to produce a complex data transformation in Python and it draws on an enormous foundation of high-quality examples. Ask it to do the same in idiomatic Clojure and the results are less reliable, the suggestions thinner, the tooling shallower. A language's effective learnability in 2026 is no longer a matter only of human cognition; it is also a function of training density. Niche languages are niche in the training data too, and that gap compounds. The expert moat – already questionable on organisational grounds – is being drained from two directions at once.

Clojure's ideas spread quietly through the languages that absorbed them and left the parentheses behind. Its practitioners, once among the best-paid developers in the industry, now find that the scarcity premium they commanded rested partly on barriers that no longer hold.

The language was right about the future of programming. It simply will not be present when that future arrives.

So, just what is Clojure, anyway? It is a language that was correct about the most important questions in software design, arrived a decade before the industry was ready to hear the answers, and expressed those answers in a notation the industry was never willing to learn. That is not a small thing. It is also not enough.

This article is part of an ongoing series examining what programming languages actually are and why they matter.

Coming next: Zig, Odin, and Nim – three languages that think C's job could be done better, and have very different ideas about how.

Permalink

Quarto Escuro de Goethe in Lisbon

Two days of performance for the premiere of Quarto Escuro de Goethe in Lisbon.

Permalink

Week Notes 2026.10

Exploring the Vanta API with Clojure, Late Night Linux family of podcasts.

Permalink

Wrapper’s in Clojure Ring

Notes

• Code

Permalink

OSS updates January and February 2026

In this post I&aposll give updates about open source I worked on during January and February 2026.

To see previous OSS updates, go here.

Sponsors

I&aposd like to thank all the sponsors and contributors that make this work possible. Without you, the below projects would not be as mature or wouldn&apost exist or be maintained at all! So a sincere thank you to everyone who contributes to the sustainability of these projects.

Current top tier sponsors:

• Clojurists Together
• Roam Research
• Nextjournal
• Nubank

Open the details section for more info about sponsoring.

Sponsor info

If you want to ensure that the projects I work on are sustainably maintained, you can sponsor this work in the following ways. Thank you!

• Github Sponsors
• The Babashka or Clj-kondo OpenCollective
• Ko-fi
• Patreon
• Clojurists Together

Updates

Babashka conf and Dutch Clojure Days 2026

Babashka Conf 2026 is happening on May 8th in the OBA Oosterdok library in Amsterdam! David Nolen, primary maintainer of ClojureScript, will be our keynote speaker! We&aposre excited to have Nubank, Exoscale, Bob and Itonomi as sponsors. Wendy Randolph will be our event host / MC / speaker liaison :-). The CfP is now closed. More information here. Get your ticket via Meetup.com (there is a waiting list, but more places may become available). The day after babashka conf, Dutch Clojure Days 2026 will be happening, so you can enjoy a whole weekend of Clojure in Amsterdam. Hope to see many of you there!

Projects

I spent a lot of time making SCI&aposs deftype, case, and macroexpand-1 match JVM Clojure more closely. As a result, libraries like riddley, cloverage, specter, editscript, and compliment now work in babashka.

After seeing charm.clj, a terminal UI library, I decided to incorporate JLine3 into babashka so people can build terminal UIs. Since I had JLine anyway, I also gave babashka&aposs console REPL a major upgrade with multi-line editing, tab completion, ghost text, and persistent history. A next goal is to run rebel-readline + nREPL from source in babashka, but that&aposs still work in progress (e.g. the compliment PR is still pending).

I&aposve been working on async/await support for ClojureScript (CLJS-3470), inspired by how squint handles it. I also implemented it in SCI (scittle, nbb etc. use SCI as a library), though the approach there is different since SCI is an interpreter.

Last but not least, I started cream, an experimental native binary that runs full JVM Clojure with fast startup using GraalVM&aposs Crema. Unlike babashka, it supports runtime bytecode generation (definterface, deftype, gen-class). It currently depends on a fork of Clojure and GraalVM EA, so it&aposs not production-ready yet.

Here are updates about the projects/libraries I&aposve worked on in the last two months in detail.

• NEW: cream: Clojure + GraalVM Crema native binary

  • A native binary that runs full JVM Clojure with fast startup, using GraalVM&aposs Crema (RuntimeClassLoading) to enable runtime eval, require, and library loading
  • Unlike babashka, supports definterface, deftype, gen-class, and other constructs that generate JVM bytecode at runtime
  • Can run .java source files directly, as a fast alternative to JBang
  • Cross-platform: Linux, macOS, Windows

• babashka: native, fast starting Clojure interpreter for scripting.

  • Released 1.12.214 and 1.12.215
  • #1909: add JLine3 for TUI support
  • Console REPL (bb repl) improvements: multi-line editing, tab completion, ghost text, eldoc, doc-at-point (C-x C-d), persistent history
  • Support deftype with map interfaces (e.g. IPersistentMap, ILookup, Associative). Libraries like core.cache and linked now work in babashka.
  • Compatibility with riddley, cloverage, editscript, charm.clj
  • #1299: add new babashka.terminal namespace that exposes tty?
  • Add keyword completions to nREPL and console REPL
  • deftype supports Object + hashCode
  • #1923: support reify with java.time.temporal.TemporalQuery
  • Fix reify with methods returning int/short/byte/float
  • Full changelog

• SCI: Configurable Clojure/Script interpreter suitable for scripting

  • Released 0.12.51
  • deftype now macroexpands to deftype*, matching JVM Clojure, enabling code walkers like riddley
  • case now macroexpands to JVM-compatible case* format, enabling tools like riddley and cloverage
  • Support async/await in ClojureScript. See docs.
  • Support functional interface adaptation for instance targets
  • Infer type tags from let binding values to binding names
  • defrecord now expands to deftype* (like Clojure), with factory fns emitted directly in the macro expansion
  • macroexpand-1 now accepts an optional env map as first argument
  • Add proxy-super, proxy-call-with-super, update-proxy and proxy-mappings
  • Support #564: this-as in ClojureScript
  • Store current analysis context during macro invocation, enabling tools like riddley to access outer locals
  • Full changelog

• clj-kondo: static analyzer and linter for Clojure code that sparks joy.
  @jramosg, @tomdl89 and @hugod have been on fire with contributions this period. Six new linters!

  • Released 2026.01.12 and 2026.01.19
  • #2735: NEW linter: :duplicate-refer which warns on duplicate entries in :refer of :require (@jramosg)
  • #2734: NEW linter: :aliased-referred-var, which warns when a var is both referred and accessed via an alias in the same namespace (@jramosg)
  • #2745: NEW linter: :is-message-not-string which warns when clojure.test/is receives a non-string message argument (@jramosg)
  • #2712: NEW linter: :redundant-format to warn when format strings contain no format specifiers (@jramosg)
  • #2709: NEW linter: :redundant-primitive-coercion to warn when primitive coercion functions are applied to expressions already of that type (@hugod)
  • Add new types array, class, inst and type checking support for related functions (@jramosg)
  • Add type checking support for clojure.test functions and macros (@jramosg)
  • #2340: Extend :condition-always-true linter to check first argument of clojure.test/is (@jramosg)
  • #2729: Check for arity mismatch for bound vectors, sets & maps, not just literals (@tomdl89)
  • #2768: NEW linter: :redundant-declare which warns when declare is used after a var is already defined (@jramosg)
  • Add type support for pmap and future-related functions (@jramosg)
  • Upgrade to GraalVM 25
  • Full changelog

• squint: CLJS syntax to JS compiler @tonsky and @willcohen contributed several improvements this period.

  • Add squint.math, also available as clojure.math namespace
  • #779: Added compare-and-swap!, swap-vals! and reset-vals! (@tonsky)
  • #788: Fixed compilation of dotimes with _ binding (@tonsky)
  • #790: Fixed shuffle not working on lazy sequences (@tonsky)
  • Multiple :require-macros with :refer now accumulate instead of overwriting (@willcohen)
  • Fix emitting negative zero value (-0.0)
  • Fix #792: prn js/undefined as nil
  • Fix #793: fix yield* IIFE
  • Full changelog

• scittle: Execute Clojure(Script) directly from browser script tags via SCI

  • Support async/await. See docs.
  • Implement js/import not using eval
  • Support this-as
  • nREPL: print #<Promise value> when a promise is evaluated

• nbb: Scripting in Clojure on Node.js using SCI

  • Support async/await. See docs for syntax.
  • Print promise result value in REPL/nREPL: (js/Promise.resolve 1) ;;=> #<Promise 1>

• fs - File system utility library for Clojure

  • Released 0.5.31
  • #212: Introduce :keep true option in with-temp-dir
  • #188 copy-tree now throws if src or dest is a symbolic link when not following links (@lread)
  • #201 gzip now accepts source-file Path (@lread)
  • #207 review and update glob and match docstrings (@lread)

• clerk: Moldable Live Programming for Clojure

  • Fix browse when using random port by passing 0, fixes #801
  • bb now supports editscript

• neil: A CLI to add common aliases and features to deps.edn-based projects.
  

  • #258: neil test now exits with non-zero exit code when tests fail

• cherry: Experimental ClojureScript to ES6 module compiler

  • Multiple :require-macros clauses with :refer now properly accumulate instead of overwriting each other

Contributions to third party projects:

• ClojureScript:
  • Working on async/await support (CLJS-3470). I also implemented this in SCI, scittle, and nbb.
  • CLJS-3471: fix printing of negative zero
  • CLJS-3472: str on var that is set! returns empty string
• editscript: Added babashka support, deps.edn for git dep usage, fixed CLJS tests
• riddley: Added babashka compatibility, clj-kondo config
• cloverage: Added babashka compatibility, migrated tools.cli from deprecated cli/cli to cli/parse-opts, bumped riddley
• specter: Added babashka compatibility
• compliment: Added babashka compatibility (PR #131)
• rebel-readline: Removed JLine impl class dependencies for babashka compatibility, released 0.1.7
• Selmer: Namespaced script tag context keys to avoid collisions, removed runtime require of clojure.tools.logging
• charm.clj: Contributed JLine integration, FFM native terminal interface, babashka and native-image compatibility

Other projects

These are (some of the) other projects I&aposm involved with but little to no activity happened in the past month.

Click for more details - [pod-babashka-go-sqlite3](https://github.com/babashka/pod-babashka-go-sqlite3): A babashka pod for interacting with sqlite3 - [unused-deps](https://github.com/borkdude/unused-deps): Find unused deps in a clojure project - [pod-babashka-fswatcher](https://github.com/babashka/pod-babashka-fswatcher): babashka filewatcher pod - [sci.nrepl](https://github.com/babashka/sci.nrepl): nREPL server for SCI projects that run in the browser - [babashka.nrepl-client](https://github.com/babashka/nrepl-client) - [http-server](https://github.com/babashka/http-server): serve static assets - [sci.configs](https://github.com/babashka/sci.configs): A collection of ready to be used SCI configs. - [http-client](https://github.com/babashka/http-client): babashka's http-client - [html](https://github.com/borkdude/html): Html generation library inspired by squint's html tag - [instaparse-bb](https://github.com/babashka/instaparse-bb): Use instaparse from babashka - [sql pods](https://github.com/babashka/babashka-sql-pods): babashka pods for SQL databases - [rewrite-edn](https://github.com/borkdude/rewrite-edn): Utility lib on top of - [rewrite-clj](https://github.com/clj-commons/rewrite-clj): Rewrite Clojure code and edn - [tools-deps-native](https://github.com/babashka/tools-deps-native) and [tools.bbuild](https://github.com/babashka/tools.bbuild): use tools.deps directly from babashka - [bbin](https://github.com/babashka/bbin): Install any Babashka script or project with one command - [qualify-methods](https://github.com/borkdude/qualify-methods) - Initial release of experimental tool to rewrite instance calls to use fully qualified methods (Clojure 1.12 only) - [tools](https://github.com/borkdude/tools): a set of [bbin](https://github.com/babashka/bbin/) installable scripts - [babashka.json](https://github.com/babashka/json): babashka JSON library/adapter - [speculative](https://github.com/borkdude/speculative) - [squint-macros](https://github.com/squint-cljs/squint-macros): a couple of macros that stand-in for [applied-science/js-interop](https://github.com/applied-science/js-interop) and [promesa](https://github.com/funcool/promesa) to make CLJS projects compatible with squint and/or cherry. - [grasp](https://github.com/borkdude/grasp): Grep Clojure code using clojure.spec regexes - [lein-clj-kondo](https://github.com/clj-kondo/lein-clj-kondo): a leiningen plugin for clj-kondo - [http-kit](https://github.com/http-kit/http-kit): Simple, high-performance event-driven HTTP client+server for Clojure. - [babashka.nrepl](https://github.com/babashka/babashka.nrepl): The nREPL server from babashka as a library, so it can be used from other SCI-based CLIs - [jet](https://github.com/borkdude/jet): CLI to transform between JSON, EDN, YAML and Transit using Clojure - [lein2deps](https://github.com/borkdude/lein2deps): leiningen to deps.edn converter - [cljs-showcase](https://github.com/borkdude/cljs-showcase): Showcase CLJS libs using SCI - [babashka.book](https://github.com/babashka/book): Babashka manual - [pod-babashka-buddy](https://github.com/babashka/pod-babashka-buddy): A pod around buddy core (Cryptographic Api for Clojure). - [gh-release-artifact](https://github.com/borkdude/gh-release-artifact): Upload artifacts to Github releases idempotently - [carve](https://github.com/borkdude/carve) - Remove unused Clojure vars - [4ever-clojure](https://github.com/oxalorg/4ever-clojure) - Pure CLJS version of 4clojure, meant to run forever! - [pod-babashka-lanterna](https://github.com/babashka/pod-babashka-lanterna): Interact with clojure-lanterna from babashka - [joyride](https://github.com/BetterThanTomorrow/joyride): VSCode CLJS scripting and REPL (via [SCI](https://github.com/babashka/sci)) - [clj2el](https://borkdude.github.io/clj2el/): transpile Clojure to elisp - [deflet](https://github.com/borkdude/deflet): make let-expressions REPL-friendly! - [deps.add-lib](https://github.com/borkdude/deps.add-lib): Clojure 1.12's add-lib feature for leiningen and/or other environments without a specific version of the clojure CLI - [edamame](https://github.com/borkdude/edamame): configurable EDN and Clojure parser with location metadata and more - [CLI](https://github.com/babashka/cli): Turn Clojure functions into CLIs! - [quickblog](https://github.com/borkdude/quickblog): light-weight static blog engine for Clojure and babashka - [process](https://github.com/babashka/process): Clojure library for shelling out / spawning sub-processes - [deps.clj](https://github.com/borkdude/deps.clj): A faithful port of the clojure CLI bash script to Clojure - [reagami](https://github.com/borkdude/reagami): A minimal zero-deps Reagent-like for Squint and CLJS - [parmezan](https://github.com/borkdude/parmezan): fixes unbalanced or unexpected parens or other delimiters in Clojure files - [quickdoc](https://github.com/borkdude/quickdoc): Quick and minimal API doc generation for Clojure - [Nextjournal Markdown](https://github.com/nextjournal/markdown)

Permalink

I am sorry, but everyone is getting syntax highlighting wrong

Translations: Russian

Syntax highlighting is a tool. It can help you read code faster. Find things quicker. Orient yourself in a large file.

Like any tool, it can be used correctly or incorrectly. Let’s see how to use syntax highlighting to help you work.

Christmas Lights Diarrhea

Most color themes have a unique bright color for literally everything: one for variables, another for language keywords, constants, punctuation, functions, classes, calls, comments, etc.

Sometimes it gets so bad one can’t see the base text color: everything is highlighted. What’s the base text color here?

The problem with that is, if everything is highlighted, nothing stands out. Your eye adapts and considers it a new norm: everything is bright and shiny, and instead of getting separated, it all blends together.

Here’s a quick test. Try to find the function definition here:

and here:

See what I mean?

So yeah, unfortunately, you can’t just highlight everything. You have to make decisions: what is more important, what is less. What should stand out, what shouldn’t.

Highlighting everything is like assigning “top priority” to every task in Linear. It only works if most of the tasks have lesser priorities.

If everything is highlighted, nothing is highlighted.

Enough colors to remember

There are two main use-cases you want your color theme to address:

1. Look at something and tell what it is by its color (you can tell by reading text, yes, but why do you need syntax highlighting then?)
2. Search for something. You want to know what to look for (which color).

1 is a direct index lookup: color → type of thing.

2 is a reverse lookup: type of thing → color.

Truth is, most people don’t do these lookups at all. They might think they do, but in reality, they don’t.

Let me illustrate. Before:

After:

Can you see it? I misspelled return for retunr and its color switched from red to purple.

I can’t.

Here’s another test. Close your eyes (not yet! Finish this sentence first) and try to remember what color your color theme uses for class names?

Can you?

If the answer for both questions is “no”, then your color theme is not functional. It might give you comfort (as in—I feel safe. If it’s highlighted, it’s probably code) but you can’t use it as a tool. It doesn’t help you.

What’s the solution? Have an absolute minimum of colors. So little that they all fit in your head at once. For example, my color theme, Alabaster, only uses four:

• Green for strings
• Purple for constants
• Yellow for comments
• Light blue for top-level definitions

That’s it! And I was able to type it all from memory, too. This minimalism allows me to actually do lookups: if I’m looking for a string, I know it will be green. If I’m looking at something yellow, I know it’s a comment.

Limit the number of different colors to what you can remember.

If you swap green and purple in my editor, it’ll be a catastrophe. If somebody swapped colors in yours, would you even notice?

What should you highlight?

Something there isn’t a lot of. Remember—we want highlights to stand out. That’s why I don’t highlight variables or function calls—they are everywhere, your code is probably 75% variable names and function calls.

I do highlight constants (numbers, strings). These are usually used more sparingly and often are reference points—a lot of logic paths start from constants.

Top-level definitions are another good idea. They give you an idea of a structure quickly.

Punctuation: it helps to separate names from syntax a little bit, and you care about names first, especially when quickly scanning code.

Please, please don’t highlight language keywords. class, function, if, elsestuff like this. You rarely look for them: “where’s that if” is a valid question, but you will be looking not at the if the keyword, but at the condition after it. The condition is the important, distinguishing part. The keyword is not.

Highlight names and constants. Grey out punctuation. Don’t highlight language keywords.

Comments are important

The tradition of using grey for comments comes from the times when people were paid by line. If you have something like

of course you would want to grey it out! This is bullshit text that doesn’t add anything and was written to be ignored.

But for good comments, the situation is opposite. Good comments ADD to the code. They explain something that couldn’t be expressed directly. They are important.

So here’s another controversial idea:

Comments should be highlighted, not hidden away.

Use bold colors, draw attention to them. Don’t shy away. If somebody took the time to tell you something, then you want to read it.

Two types of comments

Another secret nobody is talking about is that there are two types of comments:

1. Explanations
2. Disabled code

Most languages don’t distinguish between those, so there’s not much you can do syntax-wise. Sometimes there’s a convention (e.g. -- vs /* */ in SQL), then use it!

Here’s a real example from Clojure codebase that makes perfect use of two types of comments:

Disabled code is gray, explanation is bright yellow

Light or dark?

Per statistics, 70% of developers prefer dark themes. Being in the other 30%, that question always puzzled me. Why?

And I think I have an answer. Here’s a typical dark theme:

and here’s a light one:

On the latter one, colors are way less vibrant. Here, I picked them out for you:

Notice how many colors there are. No one can remember that many.

This is because dark colors are in general less distinguishable and more muddy. Look at Hue scale as we move brightness down:

Basically, in the dark part of the spectrum, you just get fewer colors to play with. There’s no “dark yellow” or good-looking “dark teal”.

Nothing can be done here. There are no magic colors hiding somewhere that have both good contrast on a white background and look good at the same time. By choosing a light theme, you are dooming yourself to a very limited, bad-looking, barely distinguishable set of dark colors.

So it makes sense. Dark themes do look better. Or rather: light ones can’t look good. Science ¯\_(ツ)_/¯

But!

But.

There is one trick you can do, that I don’t see a lot of. Use background colors! Compare:

The first one has nice colors, but the contrast is too low: letters become hard to read.

The second one has good contrast, but you can barely see colors.

The last one has both: high contrast and clean, vibrant colors. Lighter colors are readable even on a white background since they fill a lot more area. Text is the same brightness as in the second example, yet it gives the impression of clearer color. It’s all upside, really.

UI designers know about this trick for a while, but I rarely see it applied in code editors:

If your editor supports choosing background color, give it a try. It might open light themes for you.

Bold and italics

Don’t use. This goes into the same category as too many colors. It’s just another way to highlight something, and you don’t need too many, because you can’t highlight everything.

In theory, you might try to replace colors with typography. Would that work? I don’t know. I haven’t seen any examples.

Using italics and bold instead of colors

Myth of number-based perfection

Some themes pay too much attention to be scientifically uniform. Like, all colors have the same exact lightness, and hues are distributed evenly on a circle.

This could be nice (to know if you have OCD), but in practice, it doesn’t work as well as it sounds:

OkLab l=0.7473 c=0.1253 h=0, 45, 90, 135, 180, 225, 270, 315

The idea of highlighting is to make things stand out. If you make all colors the same lightness and chroma, they will look very similar to each other, and it’ll be hard to tell them apart.

Our eyes are way more sensitive to differences in lightness than in color, and we should use it, not try to negate it.

Let’s design a color theme together

Let’s apply these principles step by step and see where it leads us. We start with the theme from the start of this post:

First, let’s remove highlighting from language keywords and re-introduce base text color:

Next, we remove color from variable usage:

and from function/method invocation:

The thinking is that your code is mostly references to variables and method invocation. If we highlight those, we’ll have to highlight more than 75% of your code.

Notice that we’ve kept variable declarations. These are not as ubiquitous and help you quickly answer a common question: where does thing thing come from?

Next, let’s tone down punctuation:

I prefer to dim it a little bit because it helps names stand out more. Names alone can give you the general idea of what’s going on, and the exact configuration of brackets is rarely equally important.

But you might roll with base color punctuation, too:

Okay, getting close. Let’s highlight comments:

We don’t use red here because you usually need it for squiggly lines and errors.

This is still one color too many, so I unify numbers and strings to both use green:

Finally, let’s rotate colors a bit. We want to respect nesting logic, so function declarations should be brighter (yellow) than variable declarations (blue).

Compare with what we started:

In my opinion, we got a much more workable color theme: it’s easier on the eyes and helps you find stuff faster.

Shameless plug time

I’ve been applying these principles for about 8 years now.

I call this theme Alabaster and I’ve built it a couple of times for the editors I used:

• VS Code
• JetBrains IDEs
• Sublime Text (twice)

It’s also been ported to many other editors and terminals; the most complete list is probably here. If your editor is not on the list, try searching for it by name—it might be built-in already! I always wondered where these color themes come from, and now I became an author of one (and I still don’t know).

Feel free to use Alabaster as is or build your own theme using the principles outlined in the article—either is fine by me.

As for the principles themselves, they worked out fantastically for me. I’ve never wanted to go back, and just one look at any “traditional” color theme gives me a scare now.

I suspect that the only reason we don’t see more restrained color themes is that people never really thought about it. Well, this is your wake-up call. I hope this will inspire people to use color more deliberately and to change the default way we build and use color themes.

Permalink

Statistics made simple

I have a weird relationship with statistics: on one hand, I try not to look at it too often. Maybe once or twice a year. It’s because analytics is not actionable: what difference does it make if a thousand people saw my article or ten thousand?

I mean, sure, you might try to guess people’s tastes and only write about what’s popular, but that will destroy your soul pretty quickly.

On the other hand, I feel nervous when something is not accounted for, recorded, or saved for future reference. I might not need it now, but what if ten years later I change my mind?

Seeing your readers also helps to know you are not writing into the void. So I really don’t need much, something very basic: the number of readers per day/per article, maybe, would be enough.

Final piece of the puzzle: I self-host my web projects, and I use an old-fashioned web server instead of delegating that task to Nginx.

Static sites are popular and for a good reason: they are fast, lightweight, and fulfil their function. I, on the other hand, might have an unfinished gestalt or two: I want to feel the full power of the computer when serving my web pages, to be able to do fun stuff that is beyond static pages. I need that freedom that comes with a full programming language at your disposal. I want to program my own web server (in Clojure, sorry everybody else).

Existing options

All this led me on a quest for a statistics solution that would uniquely fit my needs. Google Analytics was out: bloated, not privacy-friendly, terrible UX, Google is evil, etc.

What is going on?

Some other JS solution might’ve been possible, but still questionable: SaaS? Paid? Will they be around in 10 years? Self-host? Are their cookies GDPR-compliant? How to count RSS feeds?

Nginx has access logs, so I tried server-side statistics that feed off those (namely, Goatcounter). Easy to set up, but then I needed to create domains for them, manage accounts, monitor the process, and it wasn’t even performant enough on my server/request volume!

My solution

So I ended up building my own. You are welcome to join, if your constraints are similar to mine. This is how it looks:

It’s pretty basic, but does a few things that were important to me.

Setup

Extremely easy to set up. And I mean it as a feature.

Just add our middleware to your Ring stack and get everything automatically: collecting and reporting.

(def app
  (-> routes
    ...
    (ring.middleware.params/wrap-params)
    (ring.middleware.cookies/wrap-cookies)
    ...
    (clj-simple-stats.core/wrap-stats))) ;; <-- just add this

It’s zero setup in the best sense: nothing to configure, nothing to monitor, minimal dependency. It starts to work immediately and doesn’t ask anything from you, ever.

See, you already have your web server, why not reuse all the setup you did for it anyway?

Request types

We distinguish between request types. In my case, I am only interested in live people, so I count them separately from RSS feed requests, favicon requests, redirects, wrong URLs, and bots. Bots are particularly active these days. Gotta get that AI training data from somewhere.

RSS feeds are live people in a sense, so extra work was done to count them properly. Same reader requesting feed.xml 100 times in a day will only count as one request.

Hosted RSS readers often report user count in User-Agent, like this:

Feedly/1.0 (+http://www.feedly.com/fetcher.html; 457 subscribers; like FeedFetcher-Google)

Mozilla/5.0 (compatible; BazQux/2.4; +https://bazqux.com/fetcher; 6 subscribers)

Feedbin feed-id:1373711 - 142 subscribers

My personal respect and thank you to everybody on this list. I see you.

Graphs

Visualization is important, and so is choosing the correct graph type. This is wrong:

Continuous line suggests interpolation. It reads like between 1 visit at 5am and 11 visits at 6am there were points with 2, 3, 5, 9 visits in between. Maybe 5.5 visits even! That is not the case.

This is how a semantically correct version of that graph should look:

Some attention was also paid to having reasonable labels on axes. You won’t see something like 117, 234, 10875. We always choose round numbers appropriate to the scale: 100, 200, 500, 1K etc.

Goes without saying that all graphs have the same vertical scale and syncrhonized horizontal scroll.

Insights

We don’t offer much (as I don’t need much), but you can narrow reports down by page, query, referrer, user agent, and any date slice.

Not implemented (yet)

It would be nice to have some insights into “What was this spike caused by?”

Some basic breakdown by country would be nice. I do have IP addresses (for what they are worth), but I need a way to package GeoIP into some reasonable size (under 1 Mb, preferably; some loss of resolution is okay).

Finally, one thing I am really interested in is “Who wrote about me?” I do have referrers, only question is how to separate signal from noise.

Performance. DuckDB is a sport: it compresses data and runs column queries, so storing extra columns per row doesn’t affect query performance. Still, each dashboard hit is a query across the entire database, which at this moment (~3 years of data) sits around 600 MiB. I definitely need to look into building some pre-calculated aggregates.

One day.

How to get

Head to github.com/tonsky/clj-simple-stats and follow the instructions:

Let me know what you think! Is it usable to you? What could be improved?

Permalink