Clojure Multi-Project Example Layout and Tool Use

NOTICE: Bespoke Software For My Use.
However, I hope others find some value in the idea(s) / trick(s)
contained herein. Plus, "Learn Generously" is my
credo, and I hope publishing this
welcomes brain-exchange with kindred spirits.
So... MIT-licensed for great good.
Please mess about and contribute feedback / critique!
No idea is sacrosanct.
- Try-out-ers: Follow Quick Start to, well, quick
start.
- Rationale-seekers: Concept and sundry design notes
hopefully explain where I'm trying to go with this.
- Code readers, these are the important reference points:
- The top-level
deps.edn declares all source code relationships
build/build.clj and bin/run_cmd.sh contain all commands to
execute against the whole or part of the multiproject
parts are functions: Mutually independent building blocks
that we configure and compose into applications. I've made my own
grugstack, but you can vendor in anything of your own.
projects are objects: Purpose-built applications, having
whatever architecture they need to have, built using whatever set
of libraries and/or parts they need.
- Following multiproject's
:app-alias naming convention is key
(haha) to success (see MultiProject Conventions).
Quick Start
Try from project root:
- Requirements must first be satisfied, of course.
- The
bin/run_cmd.sh Bash helper script builds and runs commands
documented in Usage. (TBD: rewrite as babashka script for
maximum portability).
bin/run_cmd.sh # and follow the menu to pick COMMAND and ALIAS
# OR
bin/run_cmd.sh run_TESTS # and follow the menu to pick ALIAS
# OR, directly make it do what you mean...
bin/run_cmd.sh run_TESTS "com.acmecorp.snafuapp.core"
bin/run_cmd.sh run_UBERJAR "com.acmecorp.snafuapp.core"
Concept
As of today, "multiproject" addresses my own specific
requirements; viz.
Indie and Hobby SaaS apps of my own;
RAD
for outcomes-driven customers who want long-lived, stable
software. I'm my own customer! And I'm available for hire!
Benefit from the Clojure ecosystem's creativity, reach, stewardship,
and software stability.
Professionally, I want to be able to:
- create, manage, and maintain multiple apps/projects,
- under /a single source tree/ (no diamond dependencies, please),
- crafted with a well curated application stack
- that each application/project can use a la carte
- and which I can pry apart cleanly, if needed (e.g. hand over source to a
customer or buyer (that will be the day!)).
Architecturally, I want to retain optionality.
Choosing to focus on outcomes means I should retain the option to
use any framework or architecture or Clojure dialect, for any type
of application (web, backend, developer tool etc.).
As of this writing, I feel like this is already plausible. I don't see
why any one app managed by "multiproject" cannot itself be a
biff/kit/duct app, or itself follow polylith architecture, or be just
a single babashka script.
Systematically, I want /system and workflow/ re-use.
In addition to stack reuse.
Just enough structure to help me manage things, while staying sane,
without building hard dependence on any specific project layout, build
tool, application stack etc.
More stream-of-conscious-y stuff squirreled away under
sundry design notes.
Requirements
Mandatory
A working Clojure
installation (prefer the latest available Clojure).
Optional
Bash to use the bin/run_cmd.sh. I've assumed Bash 5.0+. Bash 4.0+
should be okay too.
DIY
Non-Linux users may have to fiddle about to make things work right for
them. I use Ubuntu 24.04 LTS on my dev and server boxen. So I haven't
paid attention to any other OS.
MultiProject Conventions
Mandatory
The root deps.edn is the lynchpin of control.
- It defines conventions and data relied upon by everything under the
multiproject; repl, build, test, ci, local-m2 etc.
- Each project/app must have a minimal
deps.edn under its project
root. The app-specific deps file must specify its own library
dependencies.
- Multiproject commands will ignore any project-specific alias or
extra path. These may be defined at-will, only for developer
convenience.
Top-level alias naming convention does a lot of heavy lifting for us.
- All project-global information must be described under
:root/
aliases, only in the root deps.edn file. This helps avoids
overlap / conflict with system-specific and user-specific
deps.edn.
- Each project / application must get its own alias (a keyword),
only in the root
deps.edn. The alias data is used by commands
defined for use within the multiproject.
- Project alias names must map to one and only one project.
- Project alias name must match the project' main entry point namespace.
- Build commands rely on the keyword alias when provided
via.
:app-alias command line option.
- The uberjar build procedure relies on our namespacing convention
to ensure clean separation of build-time classpaths, intermediate
artifacts, and so forth.
- Socket REPL management is easier if we name the socket file
according to the alias.
Optional
- A multiproject-local
.m2 repository may be useful for dependency
management / audit reasons, but isn't a hard requirement.
- We many need to help LSP recognise individual apps/projects by
placing a
.gitignore under the project root (for completions,
refactoring, etc.).
Usage
Use aliases from the root-level deps.edn to run everything from the
root of the source repo. Here "everything" including tests, builds, CI
tasks.
REPL Development
I prefer to start REPLs at the shell, and connect to them via my code
editor. This lets me independently kill/restart/manage the REPL
process and the Editor process. Sometimes one of them can go into a
bad state. Live REPL state tends to collect orphan objects the longer
they are live. Sometimes I want to force-invalidate some editor
state, which may require killing and cold-starting it. etc...
Start a REPL at a random port.
This is the most common way to start a REPL. This works just fine for
conventional single-repo single-app style projects.
clj -M:root/all:root/dev:root/test:cider
Start REPL at specific UNIX domain socket.
This is my preferred tactic to trivially share or isolate REPLs from
each other, in a multi-project context. The trick is to name socket
paths along the project directory paths structure. For example:
To imply a REPL is shared across the whole multi-project, create
the UNIX domain socket at the root of the multi-project repo.
clj -M:root/all:root/dev:root/test:cider --socket "repl.socket"
To imply a REPL is specific to a project, create the socket at the
root of the project directory.
clj -M:root/all:root/dev:root/test:com.example.core:cider --socket "projects/example_app/repl.socket"
clj -M:root/all:root/dev:root/test:com.acmecorp.snafuapp:cider --socket "projects/acmecorp/snafuapp/repl.socket"
REPL Development with Project Isolation
This trick helps us conveniently access / share code from anywhere in
the multi-project, while also being able to isolate project-specific
REPL state when needed.
Example: Isolating Integrant REPL state per-project, while being able
to access source code from any path in the multi-project.
- We know we can automatically bootstrap custom code and settings into
the default
user namespace. This is Clojure's standard bootstrap
behaviour.
- We know every REPL is an isolated process. So, all bootstrapped
context is isolated by construction.
Given these guarantees...
- I've placed my "bootstrap" code in
dev/user.clj, right under the
root of the multi-project. It contains handy REPL utilities to
manipulate system state (start / stop / restart), as well as spin
up developer tools like portal.
- Thus different REPLs running at independent sockets, are
bootstrapped using the same
user.clj code yet REPL state is
maintained independently, in isolated process, by construction.
- At the same time, we can use our top-level
deps.edn settings to
configure source access for each project-specific alias. With this,
we can grant access to any permutation of the multi-project
codebase.
Thus, inert code can be shared, while live state is isolated.
TEST running
Test all apps:
clj -X:root/all:root/test
- The trick is to declare all test target directories; viz. root of
all apps and of grugstack. PLUS, inject grugstack as an extra-deps
(via :root/all).
Test only one app:
- To narrow test target to a single project at a time, we rely on
the published alias override/merge behaviour of deps.edn.
- Here do it for SNAFUapp by ACME Corp. By appending its deps.edn
alias, we narrow test target to only SNAFuapp test dirs. This is
due to the "win last" override/merge order of aliases
defined by Clojure CLI.
clj -X:root/all:root/test:com.acmecorp.snafuapp.core
- Here we do the same narrowing for
grugstack itself.
clj -X:root/all:root/test:grugstack
BUILD options
Full CI
Run full CI sequence for individual apps.
- BUILD default example project specified by alias under this path in
our deps config -> [:root/build :extra-args :app-alias].
clj -T:root/build
Then check it with...java -jar target/com.example.core/com.example.core-*.jar
- BUILD project identified by :app-alias
clj -T:root/build :app-alias ':com.acmecorp.snafuapp.core'
Then check it with...java -jar target/com.acmecorp.snafuapp.core/com.acmecorp.snafuapp.core-*.jar
# Followed by
curl localhost:13337
UBERJAR only
Package a single app into an uberjar.
Run only "uberjar" part of the CI sequence, for app identified by
:app-alias.
clj -T:root/build uberjar :app-alias ':com.acmecorp.snafuapp.core'
Then check it as described above
TEST only
Run only "test" part of the CI sequence, for apps identified by
:app-alias.
clj -T:root/build test :app-alias ':com.acmecorp.snafuapp.core'
NEW PROJECT addition
We can just use the
deps-new tool, from the
root directory of the multi-project repo.
Example:
clojure -Tnew app :name com/acmecorp/fubarapp/core :target-dir projects/acmecorp/fubarapp
This produces the usual "application" project layout. We don't really
need some of the files under the newly-created project, but it
doesn't hurt us to let them be (README, LICENSE, build.clj, .gitignore
etc.). Tomorrow, if I need to pull the app out of the multi-project,
into a standalone project (say, to hand over to someone), then staying
compatible with the standard app layout should make extraction easier.
$ tree -a projects/acmecorp/fubarapp/
projects/acmecorp/fubarapp/
├── build.clj
├── CHANGELOG.md
├── deps.edn
├── doc
│ └── intro.md
├── .gitignore
├── LICENSE
├── README.md
├── resources
│ └── .keep
├── src
│ └── com
│ └── acmecorp
│ └── fubarapp
│ └── core.clj
└── test
└── com
└── acmecorp
└── fubarapp
└── core_test.clj
Sundry Project Maintenance
Code formatting
As of this writing, cljfmt drives code formatting convention. Thank
you, yet again, weavejester.
- Install as clj tool aliased as cljfmt:
clj -Ttools install io.github.weavejester/cljfmt '{:git/tag "0.13.0"}' :as cljfmt
- Configure options in
cljfmt.edn (:path being the most important
for our multi-project).
- Check whole-repo formatting:
clj -Tcljfmt check
- Fix whole-repo code format:
clj -Tcljfmt fix
Sundry Design Notes
Here's my stream of consciousness...
The attempt is to...
- Share a common abstract "system" (which I'm calling
grugstack),
- across multiple apps, within a single repo (this multi-project example),
- managed with only out-of-the-box tooling (not out-of-the-box thinking).
- Whether the apps are standalone (like
projects/example_app), or must
be neatly isolated for my customers (e.g. projects/acmecorp/snafuapp).
- BTW, do you want to build a niche Micro-SaaS? For outside
customers? Inside customers? As your own private force-multiplier?
Hire me!
Conceptually, it is aspirational...
- I was obsessing about web stacks, but now I suspect this bag of
tricks will generalise to apps made for any arbitrary Clojure /
ClojureScript runtime; whether web app, desktop, mobile, cli, data
science etc... And the code for all these diverse apps can be
managed within a single source repo.
- The Way is not Purely Functional /or/ Purely Object Oriented, but
a "Best of Both" approach, all the way down to code layout.
- A system of parts (functions) that glue together à la carte,
- via carefully constructed (namespaced, structured) plain Clojure
data,
- into any number of runnable apps (open-ended polymorphism) (see
credits).
Ideally, I want to get away with...
- the simplest possible project tree layout, even if it makes code
and command-line invocations repetitive or verbose. My grug brain
can easily plod along long paths, as long as they are made painfully
obvious.
- the fewest possible bespoke abstractions or terms of art,
because making a Domain Specific Language is easy, but keeping it
sensible is hard.
- no custom build tooling. I just want to appropriate the raw
machinery and public contracts provided by deps.edn, tools.build,
and Clojure CLI. I've chosen to used in the usual way, via a single
multi-project-level
build.clj. Stare at the build.clj file and
the multi-project-level deps.edn file side-by-side to see the
main trick I've used... I figured out a permutation of (alias names
x grouping of paths x grouping of dependencies x grouping of args
that must get overridden to narrow context to the last alias).
By design, I want to run tools / start REPLs etc. only at the root
of the multi-project, and use explicit command-line options to
broaden or narrow scope of the command / REPL to the part(s) of the
multi-project that I want to target. This helps me keep a simple
mental model of managing the whole or the part of the multi-project,
that can show up legibly in my shell's history / project logs /
docs etc. (hopefully the Usage examples will make this clear).
TODO
Lots.
Contributing
As of now, I am in discussions-only mode... Ping me in the Clojurians
Slack or Zulip or this thread
in the official mailing list.
Credits
I've consumed way too much web-stack buildin' prior art from across
the Clojure ecosystem. Clojure core, community librarians, builders,
architects, teachers, book authors: the whole lot of you; thank you!
Special mentions to authors making projects and explanations for use
by solo/indie web app builders: biff, duct, zodiac, caveman.
Last but not least, special mention to polylith, which lit a key
light bulb in my head... The "Expression Problem" applies to code
layout and application architecture too! Not Functions v/s Objects;
but Functions and Objects.
That said, I'm not sure I've "got it" yet. So to take it back to the
top, please send design notes my way!
License & Copyright
Copyright (c) 2025 Aditya Athalye.
Distributed under the MIT license.