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
after it establishes the first CIDER connection. It will also add a
clojure-mode hook to enable
cider-mode on newly-created
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.
commands operate on the symbol at point and prompt you to provide
a symbol if they can’t obtain one automatically.
If you set
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
(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
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
The default value is
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
You jump to
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
map will be shown in the current window.
You jump to
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
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 is bundled with Emacs and enhances the default minibuffer completion:
You can learn more about
ido is also bundled with Emacs and offers more features than
If you are using
ido, be sure to use both
You might also want to install
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.
Message Displayed on Connect
By default CIDER will display an inspirational message when a new connection is
established. This behavior is configurable via
;; make the message more educational (setq cider-connection-message-fn #'cider-random-tip) ;; disable this extra message altogether (setq cider-connection-message-fn nil)
|This is probably one of the most important CIDER features. Disable those amazing messages at your own risk!|
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
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
buffers are cluttering up your development environment, you can
suppress them from appearing in some buffer switching commands like
(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
((nil (cider-path-translations . (("/root/.m2" . "/Users/foo/.m2") ("/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
and the source at
/src. These translations would map these locations
back to the user’s computer so that navigation to definition would work.
eval pseudo-variable you can make the translation dynamic, enabling
the possibility of sharing the
.dir-locals.el across a team of developers with
((nil . ((eval . (customize-set-variable 'cider-path-translations (list (cons "/src" (clojure-project-dir)) (cons "/root/.m2" (concat (getenv "HOME") "/.m2"))))))))
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
Filter out namespaces in certain namespace-related commands
You can hide all nREPL middleware details from
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, you could use the Emacs customize UI,
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-doc* are line truncated. You can set
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
nREPL Connection Hooks
CIDER provides the hooks
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:
(defun cider--maybe-inspire-on-connect () "Display an inspiration connection message." (when cider-connection-message-fn (message "Connected! %s" (funcall cider-connection-message-fn)))) (add-hook 'cider-connected-hook #'cider--maybe-inspire-on-connect)
There are also lower-level