Leiningen — Automate Clojure Projects Without Losing Your Mind

Introduction

Leiningen is the most widely used build tool in the Clojure ecosystem. It handles the entire project lifecycle—from scaffolding a new project to managing dependencies, running tests, starting a REPL, and building deployable artifacts—all driven by a declarative project.clj file.

What Leiningen Does

• Resolves and downloads dependencies from Maven Central and Clojars repositories
• Scaffolds new projects from templates via lein new <template> <name>
• Launches a Clojure REPL with the project classpath fully configured
• Runs tests with lein test and generates reports
• Builds uberjars (standalone JARs with all dependencies bundled) for deployment

Architecture Overview

Leiningen is a Clojure application distributed as a shell script bootstrap. The bootstrap downloads the Leiningen core JAR on first run and delegates to it. Projects are configured through project.clj, a Clojure data structure. Dependency resolution uses Apache Maven's Aether library under the hood. Leiningen's plugin architecture allows the community to extend it with tasks for code formatting, Docker builds, ClojureScript compilation, and more.

Self-Hosting & Configuration

• Install by downloading the lein script and placing it on your PATH
• All project settings live in project.clj at the project root
• User-level settings go in ~/.lein/profiles.clj for global plugins and JVM options
• Repositories are configurable: add private Maven repos or S3-backed repositories
• JVM options are set via :jvm-opts in project.clj or via LEIN_JVM_OPTS environment variable

Key Features

• Template-based project creation with community templates for web apps, libraries, and more
• nREPL integration for connecting editors like Emacs (CIDER), IntelliJ (Cursive), and VS Code (Calva)
• Profile system for environment-specific configuration (dev, test, production)
• Plugin ecosystem covering tasks like lein-ring for web servers and lein-cljsbuild for ClojureScript
• Offline mode and local repository caching for reproducible builds without network access

Comparison with Similar Tools

• Clojure CLI (deps.edn) — official tool focused on dependency management; Leiningen provides a broader task runner and plugin system
• Boot — alternative Clojure build tool using a pipeline model; less widely adopted than Leiningen
• Maven — Java build tool; Leiningen wraps Maven's resolver but uses a simpler Clojure-native configuration
• Gradle — powerful but complex; Leiningen is purpose-built for Clojure with less configuration overhead

FAQ

Q: Should I use Leiningen or the official Clojure CLI? A: Leiningen is better for projects that need a full build lifecycle with plugins. The Clojure CLI is lighter and preferred for library development and simple dependency management.

Q: Can Leiningen build ClojureScript projects? A: Yes. Use the lein-cljsbuild plugin or lein-shadow (wrapping shadow-cljs) for ClojureScript compilation.

Q: Does Leiningen work with Java dependencies? A: Yes. Leiningen resolves dependencies from Maven Central and any Maven-compatible repository, so all Java libraries are accessible.

Q: How do I create a standalone executable? A: Run lein uberjar to produce a self-contained JAR file that includes all dependencies and can be run with java -jar.

Sources

• https://github.com/technomancy/leiningen
• https://leiningen.org