<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Belisabettega on Medium]]></title>
        <description><![CDATA[Stories by Belisabettega on Medium]]></description>
        <link>https://medium.com/@belisabettega_83446?source=rss-024e2a029569------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/0*9RKpA12ELbAIWTkO</url>
            <title>Stories by Belisabettega on Medium</title>
            <link>https://medium.com/@belisabettega_83446?source=rss-024e2a029569------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Mon, 16 Nov 2026 18:22:28 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@belisabettega_83446/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Setting Up a Clojure App Template: The Decisions and Trade-offs Behind It]]></title>
            <link>https://medium.com/@belisabettega_83446/setting-up-an-opinionated-clojure-service-template-the-decisions-and-trade-offs-behind-it-d21b317f4278?source=rss-024e2a029569------2</link>
            <guid isPermaLink="false">https://medium.com/p/d21b317f4278</guid>
            <category><![CDATA[pedestal]]></category>
            <category><![CDATA[leiningen]]></category>
            <category><![CDATA[template]]></category>
            <category><![CDATA[clojure]]></category>
            <category><![CDATA[diplomat]]></category>
            <dc:creator><![CDATA[Belisabettega]]></dc:creator>
            <pubDate>Tue, 21 Jul 2026 00:20:59 GMT</pubDate>
            <atom:updated>2026-07-29T02:20:09.471Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*2eHf2UoFNS-DCSRdxWcH2Q.png" /></figure><p>There are many ways to start learning a new language but, personally, my favorite one is by starting a hobby web app. Coming from a ruby background where the &quot;Convention over Configuration&quot; software design paradigm is very present my first though was: what is the convention when building a clojure app? And what is the recommended structure for it?</p><p>This is why I decided to create this blog post, it was a way to understand the clojure mindset and best-practices while also documenting and analysing the decisions and trade-offs of setting up a clojure app for the first time.</p><h4>How to get started: which dependency management tool to use</h4><p>My first challenge was deciding what tool to use to get started and there were three main options¹:</p><ol><li>CLI deps: tool built by the Clojure core team that provides dependency management, REPL support and execution of Clojure programs. Uses a deps.edn file.</li><li>Leiningen: extensive build tool that provides not only dependency management, REPL support but also testing, packaging, deployment and other capabilities. Uses a project.clj file.</li><li>Boot: also a build tool but with a focus on supplying abstractions and libraries to automate different build scenarios.</li></ol><p>From these three tools, CLI deps and Leiningen were the ones more often compared and considered in different talks and articles.</p><p>Leiningen was created in a context where Clojure didn’t have a build tool of its own and it carries Java&#39;s tools artifact-centric mental model. That means that Leiningen tends to treat software primarily as versioned build artifacts (usually Maven/JAR ones) that are built, installed, and consumed through the dependency graph.</p><p>This mental model centers dependency management on artifact versions that are declared in the project.clj file and creates friction for working across multiple local libs, speculative changes, or code that is not yet published as an artifact.</p><p>The CLI deps came as a way to address this by treating the project as a collection of source paths and dependencies, giving it a fast, lightweight setup without Maven’s artifact-first assumptions².</p><p>The trade-off here though is that this freedom comes with more responsibility (and configuration).</p><p>This is because Leiningen already provides a series of tasks out of the box while CLI deps will need to be configured to do the same. The following table shows the main tasks and if they are or not available from the get-go in both Leiningen (lein) and CLI deps (deps):</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*FQ0757NXie5KIHkuqBavgg.png" /><figcaption>Image extracted from talk given by Aleksandar Simic³</figcaption></figure><p>This other comparison shows the commands used by each tool to implement those tasks:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*CTEkJXMFbm1nyqv6BemCRw.png" /><figcaption>Image extracted from talk given by Aleksandar Simic³</figcaption></figure><p>This means that while Leiningen provides the developer with a default/out-of-the-box way of running tests, packaging and releasing, CLI deps focus on resolving deps and building classpaths and delegates the rest of it to tools to be congurated specifically, so for example:</p><ul><li>To run tests while using CLI deps there is a need to provide the setting on how the tests should be picked up and ran. This can be done by using alias and setting up test runners from cognitec, eftest and kaocha for example.</li><li>To build a JAR with CLI deps there are several packaging and build tools such as packs, depstar and uberdeps. Uberdeps is specially popular for mimicking the behavior you’d get with lein uberjar since it runs one command and it does the work for you.</li></ul><p>But then, after evaluating those differences, how to decide about which tool to use then?</p><p>The first thing is to recognize that both tools cover the same usages so choosing one or the other is more a matter of preference. CLI deps might be the call if you:</p><ul><li>need a lightweight approach;</li><li>have a project that depends on certain repos that haven’t yet being pushed to clojars and do not want to depend on plugins such as lein-git-down to use code directly from github;</li><li>have a sophisticated test chain. With Leiningen, once your needs go beyond ordinary lein test / profiles / aliases, you often start pushing logic into Lein-specific mechanisms: profiles, aliases, middleware, and sometimes custom plugins. With deps you can build exactly the task chain you want on top, in normal Clojure, instead of conforming to Lein’s model;</li><li>need a easier way to get standardized environments. This is because Leiningen has ambient user config that can influence runs and isolating yourself from that is not the default happy path. With CLI deps there is less built-in magic, but easier to make reproducible and bespoke;</li><li>need more control and flexibility over how to build things: deps allows you to build your own tooling out of ad hoc clojure functions;</li></ul><p>But the main argument towards CLI deps regards plugins. This is because with Leiningen important behavior lives in plugins and those plugins might be broken, outdated, or incompatible leading to core workflows breaking or drifting.</p><p>Besides that, each plugin has its own conventions and lifecycle. Some even require local installation/activation steps per developer, which adds another failure mode. In order to deal with that team end up needing to centralize plugin management to reduce churn and so plugin integration/versioning/repeatability becomes part of everyday maintenance.</p><p>On the other hand Leiningen feels way more friendly for beginners: since scaffolding projects is part of the tool it offers a simple command to bootstrap a new clojure app (<em>lein new app</em>) and also very easy to remember commands that provide a better developer experience (like <em>lein lint</em>, <em>lein test</em>, etc.).</p><p>One best practice though, even when deciding to use Leiningen, is to keep project.clj as the main build file, but also generate a matching deps.edn so Clojure CLI / tools.deps users can work with your project too. Repos can contain both files side by side and this approach don’t force contributors and CLI users to speak only Leiningen keeping the project usable from both worlds.</p><p>Have in mind though that a synced deps.edn is mostly helpful for source-level workflows: local development, REPL, running tests with the CLI, or using the project as a git/local dep.</p><p>For the sake of this article and considering:</p><ol><li>This is a initial template to explore and learn clojure;</li><li>My inclination for convention over configuration;</li><li>The template is intended for a hobby project and not a scalable service;</li></ol><p>Leiningen feels like the right choice here. It is a easy, batteries-included option that removes part of the complexity and configuration choices needed for more complex and large scale projects. So the template will use Leiningen for now.</p><h3>Pedestal vs Ring + Reitit</h3><p>Most Clojure web services are built on <a href="https://github.com/ring-clojure/ring">Ring</a>, a simple, widely-adopted spec for HTTP handlers as plain functions from a request map to a response map, composed via middleware (functions that wrap a handler to add behavior like logging, auth, JSON parsing before and after it runs). <a href="https://github.com/metosin/reitit">Reitit</a> is typically paired with Ring to add fast routing on top.</p><p>This combination is lightweight and easy to reason about, and it’s a great default for many services. <a href="http://pedestal.io/">Pedestal</a>, the framework used in this template, takes a different approach: instead of middleware wrapping a handler, it models a request as a chain of interceptors, each with an explicit :enter and :leave function. The chain runs all :enter functions in order, reaches the handler, then runs all :leave functions back in reverse order.</p><p>Two things about that model make it worth the extra concept:</p><ol><li>Symmetry. An interceptor can inspect and modify both the request on the way in and the response on the way out, using the same data structure (the context map) throughout. Auth, request logging, and response shaping all follow the same shape instead of three different middleware conventions.</li><li>Testability without a socket. Because a Pedestal service is ultimately just a function from a servlet request to a servlet response, you can drive the entire interceptor chain (routing, body parsing, auth, your handler) in-process, with no Jetty server and no open port, via io.pedestal.test/response-for. That gives you a middle tier in your test pyramid that’s almost as fast as a unit test but exercises real routing and real middleware-equivalent behavior.</li></ol><p>Pedestal is a heavier dependency and a steeper initial learning curve than Ring + Reitit, and for a small service or a prototype, that trade may not be worth it. But for a service expected to grow with more routes, more interceptors and more layers of cross-cutting concerns, the interceptor model tends to scale more gracefully than a stack of middleware functions.</p><h3>Building a Clojure Service Template, Step by Step</h3><p>After those two main decisions, the following steps show how to go from starting a lein new app’s bare output to an opinionated Clojure Service Template.</p><h4>Hardening project.clj:</h4><p>The bare template’s project.clj has one dependency (Clojure itself) and no meaningful structure. Before writing any application code, it’s worth deciding:</p><ul><li>Dependencies, in a deliberate order. Maven’s conflict resolution is “nearest wins”, that is: the version closest to the root of the dependency tree is chosen, and when two dependencies sit at the same depth, declaration order breaks the tie. Listing Clojure first, then the web framework, then the lifecycle library, then logging, then everything else keeps the tree predictable and makes version conflicts easier to diagnose later (and this pays off the first time you have to debug a dependency clash).</li><li>Profiles. :uberjar turns on ahead-of-time (AOT) compilation and direct-linking for a faster, self-contained deployable jar. :dev adds REPL tooling and source paths that should never ship to production. Splitting these means your production artifact never accidentally carries dev-only code or dependencies.</li></ul><h4>A Component Lifecycle System</h4><p>The bare template has no notion of “start” or “stop” since the process just runs -main and does whatever it does. That’s fine for a script, but a long-running service inevitably accumulates stateful things that need to start in the right order and shut down cleanly: an HTTP server, eventually a DB connection pool, a message queue consumer. Stuart Sierra&#39;s <a href="https://github.com/stuartsierra/component">component</a> solves this with a small Lifecycle protocol (start/stop) and a dependency graph (system-map + component/using). Each piece of the running service becomes a component, and the whole system starts and stops in dependency order automatically.</p><p>The immediate payoff, beyond production correctness, is REPL-driven development: you can tear down and rebuild the entire system from a live REPL without restarting the JVM, because “the system” is just a value you can start, stop, and replace.</p><h4>A Single Source of Truth for Configuration</h4><p>Instead of scattering System/getenv calls throughout the codebase, every setting is read through one config.clj namespace which is the only place that knows environment variable names, defaults, and coercions (e.g., parsing PORT as an integer). This means:</p><ul><li>Changing a default or adding validation happens in exactly one place.</li><li>Tests can override config values in one predictable spot instead of hunting for getenv calls.</li><li>It’s immediately obvious, from reading one small file, everything the service can be configured to do.</li></ul><h4>The Diplomat Layer: Inbound and Outbound HTTP Boundaries</h4><p>All inbound HTTP concerns (diplomat/http_server.clj) like routes, handlers and Pedestal syntax live in one namespace. All outbound HTTP calls (diplomat/http_client.clj) live in a mirrored one.</p><p>This is a “diplomat” pattern: the only code in the entire service that’s allowed to know about the specific shape of an HTTP request or response is this boundary layer. Domain logic calls plain functions, never clj-http or Pedestal route syntax directly.</p><p>The advantage compounds as the service grows: adding retries, auth headers, or a base-URL config to outbound calls means touching one namespace, not every call site.</p><p>Handlers stay thin and delegate to domain code, keeping “how do we talk over HTTP” separate from “what does this service actually do.”</p><h4>Wire Schemas</h4><p>Every payload this service accepts or returns is validated against a schema, split into wire.in (what we accept) and wire.out (what we return). Validating incoming and outgoing payloads independently means:</p><ul><li>A handler that shapes its own response incorrectly gets caught by the wire.out schema before the bad response goes out over the wire.</li><li>a bug in your own code is caught the same way a bad client request is.</li><li>The two directions are free to diverge later without one schema having to serve two incompatible purposes.</li></ul><p>A note on the choice of library: this template uses Malli because it’s a lightweight, self-contained dependency for a standalone project. Larger Clojure shops that use this same wire.in/wire.out split often build it on top of <a href="https://github.com/plumatic/schema">Plumatic Schema</a> instead, wired into the interceptor chain as coerce!/externalize! steps. The split itself, not the specific schema library, is the pattern worth keeping.</p><h4>Authentication as an Interceptor</h4><p>The template includes a minimal but real auth example: a shared bearer token, checked via <a href="https://github.com/funcool/buddy-auth&#39;s">https://github.com/funcool/buddy-auth&#39;s</a> token backend. buddy-auth is normally Ring middleware, so wiring it into Pedestal’s interceptor model means manually invoking its -parse/-authenticate protocol functions inside a Pedestal interceptor rather than using it out of the box.</p><p>This is a small adapter, but a useful pattern to see once, since it’s the same shape you’d use to wire in JWT verification or an API-key lookup later without touching the interceptor that guards routes.</p><h4>The REPL-Driven (“Reloaded”) Dev Workflow</h4><p>dev/user.clj exposes three functions: go (start the system against local config), stop, and reset (stop, reload any changed namespaces via clojure.tools.namespace.repl, then start back up).</p><p>This is Stuart Sierra’s well-known “reloaded” workflow: after editing code, you call (reset) instead of restarting the JVM, which is both faster and preserves your REPL history and any state you’ve built up interactively. Keeping dev/ and its dependencies scoped to the :dev profile matters here too: only src and dev are on the classpath for set-refresh-dirs, so refreshing never picks up test code or stale compiled test classes.</p><p>This go/stop/reset shape is the classic version of the reloaded workflow, and it’s the right starting point for a template. As a service and its REPL usage matures, teams often evolve it further by restarting just the Component system in place inside an already-running REPL/nREPL session (rather than a separate dev process), so a long-lived REPL survives edits without ever losing accumulated state. The mechanism differs, but the underlying idea of never restarting the JVM to see a code change is the same.</p><h4>The Testing Pyramid</h4><p>Rather than one flat pile of tests, the template splits testing into three layers, each trading speed for fidelity:</p><ul><li>Unit tests for pure functions (config, wire.in/wire.out schemas) with no HTTP involved at all. Fast, numerous, the base of the pyramid.</li><li>Service tests for the entire Pedestal interceptor chain (routing, body-params, auth, the handler, wire validation) driven in-process via io.pedestal.test/response-for, with no Jetty server and no open socket. This is the layer Pedestal’s interceptor model enables cheaply, and it’s where most of the “does this behave correctly end to end” testing should live.</li><li>Integration tests for a real Jetty server on a real port tohit over an actual socket with clj-http. Slow and few in number, but they catch anything the in-process test can’t — real serialization over the wire, real connection handling. <strong>Worth calling out</strong>: for a single, standalone service this tier still earns its keep, but it doesn’t scale as a strategy once you have many services calling each other. Organizations running thousands of interdependent Clojure services have moved away from real-socket, real-environment tests because they get slow and flaky past a certain scale. Instead they chose in-process interceptor-chain tests plus contract tests that verify producer/consumer schema compatibility offline. If this template grows into a multi-service system, that’s the direction to look, rather than adding more real-socket tests per service.</li></ul><h4>Observability: A Health Check and Sane Logging</h4><p>Two small but easy-to-forget pieces:</p><ul><li>GET /health: a deliberately unauthenticated, dependency-free endpoint returning {“status”: “ok”}, meant as a target for load balancers and orchestrators (Kubernetes liveness/readiness probes, etc.) to poll. It reports only whether the process itself is up, not the health of downstream dependencies, which keeps it fast and reliable enough to be trusted for automated restarts. This is a deliberate simplification for this template: a liveness check should stay minimal so a downstream outage doesn’t trigger a restart storm, but many production setups add a separate readiness check (or aggregate dependency status into /health itself) so orchestrators can stop routing traffic to an instance whose DB or upstream is down without killing the process.</li><li>resources/logback.xml:without any Logback configuration, Pedestal logs one DEBUG line per interceptor per request, which drowns out anything you actually care about. A small config file dialing Pedestal’s logger down to WARN, while leaving your own application logs at INFO, is the difference between a usable log stream and unreadable noise — and it’s easy to skip entirely if nobody sets it up on day one.</li></ul><h4>Continuous Integration</h4><p>Finally, a GitHub Actions workflow runs lein test on every pull request and push, then, gated on tests passing,builds the uberjar in a separate job. The gating matters: it guarantees a broken build never reaches the packaging step, and separating “test” from “build” leaves room to bolt a real deploy step onto the end later without re-running the whole test suite.</p><h4>Closing Thoughts</h4><p>None of the decisions above are Pedestal or Component-specific dogma, they’re the smallest set of choices a service needs made before it can be deployed and operated safely: how it’s configured, how it starts and stops, how its contracts are validated, how it’s tested at multiple levels of fidelity, and how it’s observed once it’s running. Making these decisions once, in a template, means every new service starts from a foundation instead of re-deriving the same answers from scratch.</p><h3>References</h3><ol><li>CLOJURE. Clojure Tools. Source: <a href="https://clojure.org/community/tools">https://clojure.org/community/tools</a></li><li>MILLER, Alex. Dependency Heaven. Source: <a href="https://github.com/matthiasn/talk-transcripts/blob/master/Miller_Alex/DependencyHeaven.md">https://github.com/matthiasn/talk-transcripts/blob/master/Miller_Alex/DependencyHeaven.md</a></li><li>SIMIC, Aleksandar. From lein to deps and back. London Clojurians. Oct 2020. Source: <a href="https://www.youtube.com/watch?v=nAu8AWc-IvE">https://www.youtube.com/watch?v=nAu8AWc-IvE</a></li></ol><ul><li><a href="https://clojure-doc.org/articles/cookbooks/cli_build_projects/">https://clojure-doc.org/articles/cookbooks/cli_build_projects</a></li><li><a href="https://japan-clojurians.github.io/clojure-site-ja/reference/deps_and_cli">https://japan-clojurians.github.io/clojure-site-ja/reference/deps_and_cli</a></li><li><a href="https://www.reddit.com/r/Clojure/comments/16awahk/revisiting_clojure_the_build_tool_situation/">https://www.reddit.com/r/Clojure/comments/16awahk/revisiting_clojure_the_build_tool_situation/</a></li><li><a href="https://clojure-doc.org/articles/tutorials/getting_started/">https://clojure-doc.org/articles/tutorials/getting_started/</a></li><li><a href="https://leiningen.org/tutorial">https://leiningen.org/tutorial</a></li><li><a href="https://clojure-doc.org/articles/cookbooks/cli_build_projects/">https://clojure-doc.org/articles/cookbooks/cli_build_projects/</a></li><li><a href="https://www.cognitect.com/blog/2013/06/04/clojure-workflow-reloaded">https://www.cognitect.com/blog/2013/06/04/clojure-workflow-reloaded</a></li><li><a href="https://www.slideshare.net/slideshow/microservices-in-clojure/71972771">https://www.slideshare.net/slideshow/microservices-in-clojure/71972771</a></li><li><a href="https://www.slideshare.net/slideshow/complex-made-bearable-clojure-conj-2019/196117487">https://www.slideshare.net/slideshow/complex-made-bearable-clojure-conj-2019/196117487</a></li><li><a href="https://building.nubank.com/functional-programming-with-clojure/">https://building.nubank.com/functional-programming-with-clojure/</a></li><li><a href="https://www.slideshare.net/slideshow/the-advantages-of-functional-programming-with-clojure/255658038">https://www.slideshare.net/slideshow/the-advantages-of-functional-programming-with-clojure/255658038</a></li><li><a href="https://medium.com/building-nubank/working-with-clojure-at-nubank-ef165b77bf08">https://medium.com/building-nubank/working-with-clojure-at-nubank-ef165b77bf08</a></li><li><a href="https://www.youtube.com/watch?v=ct5aWqhHARs">https://www.youtube.com/watch?v=ct5aWqhHARs</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=d21b317f4278" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>