nREPL Middleware Setup

You can skip this section if you don’t plan to use cider-connect or don’t care about the advanced functionality that requires cider-nrepl.

Much of CIDER’s functionality depends on its own nREPL middleware. Starting with version 0.11, cider-jack-in (C-c C-x (C-)j (C-)j) automatically injects this middleware and other dependencies as required.

In the past, if you were setting up CIDER, you might have had to modify profiles.clj or profile.boot. CIDER now handles everything automatically and you don’t need to add anything special to these files. The same is true of your deps.edn file and your build.gradle (as of Clojurephant 0.7.0-alpha.6).

If you prefer a standalone REPL, you will need to invoke cider-connect instead of cider-jack-in and manually add the dependencies to your Clojure project (explained in the following sections).

Setting Up a Standalone REPL

Using Leiningen

Make sure you’re using Leiningen 2.9.0 or newer, as 2.9.0 is the first release to ship with nREPL 0.6.

Use the convenient plugin for defaults, either in your project’s project.clj file or in the :repl profile in ~/.lein/profiles.clj.

:plugins [[cider/cider-nrepl "x.y.z"]
          [mx.cider/enrich-classpath "x.y.z"]]

enrich-classpath is a library (and Leiningen plugin) that, as its main feature, automatically downloads all available .jars with Java sources and javadocs for a given project, so that various tools (e.g. CIDER) can access it. Simply put - it allows you to navigate to Java sources and javadocs in your Clojure projects.

enrich-classpath has a bit of a startup cost associated with it, the first time Java sources and javadocs are fetched. It can be turned off by setting cider-enrich-classpath to nil.

A minimal profiles.clj for CIDER would be:

{:repl {:plugins [[cider/cider-nrepl "0.28.5"]
                  [mx.cider/enrich-classpath "1.9.0"]]}}

Be careful not to place this in the :user profile, as this way CIDER’s middleware will always get loaded, causing lein to start slower. You really need it just for lein repl and this is what the :repl profile is for.

Using Boot

Make sure you’re using Boot 2.8.3 or newer, as 2.8.3 is the first release to ship with nREPL 0.6.

Boot users can configure the tool to include the middleware automatically in all of their projects using a ~/.boot/profile.boot file like so:

(require 'boot.repl)

(swap! boot.repl/*default-dependencies*
       concat '[[cider/cider-nrepl "0.25.2"]])

(swap! boot.repl/*default-middleware*
       conj 'cider.nrepl/cider-middleware)

For more information visit boot-clj wiki.

Using tools.deps

You can add the following aliases to your deps.edn in order to launch a standalone Clojure(Script) nREPL server with CIDER middleware from the commandline with something like clj -A:cider-clj. Then from emacs run cider-connect or cider-connect-cljs.

  :cider-clj {:extra-deps {cider/cider-nrepl {:mvn/version "0.22.4"}}
              :main-opts ["-m" "nrepl.cmdline" "--middleware" "[cider.nrepl/cider-middleware]"]}

  :cider-cljs {:extra-deps {org.clojure/clojurescript {:mvn/version "1.10.339"}
                            cider/cider-nrepl {:mvn/version "0.22.4"}
                            cider/piggieback {:mvn/version "0.5.1"}}
               :main-opts ["-m" "nrepl.cmdline" "--middleware"
                           "[cider.nrepl/cider-middleware,cider.piggieback/wrap-cljs-repl]"]}

Using Gradle

Make sure you’re using Clojurephant 0.4.0 or newer.

build.gradle

dependencies {
  devImplementation 'nrepl:nrepl:0.9.0'
  devImplementation 'cider:cider-nrepl:0.28.5'
}

tasks.named('clojureRepl') {
  middleware = ['cider.nrepl/cider-middleware']
}

You can then launch the nREPL server from the command line via: ./gradlew clojureRepl.

For more information, see the Clojurephant docs.

Using Maven

This section is currently a stub. Contributions welcome!

Using Embedded nREPL Server

If you’re embedding nREPL in your application, you’ll have to start the server with CIDER’s own nREPL handler.

(ns my-app
  (:require [nrepl.server :as nrepl-server]
            [cider.nrepl :refer (cider-nrepl-handler)]))

(defn -main
  []
  (nrepl-server/start-server :port 7888 :handler cider-nrepl-handler))

It goes without saying that your project should depend on cider-nrepl.

Prior to CIDER 0.18, CIDER and cider-nrepl were always released together and their versions had to match for things to work (e.g. CIDER 0.15 required cider-nrepl 0.15). But as the prominence of cider-nrepl grew and many other tools started using it, the two projects evolved separately and are no longer in tight lock-step. Usually, any recent version of cider-nrepl should be (mostly) compatible with a recent version of CIDER. You can check the required version of cider-nrepl for your version of CIDER by looking at cider-required-middleware-version.