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 tools.deps, Leiningen, 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 a recent tools.deps. 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 better option would be to start nREPL manually and connect to it with cider-connect.

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. Fortunately, if you’re using cider-jack-in, that’s handled auto-magically.

If your project uses lein 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 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 "1.3.1"} cider/cider-nrepl {:mvn/version "0.52.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).

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.

Enabling nREPL JVMTI agent

Since version 1.2.0, nREPL includes a native JVMTI agent which makes the eval interrupts work properly on Java 21 and later. To enable the agent, the Java process should be launched with -Djdk.attach.allowAttachSelf. CIDER will do it automatically during jack-in if cider-enable-nrepl-jvmti-agent variable is set to t.

cider-enable-nrepl-jvmti-agent has no effect if you start a REPL process outside of Emacs and connect to it with cider-connect. In that scenario, you have to add -Djdk.attach.allowAttachSelf Java property manually through the means of the build tool. In Leiningen, add this to project.clj:

:jvm-opts ["-Djdk.attach.allowAttachSelf"]

In tools.deps, add this to one of the aliases that you enable with the REPL:

:aliases {:dev
          {:jvm-opts ["-Djdk.attach.allowAttachSelf"]
           ...}}

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 (defaults 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

  • M-1 C-c C-x j u jack-in using clojure-cli.

  • M-2 C-c C-x j u jack-in using leiningen.

  • M-3 C-c C-x j u jack-in using babashka.

  • M-4 C-c C-x j u jack-in using nbb.

  • M-5 C-c C-x j u jack-in using basilisp.

Here is an example of how to bind F12 for quickly bringing up a babashka REPL:

(global-set-key (kbd "<f12>") (lambda ()
                                (interactive)
                                (cider-jack-in-universal 3)))

The list of available build tools to consider is configured in cider-jack-in-universal-options. Each element of the list consists of the tool name and its setup options. Taking nbb as an example from the list:

(nbb         (:prefix-arg 4 :cmd (:jack-in-type cljs :project-type nbb :cljs-repl-type nbb :edit-project-dir t)))

with

  1. :prefix-arg assigns the nbb tool name a numerical argument prefix of 4.

  2. :cmd how to invoke the command.

    1. :jack-in-type use a cljs repl.

    2. :project-type use nbb (see jack-in-command) to bring up the nREPL server.

    3. :cljs-repl-type client uses the nbb cljs repl type (see cider-cljs-repl-types) to initialize server.

    4. :edit-project-dir ask the user to confirm root directory to use as base.

Customizing the Jack-in Command Behavior

You can use C-u M-x cider-jack-in RET to specify the exact command that cider-jack-in would run. This option is very useful is you want to e.g. specify extra Leiningen profiles or deps.edn aliases.

Alternatively you can C-u C-u M-x cider-jack-in RET, which is a variation of the previous command. This command will first prompt you for the project you want to launch cider-jack-in in, which is pretty handy if you’re in some other directory currently. This option is also useful if your project contains some combination of project.clj and deps.edn and you want to launch a REPL for one or the other.

The examples use only cider-jack-in, but this behavior is consistent for all cider-jack-in-\* commands.

You can further customize the command line CIDER uses for cider-jack-in by modifying the some options. Those differ a bit between the various tools, so we’ll examine them tool by tool.

Leiningen Options

  • cider-lein-command - the name of the Leiningen executable (lein by default)

  • cider-lein-parameters - the command-line params to start a REPL (e.g. repl :headless or -o to enable offline mode)

Clojure CLI Options

  • cider-clojure-cli-command - the name of the clojure executable (clojure by default)

  • cider-clojure-cli-parameters - the command-line parameters to start a REPL

  • cider-clojure-cli-aliases - a list of project-specific aliases to be used at jack-in time (it’s meant to be set via .dir-locals.el)

  • cider-clojure-cli-global-aliases - a list of global aliases that are appended to project-specific cider-clojure-cli-aliases

On MS-Windows, CIDER will employ PowerShell to execute Clojure if no clojure executable is found in the PATH (e.g. like the one supplied by deps.clj). The default executable used is powershell which is available on all Windows platforms. Using PowerShell will Base64 encode the clojure launch command before passing it to PowerShell and avoids shell-escaping issues.

The functionality of cider-clojure-cli-command has been verified with the following alternatives

  • pwsh: This option proves beneficial when the user has installed the ClojureTools module on pwsh in a directory not accessible by the system’s PowerShell installation.

  • deps.exe: This executable is part of the tools provided by deps.clj as an alternative name for clojure.exe.

Alternatively you can use WSL (e.g. to run nREPL and Emacs there), which will likely result in a better overall development experience.

Gradle Options

  • cider-gradle-command - the name of the Gradle executable (./gradlew by default)

  • cider-gradle-parameters - the Gradle arguments to invoke the repl task (e.g. --no-daemon or --configuration-cache) (clojureRepl by default)

shadow-cljs

  • cider-shadow-cljs-command - the command to run shadow-cljs (npx shadow-cljs by default). By default we favor the project-specific shadow-cljs over the system-wide.

  • cider-shadow-cljs-parameters - the task to start a REPL server (server by default)

Override the Jack-In Command

Which Jack-In Command is used is based on the project type. You can override the Jack-In Command either project-wide or as an argument in Lisp. This allows for fine-grained control over how cider starts the nrepl-server.

The precedence order for determining the Jack-In Command is: 1. :jack-in-cmd if provided as a parameter, 2.