Launchpad is a Clojure dev process launcher.
It starts from these observations:
- Clojure development is done interactively
- This requires a nREPL connection between a Clojure process and an editor
- How Clojure/nREPL gets started varies by
- editor (which middleware to include?)
- project (how to start the system, cljs config)
- individual (preferences in tooling, local roots)
- Projects are increasingly multi-module, either monorepo, or spread across repos
- We mainly rely on our editors to launch Clojure/nREPL because it is tedious
- Other tools could benefit from participating in the startup sequence (e.g. lambdaisland/classpath)
- Automating startup is done in an editor-specific way (.dir-locals.el, calva.replConnectSequences)
- And requires copying boilerplate around (user.clj)
And these preferences:
- We want project setup to be self-contained, so starting a process "just works"
- This should work for everyone on the team, no matter what editor they use
- We prefer running the process in a terminal for cleaner separation and control
- When working on multiple related projects we prefer a single JVM over multiple
Launchpad is a babashka-compatible library, through a number of steps it builds
up a Clojure command line invocation, including JVM options, extra dependencies,
and forms to evaluate, including starting nREPL with selected middleware,
watching deps.edn
files for changes, starting ClojureScript build watchers,
and hooking up your editor (if supported, otherwise a manual connect to nREPL is
needed).
It takes information from deps.edn
(checked in) and deps.local.edn
(not
checked in) and arguments passed in on the command line to determine which
modules to include, which middleware to add to nREPL, which shadow-cljs builds
to start, etc.
Launchpad integrates with lambdaisland.classpath
to provide hot-reloading of
deps.edn
and deps.local.edn
, so you can add dependencies to your project,
switch a dependency to a newer version, or from a Maven-provided jar to a local
checkout, all without restarting your process and REPL. You can even activate
additional aliases without restarting. How cool is that?
See template
for an example setup, you need a few different pieces.
bb.edn
{:deps {com.lambdaisland/launchpad { ... }}}
bin/launchpad
This is the default convention for launchpad-based projects, it provides a recognizable, predictable entry point that people will be looking for in your project, so use it. This is a simple babashka script invoking launchpad, but there's lots of room to customize this. Want to check the Java version, launch docker-compose, ensure environment variables are set up? You do that here.
#!/usr/bin/env bb
(require '[lambdaisland.launchpad :as launchpad])
(launchpad/main {})
;; (launchpad/main {:steps (into [(partial launchpad/ensure-java-version 17)]
;; launchpad/default-steps)})
deps.edn
You need a top-level deps.edn
, where you reference your sub-projects with
aliases and :local/root
.
{:deps
{... good place for dev tooling like portal, scope-capture ...}
;; Monorepo setup with two subprojects, if you have a multi-repo setup then use
;; paths like `"../proj1"`
:aliases
{:proj1
{:deps {com.example/proj1 {:local/root "proj1"}}}
:proj2
{:deps {com.example/proj2 {:local/root "proj2"}}}}}
proj1
and proj2
are then folders with their own deps.edn
, src
, etc.
.gitignore
Make sure to .gitignore
the deps.local.edn
file, this is where you can do
individual configuration.
echo deps.local.edn >> .gitignore
deps.local.edn
This follows the structure like deps.edn
, and gets passed to tools.deps as an
extra source, but there are a few special keys here that you can use to
configure launchpad.
{;; regular deps.edn stuff will work in here
:deps {}
:aliases {}
;; but some extra keys are supported to influence launchpad itself
:launchpad/aliases [:proj1] ; additional aliases, will be added to whatever
; aliases you specify on the command line
:launchpad/main-opts ["--emacs"] ; additional CLI flags, so you can encode your
; own preferences
:launchpad/shadow-build-ids [] ; which shadow builds to start, although it may
; be preferable to configure this as part of
; specific aliases in your main deps.edn
}
You don't have to stop there, you could add a dev/user.clj
(add "dev" to your
:paths
in that case), add other useful scripts or repl sessions, maybe you
even want to put cross-project integration tests in this repo, but the above is
the main stuff you need.
When invoking bin/launchpad
you pass it any aliases you want to start, plus a
number of optional flags. These currently allow injecting the CIDER and/or
refactor-nrepl middleware, which will suffice to use launchpad with Emacs/CIDER,
VS Code/Calva, and probably others.
Please do file issues on Github for your favorite editor environment, we want to eventually support every Clojure editor out there with a non-negligible user base.
Emacs is currently best supported, since we are able to query Emacs to find which versions of cider-nrepl and refactor-nrepl we should inject, and are also able to instruct Emacs to connect to the REPL, so the whole process is smooth and automated. This level of integration will not be possible with every editor, but we can look into what options we have.
➜ bin/launchpad --help
bin/launchpad <options> [proj1|proj2]+
-h, --help
-v, --verbose Print debug information
--cider-nrepl Include the CIDER nREPL middleware
--refactor-nrepl Include the refactor-nrepl middleware
--cider-connect Automatically connect CIDER
--emacs Shorthand for --cider-nrepl --refactor-nrepl --cider-connect
For example
➜ bin/launchpad backend frontend --emacs
[INFO] clojure -J-XX:-OmitStackTraceInFastThrow -J-Dlambdaisland.launchpad.aliases=backend,frontend -A:backend:frontend -Sdeps '{:deps {cider/cider-nrepl #:mvn{:version "0.28.5"}, refactor-nrepl/refactor-nrepl #:mvn{:version "3.5.2"}, com.lambdaisland/classpath #:mvn{:version "0.4.44"}, com.lambdaisland/launchpad #:local{:root "/home/arne/github/lambdaisland/launchpad"}}}' -M -e '(do (require (quote lambdaisland.classpath.watch-deps) (quote lambdaisland.launchpad.deps)) (lambdaisland.classpath.watch-deps/start! {:aliases [:backend :frontend], :include-local-roots? true, :basis-fn lambdaisland.launchpad.deps/basis, :watch-paths [(lambdaisland.classpath.watch-deps/canonical-path "deps.local.edn")], :launchpad/extra-deps (quote {cider/cider-nrepl #:mvn{:version "0.28.5"}, refactor-nrepl/refactor-nrepl #:mvn{:version "3.5.2"}, com.lambdaisland/classpath #:mvn{:version "0.4.44"}})}) (require (quote nrepl.cmdline)) (nrepl.cmdline/-main "--port" "41545" "--middleware" "[cider.nrepl/cider-middleware refactor-nrepl.middleware/wrap-refactor]"))'
nREPL server started on port 41545 on host localhost - nrepl://localhost:41545
At this point in Emacs you'll see this pop up:
[nREPL] Establishing direct connection to localhost:41545 ...
[nREPL] Direct connection to localhost:41545 established
For other editors connect to the given port manually.
launchpad is part of a growing collection of quality Clojure libraries created and maintained by the fine folks at Gaiwan.
Pay it forward by becoming a backer on our Open Collective, so that we may continue to enjoy a thriving Clojure ecosystem.
You can find an overview of our projects at lambdaisland/open-source.
Everyone has a right to submit patches to launchpad, and thus become a contributor.
Contributors MUST
- adhere to the LambdaIsland Clojure Style Guide
- write patches that solve a problem. Start by stating the problem, then supply a minimal solution.
*
- agree to license their contributions as MPL 2.0.
- not break the contract with downstream consumers.
**
- not break the tests.
Contributors SHOULD
- update the CHANGELOG and README.
- add tests for new functionality.
If you submit a pull request that adheres to these rules, then it will almost certainly be merged immediately. However some things may require more consideration. If you add new dependencies, or significantly increase the API surface, then we need to decide if these changes are in line with the project's goals. In this case you can start by writing a pitch, and collecting feedback on it.
*
This goes for features too, a feature needs to solve a problem. State the problem it solves, then supply a minimal solution.
**
As long as this project has not seen a public release (i.e. is not on Clojars)
we may still consider making breaking changes, if there is consensus that the
changes are justified.
Copyright © 2022 Arne Brasseur and Contributors
Licensed under the term of the Mozilla Public License 2.0, see LICENSE.