= nREPL Middleware Setup
:experimental:

NOTE: 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
https://github.com/clojure-emacs/cider-nrepl[nREPL middleware]. `cider-jack-in`
(kbd:[C-c C-x (C-)j (C-)j]) automatically injects this middleware and other
dependencies as required. But 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

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

[source,clojure]
----
:plugins [[cider/cider-nrepl "0.58.0"]]
----

A minimal `profiles.clj` for CIDER would be:

[source,clojure]
----
{:repl {:plugins [[cider/cider-nrepl "0.58.0"]]}}
----

WARNING: 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 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`.

[source,clojure]
----
  :cider-clj {:extra-deps {cider/cider-nrepl {:mvn/version "0.58.0"}}
              :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.58.0"}
                            cider/piggieback {:mvn/version "0.6.1"}}
               :main-opts ["-m" "nrepl.cmdline" "--middleware"
                           "[cider.nrepl/cider-middleware,cider.piggieback/wrap-cljs-repl]"]}
----

NOTE: the suggested ClojureScript setup is apt for e.g. library development, but not for frontend development.
For those cases, you may want to check out our xref:cljs/shadow-cljs.adoc#using-cider-connect-cljs[shadow-cljs]
or xref:cljs/figwheel.adoc#clojure-cli-setup[figwheel] setups instead.

=== Using Gradle

NOTE: Make sure you're using https://github.com/clojurephant/clojurephant[Clojurephant] 0.4.0 or newer.

.build.gradle
[source, groovy]
----
dependencies {
  devImplementation 'nrepl:nrepl:1.5.2'
  devImplementation 'cider:cider-nrepl:0.58.0'
}

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 https://clojurephant.dev[Clojurephant docs].

=== Using Maven

NOTE: 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.

[source,clojure]
----
(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`.

NOTE: CIDER and cider-nrepl projects are co-developed, but are not released in a
lock-step — they have differing versions. 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`. See also the
xref:about/compatibility.adoc#compatibility-matrix[compatibility
matrix].
