1= nREPL Middleware Setup
2:experimental:
3
4NOTE: You can skip this section if you don't plan to use `cider-connect` or don't care
5about the advanced functionality that requires `cider-nrepl`.
6
7Much of CIDER's functionality depends on its own https://github.com/clojure-emacs/cider-nrepl[nREPL
8middleware]. Starting
9with version 0.11, `cider-jack-in` (kbd:[C-c C-x (C-)j (C-)j])
10automatically injects this middleware and other dependencies as required.
11
12NOTE: In the past, if you were setting up CIDER, you might have had to
13modify `profiles.clj` or `profile.boot`. CIDER now handles
14everything automatically and you don't need to add anything
15special to these files. The same is true of your `deps.edn` file.
16
17If you prefer a standalone REPL, you will need to invoke
18`cider-connect` instead of `cider-jack-in` and manually add the
19dependencies to your Clojure project (explained in the following
20sections).
21
22== Setting Up a Standalone REPL
23
24=== Using Leiningen
25
26NOTE: Make sure you're using Leiningen 2.9.0 or newer, as 2.9.0 is the first
27release to ship with nREPL 0.6.
28
29Use the convenient plugin for defaults, either in your project's
30`project.clj` file or in the :repl profile in `~/.lein/profiles.clj`.
31
32[source,clojure]
33----
34:plugins [[cider/cider-nrepl "x.y.z"]]
35----
36
37A minimal `profiles.clj` for CIDER would be:
38
39[source,clojure]
40----
41{:repl {:plugins [[cider/cider-nrepl "0.25.2"]]}}
42----
43
44WARNING: Be careful not to place this in the `:user` profile, as this way CIDER's
45middleware will always get loaded, causing `lein` to start slower.  You really
46need it just for `lein repl` and this is what the `:repl` profile is for.
47
48=== Using Boot
49
50NOTE: Make sure you're using Boot 2.8.3 or newer, as 2.8.3 is the first
51release to ship with nREPL 0.6.
52
53Boot users can configure the tool to include the middleware automatically in
54all of their projects using a `~/.boot/profile.boot` file like so:
55
56[source,clojure]
57----
58(require 'boot.repl)
59
60(swap! boot.repl/*default-dependencies*
61       concat '[[cider/cider-nrepl "0.25.2"]])
62
63(swap! boot.repl/*default-middleware*
64       conj 'cider.nrepl/cider-middleware)
65----
66
67For more information visit https://github.com/boot-clj/boot/wiki/Cider-REPL[boot-clj wiki].
68
69=== Using tools.deps
70
71You can add the following aliases to your deps.edn in order to launch
72a standalone Clojure(Script) nREPL server with CIDER middleware from
73the commandline with something like `clj -A:cider-clj`. Then from emacs
74run `cider-connect` or `cider-connect-cljs`.
75
76[source,clojure]
77----
78  :cider-clj {:extra-deps {cider/cider-nrepl {:mvn/version "0.22.4"}}
79              :main-opts ["-m" "nrepl.cmdline" "--middleware" "[cider.nrepl/cider-middleware]"]}
80
81  :cider-cljs {:extra-deps {org.clojure/clojurescript {:mvn/version "1.10.339"}
82                            cider/cider-nrepl {:mvn/version "0.22.4"}
83                            cider/piggieback {:mvn/version "0.5.1"}}
84               :main-opts ["-m" "nrepl.cmdline" "--middleware"
85                           "[cider.nrepl/cider-middleware,cider.piggieback/wrap-cljs-repl]"]}
86----
87
88=== Using Gradle
89
90NOTE: This section is currently a stub. Contributions welcome!
91
92=== Using Maven
93
94NOTE: This section is currently a stub. Contributions welcome!
95
96== Using Embedded nREPL Server
97
98If you're embedding nREPL in your application, you'll have to start the
99server with CIDER's own nREPL handler.
100
101[source,clojure]
102----
103(ns my-app
104  (:require [nrepl.server :as nrepl-server]
105            [cider.nrepl :refer (cider-nrepl-handler)]))
106
107(defn -main
108  []
109  (nrepl-server/start-server :port 7888 :handler cider-nrepl-handler))
110----
111
112It goes without saying that your project should depend on `cider-nrepl`.
113
114NOTE: Prior to CIDER 0.18, CIDER and cider-nrepl were always released together
115and their versions had to match for things to work (e.g. CIDER 0.15 required
116cider-nrepl 0.15). But as the prominence of cider-nrepl grew and many other
117tools started using it, the two projects evolved separately and are no longer in
118tight lock-step. Usually, any recent version of cider-nrepl should be (mostly)
119compatible with a recent version of CIDER. You can check the required version of
120cider-nrepl for your version of CIDER by looking at
121`cider-required-middleware-version`.
122