= Additional Packages

There are many additional Emacs packages that can enhance your Clojure programming
experience. The majority of the minor modes listed here should be enabled for both
`cider-repl-mode`, `clojure-mode`, and `clojure-ts-mode` for optimal effects.

The packages listed here belong to three categories:

* CIDER extensions
* Generic Emacs packages useful for Clojure programming
* CIDER alternatives

== CIDER Extensions

IMPORTANT: Make sure that the version of any extension you've installed is compatible with
your CIDER version.

CIDER extensions typically are Emacs packages that are built on top of CIDER's Emacs Lisp API.
Some of them ship with extra nREPL middleware as well (e.g. `clj-refactor`). Typically
packages that rely on middleware would hook into CIDER's middleware injection
functionality and inject their own functionality automatically as well.

NOTE: Keep in mind that currently there are no "official" CIDER extensions and the packages
on the list are not maintained by CIDER's Core Team. Their quality and level
of maintenance may vary significantly.

=== cider-storm

https://github.com/jpmonettas/cider-storm[Cider Storm] is an Emacs Cider front-end for the https://github.com/jpmonettas/flow-storm-debugger[FlowStorm] debugger with support for Clojure and ClojureScript.

=== clj-decompiler

https://github.com/bsless/clj-decompiler.el[clj-decompiler] allows you to quickly decompile Clojure code to Java bytecode. It's based on https://github.com/clojure-goes-fast/clj-java-decompiler[clj-java-decompiler].

=== clj-refactor

https://github.com/clojure-emacs/clj-refactor.el[clj-refactor] builds on top
of `clojure-mode` and CIDER and adds a ton of extra functionality (e.g. the
ability to thread/unthread expression, find and replace usages, introduce let
bindings, extract function and so on).

A full list of features is available
https://github.com/clojure-emacs/clj-refactor.el/wiki[here].

We hope to incorporate some of its features into `clojure-mode` and CIDER themselves
down the road.

=== emidje

https://github.com/nubank/emidje[Emidje] is a test runner, report
viewer and formatting tool for
https://github.com/marick/Midje[Midje] within Emacs.

Emidje extends CIDER to provide support for Midje tests in a similar
fashion as `cider-test.el` does for `clojure.test` tests. In fact, most of
Emidje's functionalities were strongly inspired by `cider-test.el`
features.

=== kaocha-runner

https://github.com/magnars/kaocha-runner.el[kaocha-runner] provides
https://github.com/lambdaisland/kaocha[Kaocha] integration for Emacs.

=== helm-cider

https://github.com/clojure-emacs/helm-cider[helm-cider] provides a Helm
interface for certain CIDER commands (e.g. `cider-apropos`).

=== cider-hydra

https://github.com/clojure-emacs/cider-hydra[cider-hydra] provides a nice way
to navigate groups of related CIDER commands.

You can think of it as a fancier https://github.com/justbur/emacs-which-key[which-key].

=== flycheck-clj-kondo

https://github.com/borkdude/flycheck-clj-kondo/[flycheck-clj-kondo] is a
Flycheck checker for Clojure that provides instant linting of clojure code as you type, via
https://github.com/borkdude/clj-kondo[clj-kondo].

https://github.com/borkdude/clj-kondo[clj-kondo] is a great way of preventing
yourself from writing buggy code.

=== squiggly-clojure

https://github.com/clojure-emacs/squiggly-clojure[squiggly-clojure] is a
Flycheck checker for Clojure, using tools like
https://github.com/jonase/eastwood[eastwood],
http://typedclojure.org/[core.typed] and
https://github.com/jonase/kibit[kibit].

=== sayid

http://clojure-emacs.github.io/sayid/[sayid] is a powerful alternative of CIDER's
built-in basic tracing functionality.

=== clay

https://github.com/scicloj/clay.el[clay.el] provides CIDER support for https://scicloj.github.io/clay/[Clay],
a minimalistic tool for data visualization and literate programming.
It provides interactive functions for sending a single Clojure form to be visualized in the browser,
and for rendering a whole namespace as a notebook (or slideshow) in different formats.

