nREPL Server

Starting a server

There are many ways to start an nREPL server. Most often you’d start it using some build tool, but you can also embed the server in your application and start it from it. Here we’ll outline the most popular options available for you today.

Using Clojure CLI tools

This section assumes you’re using Clojure 1.9+ and nREPL 0.4.4+.

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:

{
;; ...
:aliases {:nREPL
          {:extra-deps
            {nrepl/nrepl {:mvn/version "0.5.3"}}}}
}

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

$ clj -R:nREPL -m nrepl.cmdline

A good practice is 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:

{
;; ...
:aliases {:nREPL
          {:extra-deps
           {nrepl/nrepl {:mvn/version "0.5.3"}
            cider/piggieback {:mvn/version "0.3.8"}}}}
}
$ clj -R:nREPL -m nrepl.cmdline --middleware "[cider.piggieback/wrap-cljs-repl]"

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

-i/--interactive            Start nREPL and connect to it with the built-in client.
-c/--connect                Connect to a running nREPL with the built-in client.
-C/--color                  Use colors to differentiate values from output in the REPL. Must be combined with --interactive.
-b/--bind ADDR              Bind address, by default "127.0.0.1".
-h/--host ADDR              Host address to connect to when using --connect. Defaults to "127.0.0.1".
-p/--port PORT              Start nREPL on PORT. Defaults to 0 (random port) if not specified.
--ack ACK-PORT              Acknowledge the port of this server to another nREPL server running on ACK-PORT.
-n/--handler HANDLER        The nREPL message handler to use for each incoming connection; defaults to the result of `(nrepl.server/default-handler)`.
-m/--middleware MIDDLEWARE  A sequence of vars, representing middleware you wish to mix in to the nREPL handler.
-t/--transport TRANSPORT    The transport to use. By default that's `nrepl.transport/bencode`.
--help                      Show this help message.

Using Leiningen

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

$ lein repl

And you’re all set. By default Lein 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:

$ lein repl :headless

Using Boot

Boot is a popular alternative to Leiningen, that also has build-in support for nREPL:

$ boot repl

Embedding nREPL

All the above options are typically used during the development of an application. It can also be extremely useful to have your application host a REPL server whereever it might be deployed; this can greatly simplify debugging, sanity-checking, panicked code patching, and so on.

You should think long and hard before hot-patching code in production, but that’s a subject for an unrelated discussion.

nREPL provides a socket-based server that you can trivially start from your application. Add it to your project’s dependencies, and add code like this to your app:

=> (require '[nrepl.server :refer [start-server stop-server]])
nil
=> (defonce server (start-server :port 7888))
='user/server

If you want your nREPL server to listen on a particular address instead of the default one, you can use the :bind keyword to specify the address to listen on. E.g., to make the nREPL server listen on address 172.18.0.5 and port 4001:

=> (require '[nrepl.server :refer [start-server stop-server]])
nil
=> (defonce server (start-server :bind "172.18.0.5" :port 4001))
='user/server
Keep in mind that running a nREPL server on a public address is an epic security hole! As the connections are insecure (no authentication, no authorization) by default anyone can connect to your app and modify its behaviour or run code on the remote host.

Depending on what the lifecycle of your application is, whether you want to be able to easily restart the server, etc., you might want to put the value start-server returns into an atom or somesuch. Anyway, once your app is running an nREPL server, you can connect to it from a tool like Leiningen or Counterclockwise or REPL-y, or from another Clojure process, as shown here.

You can stop the server with (stop-server server).

Server options

Note that nREPL is not limited to its default messaging protocol, nor to its default use of sockets. nREPL provides a transport abstraction for implementing support for alternative protocols and connection methods. Alternative transport implementations are available, and implementing your own is not difficult; read more about transports here.

Server Configuration

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

There are two configuration files:

  • Global configuration file .nrepl/nrepl.edn

  • Local configuration file .nrepl.edn

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).

You can alter the location of the global configuration file via the environment variable NREPL_CONFIG_DIR.

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 it 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:

nrepl/nrepl.edn
{:bind         "::"
 :transport    "nrepl.transport/tty"
 :middleware   ["some.ns/mw1" "some.ns/mw1"]}
You can refer to vars either as strings or symbols.

And this is an example of a local config file:

nrepl.edn
{:bind         "localhost"
 :port         12345
 :ack          23456
 :handler      "some.ns/awesome-handler"
 :transport    "nrepl.transport/bencode"}
At the time of this writing Boot and Leiningen don’t honor the new configuration files. They are current leveraged only by the built-in command-line interface.