Basic Configuration

Like Emacs itself, almost every part of CIDER is configurable. The CIDER developers have tried to implement some reasonable defaults that should work for a large portion of the Clojure community, but we know that there is nothing approaching a "one size fits all" development environment and we’ve tried to create points of customization that can account for many different peoples' preferences. In this way, you should be able to make CIDER as comfortable as possible for you.

This section doesn’t describe every possible customization that CIDER offers, but here are some of the most popular.

You can see every single customizable configuration option with the command M-x customize-group RET cider.

Disable Automatic cider-mode in clojure-mode Buffers

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:

(setq cider-auto-mode nil)

Prompt for Symbol Confirmation

The default here was changed in CIDER 1.0.

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).

(setq cider-prompt-for-symbol t)
Many interactive commands that operate on the symbol at point, accept a prefix argument that flips the behavior configured via cider-prompt-for-symbol for the current command invocation.

Control what window to use when jumping to a definition

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

  • If the definition buffer is visible simply switch to it.

  • Otherwise, use the current window to show the definition.

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:

(setq cider-jump-to-pop-to-buffer-actions
      '((display-buffer-same-window)))
Keep in mind this might cause problems with some special buffers (e.g. test report buffers), as when you try to navigate to a definition this will clobber the special buffer.

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

Example 1

You jump to map in core.clj when core.clj is not being displayed in another window in the current frame.

With both the default behavior and the alternative behavior defined above, the definition of map will be shown in the current window.

Example 2

You jump to map in core.clj when core.clj is being displayed in another window in the current frame.

With the default behavior, the definition of map will be shown in the current window; you will now have two windows showing core.clj, and the existing core.clj window will be unchanged.

With the alternative behavior defined above, the definition of map will be shown in the existing core.clj window; all windows will show the same buffer as before the jump, and the current window will now be the one showing core.clj.

Minibuffer completion

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.

icomplete

icomplete is bundled with Emacs and enhances the default minibuffer completion:

(require 'icomplete)

You can learn more about icomplete here.

ido

ido is also bundled with Emacs and offers more features than icomplete. If you are using ido, be sure to use both ido-everywhere and ido-completing-read+. You might also want to install ido-flex.

If you’re fine with installing a third-party package for enhanced minibuffer completion you can’t go wrong with the modern and versatile ivy.

Log nREPL Communications

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

(setq nrepl-log-messages t)

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.

Hide Special nREPL Buffers

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):

(setq nrepl-hide-special-buffers t)

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).

Prefer Local Resources Over Remote Resources

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

(setq cider-prefer-local-resources t)

Translate File Paths

If you wish to translate file paths from your running instance you may use the cider-path-translations defcustom to do so. For instance, suppose your app is running in a docker container with your source directories mounted there. 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):

((nil
  (cider-path-translations . (("/root" . "/Users/foo")
                              ("/src/" . "/Users/foo/projects")))))

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.

Use a Local Copy of the JDK API Documentation

If you are targeting the JVM and prefer a local copy of the JDK API documentation over Oracle’s official copy (e.g., for JavaSE 8), per nREPL’s javadoc-info logic (accurate as of 29 Dec 2014), you can arrange your project to include the root path of the local API doc (i.e., where the index.html is located) to be included on your classpath (i.e., where the doc HTML files can be located by clojure.java.io/resource). For example, for Leiningen, with the local API path being /usr/share/doc/java/api/, put the following line in project.clj:

:dev {:resource-paths ["/usr/share/doc/java/api/"]}

or the following line in $HOME/.lein/profiles.clj:

:user {:resource-paths ["/usr/share/doc/java/api/"]}

More details can be found here.

Use a Local Copy of the Java Source Code

When an exception is thrown, e.g. when eval-ing (. clojure.lang.RT foo), a stack trace pops up. Some places of the stack trace link to Clojure files, others to Java files. By default, you can click the Clojure file links to navigate there. If you configure cider-jdk-src-paths, you can also click the Java file links to navigate there.

On Windows and macOS the JDK source code is bundled with the JDK. On Windows its typical location is C:\Program Files\Java\{jdk-version}\src.zip and on macOS it’s /Library/Java/JavaVirtualMachines/{jdk-version}/Contents/Home/src.zip.

On Linux distributions usually the source code is distributed as a separate package. Here’s how do get the JDK 8 source on Ubuntu:

sudo apt install openjdk-8-source

The zip is installed to /usr/lib/jvm/openjdk-8/src.zip.

You can download Clojure Java source code from here.

Extract both and configure e.g. like so:

(setq cider-jdk-src-paths '("~/java/clojure-1.8.0-sources"
                            "~/java/openjvm-8-src"))

It’s possible to point cider-jdk-src-paths to jar or zip files, but extracting them is better since you can use features like ag or dired-jump.

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.

(setq cider-filter-regexps '(".*nrepl"))

Truncate long lines in special buffers

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.

(setq cider-special-mode-truncate-lines nil)
This variable should be set before loading CIDER (which means before require-ing it or autoloading it).