Basic Configuration

By default, CIDER enables cider-mode in all clojure-mode buffers after it establishes the first CIDER connection. It will also add a clojure-mode hook to enable cider-mode on newly-created clojure-mode buffers. You can override this behavior, however:

enrich-classpath is a program/plugin/wrapper that allows CIDER to access to the sources and javadocs of a given project’s Java files: your own files, those from your dependencies, and those from the JDK.

With that, CIDER can show better completions, navigation, documentation, and stacktrace integration.

For Lein users, it has the additional benefit of running a single JVM, instead of the two JVMs that Lein programs typically involve.

You can enable it by setting the cider-enrich-classpath defcustom to t.

With it enabled, cider-jack-in will activate enrich-classpath, given the following conditions:

…​these conditions will be progressively relaxed.

It’s worth noting that cider-jack-in will fall back to the original command if enrich-classpath failed, for whatever reason.

By default, CIDER won’t prompt you for a symbol when it executes interactive commands that require a symbol (e.g. cider-doc). Such commands operate on the symbol at point and prompt you to provide a symbol if they can’t obtain one automatically.

If you set cider-prompt-for-symbol to t, this behavior will be inverted and CIDER will always prompt you to confirm the symbol on which a command will operate. This behavior is useful, as it allows you to edit the inferred symbol, before some operation is carried out with it (and you get to see what was inferred by cider-symbol-at-point).

By default M-. and other commands that jump to a definition have the following behavior:

Other behavior is possible, and is controlled with cider-jump-to-pop-to-buffer-actions; the value of this is passed as the action argument to pop-to-buffer.

The default value is ((display-buffer-reuse-window display-buffer-same-window)).

Some people might prefer to always display the definition in the current window. Here’s how you can achieve this:

For other possibilities, see the documentation for display-buffer.

Out-of-the box, CIDER uses the standard completing-read Emacs mechanism. While it’s not fancy it certainly gets the job done (just press TAB). There are, however, ways to improve upon the standard completion if you wish to.

By default CIDER will display an inspirational message when a new connection is established. This behavior is configurable via cider-connection-message-fn:

The default message are stored in the variable cider-words-of-inspiration that you can tweak easily yourselves:

Of course, it goes without saying that you can do the same with cider-tips.

If you want to see all communications between CIDER and the nREPL server:

CIDER will then create buffers named *nrepl-messages conn-name* for each connection.

The communication log is tremendously valuable for debugging CIDER-to-nREPL problems and we recommend you enable it when you are facing such issues.

If you’re finding that *nrepl-connection* and *nrepl-server* buffers are cluttering up your development environment, you can suppress them from appearing in some buffer switching commands like switch-to-buffer(C-x b):

If you need to make the hidden buffers appear When using switch-to-buffer, type SPC after issuing the command. The hidden buffers will always be visible in list-buffers (C-x C-b).

To prefer local resources to remote resources (tramp) when both are available:

If you are running Clojure within a Docker image, or doing something similar (i.e. you’re cider-connect`ing to a process, and there’s a directory mapping for your source paths), you typically need to set `cider-path-translations for jump-to-definition to properly work. For instance, suppose your app is running in a docker container with your source directories mounted there as volumes. The navigation paths you’d get from nREPL will be relative to the source in the docker container rather than the correct path on your host machine. You can add translation mappings easily by setting the following (typically in .dir-locals.el):

Each entry will be interpreted as a directory entry so trailing slash is optional. Navigation to definition will attempt to translate these locations, and if they exist, navigate there rather than report that the file does not exist. In the example above, the .m2 directory is mounted at /root/.m2 and the source at /src. These translations would map these locations back to the user’s computer so that navigation to definition would work.

Using the eval pseudo-variable you can make the translation dynamic, enabling the possibility of sharing the .dir-locals.el across a team of developers with different configurations.

In this example, the path /src will be translated to the correct path of your Clojure project on the host machine. And /root/.m2 to the host’s ~/.m2 folder.

You need to run lein deps (or clojure -P, etc) in the host machine in order for navigation to fully work, at least once, and then, preferably, every time your Maven dependencies change. This allows the .m2 part of cider-path-translations to be actually useful.

If you can’t or won’t do that, you can use TRAMP capabilities (which CIDER supports) instead of setting up cider-path-translations. For that, you’d typically need to set up a SSH daemon within your Docker image.

You can hide all nREPL middleware details from cider-browse-ns* and cider-apropos* commands by customizing the variable cider-filter-regexps. The value of this variable should be a list of regexps matching the pattern of namespaces you want to filter out.

Its default value is '("^cider.nrepl" "^refactor-nrepl" "^nrepl"), the most commonly used middleware collections/packages.

An important thing to note is that this list of regexps is passed on to the middleware without any pre-processing. So, the regexps have to be in Clojure format (with twice the number of backslashes) and not Emacs Lisp. For example, to achieve the above effect, you could also set cider-filter-regexps to '(".*nrepl").

To customize cider-filter-regexps, you could use the Emacs customize UI, with M-x customize-variable RET cider-filter-regexps.

An alternative is to set the variable along with the other CIDER configuration.

By default contents of CIDER’s special buffers such as *cider-test-report* or *cider-doc* are line truncated. You can set cider-special-mode-truncate-lines to nil to make those buffers use word wrapping instead of line truncating.

CIDER provides the hooks cider-connected-hook and cider-disconnected-hook that get triggered when an nREPL connection is established or closed respectively.

Here’s how CIDER uses the first hook internally to display its famous inspirational messages on connect: