Up and Running

To use CIDER, you’ll need to connect it to a running nREPL server that is associated with your program. Most Clojure developers use standard build tooling such as Leiningen, Boot, or Gradle, and CIDER can automatically work with those tools to get you up and running quickly. But those tools are not required; CIDER can connect to an nREPL server that is already started and is managed separately.

CIDER will automatically work with Leiningen 2.9.0+ or Boot 2.8.3+. Older versions are not supported.

There are two ways to connect CIDER to an nREPL server:

  1. CIDER can launch an nREPL server for your project from Emacs.

  2. You can connect CIDER to an already-running nREPL server, managed separately.

The following sections describe each of these methods.

Launch an nREPL Server From Emacs

If you have a Clojure project in your file system and want CIDER to launch an nREPL session for it, simply visit a file that belongs to the project, and type M-x cider-jack-in RET.[1] CIDER will start an nREPL server and automatically connect to it.

In Clojure(Script) buffers the command cider-jack-in is bound to C-c C-x (C-)j (C-)j.

The process of jacking-in is pretty simple:

  • CIDER determines the build system for your project (e.g. Leiningen) and picks the necessary command to start an nREPL server.

  • CIDER shells out and runs a command like lein repl :headless to start an nREPL server.

  • CIDER waits for the nREPL server to start. CIDER figures out this by parsing the output from the command and waiting for a line like nREPL server started on port 53005 on host localhost - nrepl://localhost:53005 to appear there.

  • CIDER extracts the port of the nREPL from the preceding message.

  • It connects to the running nREPL server.

You can see the exact command that cider-jack-in invoked in your minibuffer, while waiting for nREPL to start. You can also find this command in Emacs’s *Messages* buffer.

In some cases one project might have multiple project markers in it - e.g. project.clj and deps.edn. When this happens CIDER will prompt you to select the build tool to use. You can override this behavior by setting the variable cider-preferred-build-tool. While you can set it globally in your Emacs config, most of the time you’d probably want to have a project-specific setting for it in your .dir-locals.el:

((clojure-mode
  (cider-preferred-build-tool . lein)))
cider-jack-in is mainly designed for local development (with files on a local machine and the nREPL process running on the same machine). It does support various common remote/container scenarios, as documented later in this section. Due to the large variation of remote scenarios it cannot support all of them, so in some cases a manual nREPL start and usage of cider-connect might be a better option.

Auto-Injecting Dependencies

While CIDER’s core functionality requires nothing more than an nREPL server, there are many advanced features that depend on the presence of additional nREPL middleware. In the early versions of CIDER (up to CIDER 0.11) users had to add those dependencies themselves, which was a painful and error-prone process. Fortunately today that’s handled auto-magically when you’re using cider-jack-in.

If your project uses lein, boot or tools.deps (deps.edn), CIDER will automatically inject all the necessary nREPL dependencies (e.g. cider-nrepl or piggieback) when it starts the server. The injection process is extremely simple - CIDER simply passes the extra dependencies and nREPL configuration to your build tool in the command it runs to start the nREPL server. Here’s how this looks for tools.deps:

$ clojure -Sdeps '{:deps {nrepl {:mvn/version "0.6.0"} cider/cider-nrepl {:mvn/version "0.48.0"}}}' -m nrepl.cmdline --middleware '["cider.nrepl/cider-middleware"]'
If you don’t want cider-jack-in to inject dependencies automatically, set cider-inject-dependencies-at-jack-in to nil. Note that you’ll have to setup the dependencies yourself (see nREPL Middleware Setup), just as in CIDER 0.10 and older.

Normally cider-jack-in would inject only cider-nrepl and cider-jack-in-cljs would add piggieback as well. The injection mechanism is configurable and you can easily add more libraries there. Some CIDER extensions would use this mechanism to auto-inject their own dependencies.

Here’s how you can modify the injected dependencies for cider-jack-in-clj:

;; auto-inject version 1.0 of the library foo/bar
(cider-add-to-alist 'cider-jack-in-dependencies
                    "foo/bar" "1.0")
;; if you want to have full control over the coordinate description set it as an alist
;; auto-inject {:git/sha "6ae2b6f71773de7549d7f22759e8b09fec27f0d9" for library org.clojure/tools.deps
;;              :git/url "https://github.com/clojure/tools.deps/"}
(cider-add-to-alist 'cider-jack-in-dependencies
                    "org.clojure/tools.deps"
                    '(("git/sha" . "6ae2b6f71773de7549d7f22759e8b09fec27f0d9")
                      ("git/url" . "https://github.com/clojure/tools.deps/")))
Always use the fully qualified group/artifact (e.g. re-frame/re-frame) in these dependencies, since only Leiningen supports the bare re-frame syntax.

CIDER will also inject the most recent version of nREPL that it supports. This is a simple trick to override the version of nREPL bundled with your build tool (e.g. Leiningen), so you can gain access to the newest nREPL features. Generally that’s one aspect of CIDER’s inner workings that end-users will rarely have to think about.

You can override the injected versions of cider-nrepl and nREPL by customizing cider-injected-middleware-version and cider-injected-nrepl-version. Generally you should avoid doing this, but it may be useful if you want to try a newer version or you encounter some regression that forces you to temporarily use an older version.

CIDER can also inject a Clojure dependency into your project, which is useful, for example, if your project defaults to an older version of Clojure than that supported by the CIDER middleware. Set cider-jack-in-auto-inject-clojure appropriately to enable this.

Jacking-in without a Project

If you try to run cider-jack-in outside a project directory, CIDER will warn you and ask you to confirm whether you really want to do this; more often than not, this is an accident. If you decide to proceed, CIDER will invoke the command configured in cider-jack-in-default. Prior to CIDER 0.17, this defaulted to lein but was subsequently switched to clj, Clojure’s basic startup command.

You can set cider-allow-jack-in-without-project to t if you’d like to disable the warning displayed when jacking-in outside a project.

Universal jack-in

cider-jack-in-universal C-c C-x j u is another way to quickly jack in without a project choosing from a list of pre-configured Clojure build tools. When this command is called from outside of a project, the user is given the option to select to jack in with one of the pre-configured tools, as well as to confirm the root directory to use as a base. If the command is called from within a project directory, it behaves exactly the same as cider-jack-in does.

It utilizes Emacs’s numeric prefix arguments to quickly jack in with a specific build tool. Numeric prefix arguments can be set with the Meta key followed by a number.

The following Clojure build tools are supported so far