Usage

Prerequisites

cider-nrepl supports only Clojure(Script) 1.8+ and Java 8+.

Leiningen users will need to have version 2.8.3 or newer installed. Boot users will need to have version 2.8.2 or newer installed.

Via Leiningen

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

:plugins [[cider/cider-nrepl "0.26.0"]]

A minimal profiles.clj for CIDER would be:

{:user {:plugins [[cider/cider-nrepl "0.26.0"]]}}

Or (if you know what you’re doing) add cider-nrepl to your :dev :dependencies vector plus specific middleware to :nrepl-middleware under :repl-options.

:dependencies [[cider/cider-nrepl "0.26.0"]]
:repl-options {:nrepl-middleware
                 [cider.nrepl/wrap-apropos
                  cider.nrepl/wrap-classpath
                  cider.nrepl/wrap-clojuredocs
                  cider.nrepl/wrap-complete
                  cider.nrepl/wrap-debug
                  cider.nrepl/wrap-format
                  cider.nrepl/wrap-info
                  cider.nrepl/wrap-inspect
                  cider.nrepl/wrap-macroexpand
                  cider.nrepl/wrap-ns
                  cider.nrepl/wrap-spec
                  cider.nrepl/wrap-profile
                  cider.nrepl/wrap-refresh
                  cider.nrepl/wrap-resource
                  cider.nrepl/wrap-stacktrace
                  cider.nrepl/wrap-test
                  cider.nrepl/wrap-trace
                  cider.nrepl/wrap-out
                  cider.nrepl/wrap-undef
                  cider.nrepl/wrap-version
                  cider.nrepl/wrap-xref]}

Via Boot

Boot users can configure the injected middleware by either specifying it on the command line through the cider.tasks/add-middleware task (the lenghty command below will include the apropos and version functionality):

boot -d nrepl:0.7.0 -d cider/cider-nrepl:0.26.0 -i "(require 'cider.tasks)" cider.tasks/add-middleware -m cider.nrepl.middleware.apropos/wrap-apropos -m cider.nrepl.middleware.version/wrap-version repl --server wait

Or for all of their projects by adding a ~/.boot/profile.boot file like so:

(set-env! :dependencies '[[nrepl "0.7.0"]
                          [cider/cider-nrepl "0.26.0"]])

(require '[cider.tasks :refer [add-middleware]])

(task-options! add-middleware {:middleware '[cider.nrepl.middleware.apropos/wrap-apropos
                                             cider.nrepl.middleware.version/wrap-version]})

And then launching boot add-middleware repl --server wait.

Note that this is not necessary when using the standard cider-jack-in.

For more information visit boot-clj wiki.

Via clj

clj was introduced in Clojure 1.9.

You can easily boot an nREPL server with the CIDER middleware loaded with the following "magic" incantation:

clj -Sdeps '{:deps {cider/cider-nrepl {:mvn/version "0.26.0"} }}' -m nrepl.cmdline --middleware "[cider.nrepl/cider-middleware]"

There are also two convenient aliases you can employ:

{...
 :aliases
 {:cider-clj {:extra-deps {org.clojure/clojure {:mvn/version "1.10.1"}
                           cider/cider-nrepl {:mvn/version "0.26.0"}}
              :main-opts ["-m" "nrepl.cmdline" "--middleware" "[cider.nrepl/cider-middleware]"]}

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

Which then allow you to simply run:

clj -A:cider-clj

Via embedding nREPL in your application

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

There’s nothing magical about the cider-nrepl-handler - all it does is to add all middleware defined in cider-nrepl to nREPL’s default handler. That’s how CIDER’s nREPL handler is created:

(def cider-middleware
  '[cider.nrepl/wrap-apropos
    cider.nrepl/wrap-classpath
    cider.nrepl/wrap-clojuredocs
    cider.nrepl/wrap-complete
    cider.nrepl/wrap-content-type
    cider.nrepl/wrap-debug
    cider.nrepl/wrap-enlighten
    cider.nrepl/wrap-format
    cider.nrepl/wrap-info
    cider.nrepl/wrap-inspect
    cider.nrepl/wrap-macroexpand
    cider.nrepl/wrap-ns
    cider.nrepl/wrap-out
    cider.nrepl/wrap-slurp
    cider.nrepl/wrap-profile
    cider.nrepl/wrap-refresh
    cider.nrepl/wrap-resource
    cider.nrepl/wrap-spec
    cider.nrepl/wrap-stacktrace
    cider.nrepl/wrap-test
    cider.nrepl/wrap-trace
    cider.nrepl/wrap-tracker
    cider.nrepl/wrap-undef
    cider.nrepl/wrap-version
    cider.nrepl/wrap-xref])

(def cider-nrepl-handler
  "CIDER's nREPL handler."
  (apply nrepl-server/default-handler (map resolve-or-fail cider-middleware)))

You can build your own custom nREPL handler with the middleware you need by adjusting the code above.

With JBoss AS/JBoss EAP/WildFly

Using the advanced features of the info middleware with one of the JBoss application servers requires a tweak, since JBoss modules prevent modifications to AppClassLoader (usually the highest modifiable classloader) from being seen by application code. To work around this, run the following code from within your application to mark that classloader as unmodifiable, and cause the lower level clojure.lang.DynamicClassLoader to be used instead. This code must execute prior to loading the cider-nrepl middleware. Note that this is only if you are deploying a standard WAR file to the application server directly. If you are using Immutant (1.x or 2.x), you won’t need to do this.

(require '[dynapath.dynamic-classpath :as cp])

(extend sun.misc.Launcher$AppClassLoader
  cp/DynamicClasspath
  (assoc cp/base-readable-addable-classpath
    :classpath-urls #(seq (.getURLs %))
    :can-add? (constantly false)))