Skip to content
Tutorials Center
My learning

Topics

Lesson 31 of 36 ยท Tooling and Interop

Leiningen and deps.edn

Set up Clojure projects with Leiningen and the official Clojure CLI: project.clj, deps.edn, aliases, dependencies, running, testing, building an uberjar and choosing a tool.

A Clojure program is not just a file: it has dependencies (libraries from Maven Central and Clojars), a source layout, entry points, tests and a build. Two tools dominate. Leiningen (lein) has been the standard since 2010 and is driven by project.clj. The Clojure CLI (clj/clojure) is the official tool from the Clojure core team and is driven by deps.edn. Both download JVM libraries and start the same Clojure.

The standard project layout

TEXT
my-app/
  deps.edn            (or project.clj)
  src/
    my_app/
      core.clj
  test/
    my_app/
      core_test.clj
  resources/

Namespace my-app.core lives in src/my_app/core.clj: dashes in namespace names become underscores in file names, and each segment is a directory. Getting this mapping wrong is the most common reason for "Could not locate my_app/core__init.class" errors.

CLOJURE
(ns my-app.core
  (:require [clojure.string :as str])
  (:gen-class))

(defn greet [name]
  (str "Hello, " (str/capitalize name) "!"))

(defn -main [& args]
  (println (greet (or (first args) "world"))))

-main is the conventional entry point and (:gen-class) lets it be started as a Java main class in a compiled jar.

Leiningen: project.clj

CLOJURE
(defproject my-app "0.1.0-SNAPSHOT"
  :description "A sample app"
  :dependencies [[org.clojure/clojure "1.12.0"]
                 [ring/ring-core "1.12.2"]]
  :main my-app.core
  :profiles {:dev {:dependencies [[org.clojure/test.check "1.1.1"]]}
             :uberjar {:aot :all}})

Dependencies are [group/artifact "version"] vectors. Profiles merge extra settings: :dev is active while developing, :uberjar while packaging. Common commands:

Command Does
lein new app my-app create a project skeleton
lein repl start a REPL with your project loaded
lein run -- arg run -main
lein test run all tests
lein uberjar build a standalone jar with dependencies
lein deps :tree show the resolved dependency tree

Leiningen is mature and has a large plugin ecosystem (for example lein-ring, lein-ancient for checking outdated versions).

The Clojure CLI: deps.edn

deps.edn is plain EDN data (a map), with no code in it.

CLOJURE
{:paths ["src" "resources"]

 :deps {org.clojure/clojure {:mvn/version "1.12.0"}
        ring/ring-core      {:mvn/version "1.12.2"}
        com.github.user/lib {:git/url "https://github.com/user/lib"
                             :git/sha "abc123..."}}

 :aliases
 {:dev  {:extra-paths ["dev"]}
  :test {:extra-paths ["test"]
         :extra-deps  {io.github.cognitect-labs/test-runner
                       {:git/tag "v0.5.1" :git/sha "dfb30dd"}}
         :main-opts   ["-m" "cognitect.test-runner"]}
  :run  {:main-opts ["-m" "my-app.core"]}}}

Key ideas:

  • :paths lists source directories; :deps maps a library name to a coordinate. Besides Maven (:mvn/version), a dependency can be a git repository pinned to a SHA, or a local directory (:local/root), which is great for sharing code without publishing.
  • Aliases bundle extra paths, dependencies and options. Activate them with -M:alias (run main), -X:alias (call a function), or -A:alias (just modify the classpath for a REPL).
TEXT
clj                       # start a REPL
clj -M:run Ada            # run -main with the :run alias
clj -M:test               # run tests
clj -X:build uber         # call a function from the :build alias
clj -Stree                # print the dependency tree

-M is for programs that use -m/-main style options; -X runs a function by name with key/value arguments (clj -X my-app.core/greet :name '"Ana"'), which is the modern style for tools.

The CLI resolves versions once and caches the computed classpath in a .cpcache/ directory. When two libraries need different versions of the same dependency, the CLI picks the newest version by default.

Building and packaging

Leiningen packages with lein uberjar. With the CLI you typically add a build library, tools.build, and write a small build.clj that cleans a target directory, compiles and creates an uberjar:

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

(def basis (delay (b/create-basis {:project "deps.edn"})))

(defn uber [_]
  (b/copy-dir {:src-dirs ["src"] :target-dir "target/classes"})
  (b/compile-clj {:basis @basis :src-dirs ["src"] :class-dir "target/classes"})
  (b/uber {:class-dir "target/classes" :uber-file "target/app.jar" :basis @basis
           :main 'my-app.core}))

Run it with clj -T:build uber (after an alias :build pointing at tools.build). The result runs anywhere with Java: java -jar target/app.jar.

Leiningen or deps.edn?

Leiningen Clojure CLI (deps.edn)
Configuration project.clj (code, can run plugins) deps.edn (data only)
Plugins many few; use aliases and tools
Git dependencies via plugins built in
Philosophy all-in-one tool small composable parts
Popularity classic, many tutorials the official, growing default

Both are fine. Many new projects use deps.edn; many established ones use Leiningen. Concepts transfer: dependencies, source paths, profiles/aliases and an entry point.

Other useful tools

  • Calva, Cursive, CIDER are editor integrations that give you an interactive REPL (see testing, spec and the REPL).
  • clj-kondo is a fast linter; cljfmt formats code.
  • Babashka runs Clojure scripts with near-instant startup, great for scripting.

Try it: resolving versions

Version conflict resolution is the part of a dependency tool that surprises people. This stand-in implements the CLI's rule "newest version wins" over a tiny dependency graph, and reads an alias map the way -A:dev merges it.

JS A mini dependency resolver

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Try it: namespace to file path

JS Namespace name to file path

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where does the namespace my-app.core live?

    Dots become directories and dashes become underscores in file names.
  2. 2. What kind of file is deps.edn?

    deps.edn is data only; behavior comes from aliases and external tools.
  3. 3. Which flag runs a main namespace with an alias from the Clojure CLI?

    -M uses clojure.main options (:main-opts); -X calls a function by name.
  4. 4. What does the Clojure CLI do when two dependencies need different versions of a library?

    The CLI's default conflict rule is to choose the newest version found.

Summary

  • A project has source and test directories whose paths mirror namespace names (dots to slashes, dashes to underscores).
  • Leiningen uses project.clj with profiles and plugins; the Clojure CLI uses data-only deps.edn with aliases.
  • deps.edn supports Maven, git and local dependencies; -M, -X and -A pick how an alias is used.
  • Build jars with lein uberjar or tools.build.
  • Both tools are good; the concepts carry over between them.

Next: Java Interop