nREPL Server

If you’re into the clj command you can take advantage of nREPL’s built-in command-line interface (nrepl.cmdline).

Add this alias to ~/.clojure/deps.edn:

Then you can simply run the nREPL server in headless mode like this:

A good practice is to add whatever nREPL middleware you want to use to the nREPL profile, so you can easily activate them when needed. Here’s how you can easily start a ClojureScript capable nREPL:

By default, nREPL listens for connections on a randomly chosen local port with no authentication, but you can specify the address and port explicitly, or you can ask it to listen on a UNIX domain (filesystem) socket instead. This is supported natively on JDK 17 and newer; for earlier versions you need to add a junixsocket dependency:

Here’s a listing of all the options available via nREPL’s command-line interface (this output was simply generated with --help):

Leiningen has built-in support for nREPL. Just do:

And you’re all set. By default Leiningen will also connect to the running nREPL server using the popular command-line nREPL client REPL-y. If you don’t need the terminal REPL you can also start nREPL in headless mode:

This will start nREPL listening on localhost and a random port. You can specify the host and port explicitly like this:

Alternatively you can bind nREPL to a Unix domain socket like this:

You can also specify a lot of nREPL’s configuration options in the :repl profile in your project.clj file:

Refer to Leiningen’s sample.project.clj for an up-to-date version of those options.

The Clojurephant plugin provides Clojure/ClojureScript support for Gradle, including built-in nREPL support:

See Clojurephant’s docs for other configuration options.

Embedding nREPL in an existing Java application can also be useful - if your Java code allows for it you can still introspect values and call methods while the app is running. Since nREPL currently does not have a Java API, you’ll need to use Clojure’s interop features.

You can pull in the needed dependencies by adding this to your pom.xml:

A more complete example, including the use of custom middleware, can be found here.

The server port is written to .nrepl-port in the current working directory. Most Clojure editors — CIDER, Calva, Cursive, Conjure, and others — look for this file to auto-connect to a running nREPL server.

The file is registered for deletion on JVM shutdown (via File.deleteOnExit), so under normal circumstances it is cleaned up automatically when the server stops.

When using TLS with a local proxy, the proxy port is written to .nrepl-tls-proxy-port in the current working directory. See TLS for details on setting up TLS connections.

Since .nrepl-port is a transient runtime artifact, you should add it to your .gitignore (or equivalent):

Starting with version 0.5, you can configure certain aspects of the nREPL server’s behaviour via configuration files.

There are two configuration files:

The global configuration file is useful for setting options that you’d like to use for all the nREPL servers that you start (e.g. a common bind-address, transport, handler, etc).

The local configuration file should be placed in the directory from which you’re starting the server (normally the root directory of your project). Its purpose is to set project-specific settings (e.g. a common port you always want to use with a particular project). Any setting in .nrepl.edn will take precedence over a setting in .nrepl/nrepl.edn.

Here’s an example global configuration file:

And this is an example of a local config file:

The following keys are recognized in .nrepl.edn and ~/.nrepl/nrepl.edn:

Settings passed via the command-line interface replace configuration file settings by default. For example, if your config file specifies :middleware [a/mw1 a/mw2] and you pass --middleware "[b/mw3]" on the CLI, the resulting middleware will be just [b/mw3] — the config file values are lost.

Since version 1.6, you can use the ^:concat metadata on collection values to concatenate them instead of replacing. The metadata can be placed on either the config value or the CLI value — if either side carries ^:concat, the values are merged with into (config first, then CLI).

For example, given this config file:

And this CLI invocation:

The resulting middleware will be:

This is useful for ensuring certain middleware (e.g. company-wide monitoring or security middleware) is always loaded, even when development tools pass their own middleware via CLI flags.

You can use the server configuration file (either project-local or system-wide) to specify default values for dynamic variables. These defaults are applied when a new session is created (i.e. when a client connects). This serves two important purposes:

The format is a map from fully-qualified var symbols to their values:

You can configure any dynamic var whose namespace is loaded at server startup. This includes all of clojure.core and any namespace that your project or middleware loads eagerly.

nREPL sessions already bind a set of vars by default (with their current root values):

The :dynamic-vars config overrides these defaults and can also introduce additional vars. For example, you could set a project-local default for *print-length* to prevent accidental printing of large sequences:

By default, the server will exit with an error if any configured middleware cannot be resolved (i.e. its namespace isn’t on the classpath). Since version 1.6, middleware symbols can be marked with ^:optional metadata — if the middleware can’t be loaded, it is silently skipped and the server starts with the remaining middleware.

You can also use ^:optional from the command line:

This is useful when you share a single nREPL configuration across projects that don’t all have the same dependencies on the classpath. For instance, a global config can reference editor-specific middleware as optional so it works regardless of which projects include that dependency: