Integrating the REPL with Build Tools

For a Java engineer, the phrase “REPL integration” can sound vague until you see what the build tool is actually doing.

In Clojure, your build tool is not just packaging code. It usually decides:

• which source and resource paths are on the classpath
• which dependencies are available
• which JVM options apply
• whether REPL middleware gets injected
• whether your editor can connect to the running process cleanly

So the REPL is not separate from build tooling. The build tool is often what makes the REPL useful in the first place.

The Core Mental Model

Think of it this way:

• the REPL is the live execution surface
• the build tool defines the environment that surface runs inside

If the classpath is wrong, the REPL feels broken.

If the development aliases or profiles are wrong, hot reloading and editor commands feel broken.

If the middleware is missing, editor integrations lose much of their power.

This is why REPL setup in Clojure matters more than launching a one-off shell.

Terminal REPLs And Editor REPLs Are Different Shapes

The first distinction to keep clear is:

• a plain terminal REPL
• an editor-connected REPL

A plain terminal REPL is often just clojure.main running in your terminal.

An editor REPL is usually richer. It commonly involves:

• an nREPL or socket REPL server
• middleware for editor features
• commands to load forms, files, or namespaces from the editor

That is why “it works in the terminal” and “it works from my editor” are related but not identical states.

Using The Clojure CLI And deps.edn

In a deps.edn project, the most basic project REPL is started from the project root with:

1clj

That gives you a REPL with the project’s classpath.

If you need extra development paths or tools, put them in aliases instead of depending on a pile of manual REPL steps. For example, a :dev alias might add:

• dev source paths
• test paths
• extra development-only libraries

Then the development REPL becomes something explicit and repeatable, such as:

1clj -M:dev

The important lesson is not the exact command. It is that the project owns the classpath shape.

That makes the environment reproducible for:

• you tomorrow
• other engineers
• editor integrations

Using Leiningen

Leiningen gives you the same broad benefit through a different project model.

Inside a Leiningen project, this command starts a REPL with the project dependencies and source code available:

1lein repl

Leiningen centers configuration in project.clj, so the REPL environment often reflects:

• :dependencies
• source and test paths
• profiles
• :repl-options

For a Java developer, this often feels closer to Maven or Gradle thinking: one file shapes the project, and the tool launches an environment derived from that file.

The big practical point is the same as with deps.edn: if your REPL depends on hidden local setup, the workflow will drift and eventually break.

Build Tools Should Encode Development, Not Just Packaging

A common beginner mistake is to think the build tool only matters at packaging time.

In Clojure, that is too narrow.

A healthy project usually encodes development concerns in the tool configuration too:

• dev-only dependencies
• test paths
• JVM flags
• startup helpers
• profiles or aliases for common tasks

That is what makes a project REPL trustworthy.

Without that, you end up with private terminal rituals that nobody else can replay.

Editor Integrations Usually Depend On REPL Middleware

Once you move from a plain terminal REPL to an editor workflow, middleware becomes important.

Tools such as Calva and CIDER commonly rely on an nREPL server plus cider-nrepl middleware to support features like:

• evaluating the form at point
• loading the current file
• switching namespaces
• code completion
• inline docs and inspection
• namespace refresh commands

This is why “jack in” matters in editor docs. Jack-in usually means:

• start the right kind of REPL for the project
• inject the needed middleware
• connect the editor automatically

That is much more reliable than manually starting random processes and hoping the editor can guess what you meant.

A Good Project Usually Has More Than One REPL Shape

In practice, serious projects often need at least two REPL shapes:

• a minimal project REPL for quick experiments
• a development REPL with extra paths, helpers, and reload support

Sometimes there is also a third:

• an application-attached REPL for a running web server or service

Trying to force one REPL shape to do everything is often what makes the workflow feel fragile.

Instead, define the shapes intentionally.

Keep A dev Namespace For Repeatable Startup

No build tool can save a workflow that still requires twenty manual steps after the REPL starts.

A strong pattern is to pair the build-tool setup with a small dev namespace containing helper functions such as:

• start
• stop
• restart
• test-system

That gives the REPL a stable control surface for your application.

The build tool answers:

• what code and libraries are available?

The dev namespace answers:

• how do I drive this running system during development?

Those two pieces belong together.

How This Compares To Java Tooling

Java developers are used to builds being oriented around:

• compile
• test
• package
• run

Clojure projects still need those things, but the development center of gravity is different. The build configuration is often judged by a more immediate question:

• does it give me a fast, trustworthy REPL workflow?

That shift is part of why Clojure teams care so much about classpath clarity, dev aliases, namespace reload behavior, and editor integration.

A Practical Decision Table

The exact commands matter less than the repeatable structure behind them.

Knowledge Check