== Generic Emacs Extensions

Most packages in the following list are standard Emacs minor modes that work
with most major modes, but are especially handy for Lisp-like languages like
Clojure.

=== subword-mode

Enabling `CamelCase` support for editing commands (like
`forward-word`, `backward-word`, etc) in the REPL is quite useful since
we often have to deal with Java class and method names. The built-in
Emacs minor mode `subword-mode` provides such functionality:

[source,lisp]
----
(add-hook 'cider-repl-mode-hook #'subword-mode)
----

=== Paredit

The use of http://mumble.net/~campbell/emacs/paredit.html[paredit]
when editing Clojure (or any other Lisp) code is highly
recommended.  You're probably using it already in your `clojure-mode`
buffers (if you're not you probably should). You might also want to
enable `paredit` in the REPL buffer as well:

[source,lisp]
----
(add-hook 'cider-repl-mode-hook #'paredit-mode)
----

==== Unsetting the Paredit binding of the RET key

In recent versions of Paredit (25+), `RET` is bound to `paredit-RET`. This can cause unexpected
behavior in the REPL when `paredit-mode` is enabled, e.g. it appears to hang after hitting
`RET` instead of evaluating the last form.

You can disable this Paredit behavior by adding the following to your `init.el`:

[source,lisp]
----
(define-key paredit-mode-map (kbd "RET") nil)
----

=== paren-face

https://github.com/tarsius/paren-face[paren-face] defines a face named
`parenthesis` used just for parentheses. The originally intended purpose of this
face is to make parentheses less visible in Lisp code by dimming them.

In the author's words:

> We lispers probably don’t need to be constantly made aware of the existence of
> the parentheses. Dimming them might be even more useful for people new to lisp
> who have not yet learned to subconsciously blend out the parentheses.

TIP: the following customization expands paren-face to dim even more delimiters from the Clojure language: `(setq paren-face-regexp "\\([( ]\\.-\\|[( ]\\.+\\|[][(){}#/]\\)")`.

=== Smartparens

https://github.com/Fuco1/smartparens[smartparens] is an excellent alternative to
paredit. Many Clojure hackers have adopted it recently and you might want to
give it a try as well. To enable `smartparens` in the REPL buffer use the
following code:

[source,lisp]
----
(add-hook 'cider-repl-mode-hook #'smartparens-strict-mode)
----

=== rainbow-delimiters

https://github.com/Fanael/rainbow-delimiters[RainbowDelimiters] is a minor
mode which highlights parentheses, brackets, and braces according to their
depth. Each successive level is highlighted in a different color. This makes it
easy to spot matching delimiters, orient yourself in the code, and tell which
statements are at a given depth. Assuming you've already installed
RainbowDelimiters you can enable it in the REPL like this:

[source,lisp]
----
(add-hook 'cider-repl-mode-hook #'rainbow-delimiters-mode)
----

=== eval-sexp-fu

https://github.com/hchbaw/eval-sexp-fu.el[eval-sexp-fu] provides some visual
feedback when evaluating expressions. https://github.com/clojure-emacs/cider-eval-sexp-fu[cider-eval-sexp-fu] provides
CIDER integration for `eval-sexp-fu`.

[source,lisp]
----
(require 'cider-eval-sexp-fu)
----

== Alternatives

IMPORTANT: It's generally a bad idea to mix Clojure programming environments, as all of those
tend to modify `clojure-mode` 's keymap while active. Run only one environment at a time unless
you really know what you're doing.

This section enumerates other Emacs packages that provide a Clojure programming environment
for Emacs.

=== Inf-clojure

This package provides basic interaction with a Clojure subprocess (REPL). It's
based on ideas from the popular inferior-lisp package.

https://github.com/clojure-emacs/inf-clojure[inf-clojure] has two components -
a nice Clojure REPL with auto-completion and a minor mode
(`inf-clojure-minor-mode`), which extends clojure-mode with commands to evaluate
forms directly in the REPL.

It's basically a simple alternative of CIDER, which provides a subset of CIDER's
functionality.
