cider-nrepl: the middleware layer that gives Clojure editors their IDE features

Middleware that adds editor features without an editor

cider-nrepl is described as a collection of nREPL middleware to enhance Clojure editors with common functionality like definition lookup and code completion. The architecture matters here. nREPL is a protocol where a client and a running Clojure process exchange messages, and middleware sits in the middle of that channel, intercepting operations and adding behaviour. So the intelligence lives on the server side, in the JVM running your project, and the editor is just the thing that renders the results. That is why the same middleware works across wildly different editors. The library was originally designed to enhance CIDER, but the README lists other consumers including fireplace.vim, vim-iced, Calva and Conjure, plus other Clojure development tools based on nREPL. If you write a Clojure editor, you are probably consuming this or a fork of it.

Generic tooling was deliberately extracted to orchard

The acknowledgements section names the projects cider-nrepl leans on, and one of them explains the current shape of the code. orchard was extracted from cider-nrepl so that non-nREPL clients can reuse the generic tooling functionality, with inspect, apropos and var-info named as examples. That extraction is the reason the generic, non-editor-specific operations now live in their own library rather than inside the middleware collection. The other dependencies fill specific gaps: compliment provides Clojure code completion, clj-suitable provides ClojureScript code completion using runtime inspection, tools.namespace and clj-reload handle namespace reloading, and cljfmt handles code formatting. The practical reading is that cider-nrepl is the protocol-facing layer, and the language analysis lives in companion libraries that can be used without nREPL at all. That separation is also what lets a non-nREPL client reuse the same behaviour.

Minor version bumps are major releases, and that is deliberate

The release policy section is unusual enough to be worth reading in full. The project follows SemVer as much as one can while the major version is 0, and at that point bumps of the minor, second, version number are considered major releases and always include new features or significant changes to existing features. API compatibility between major releases is not a big concern, although the project tries to break the API rarely and only for a good reason. The development cycle for the next major release starts immediately after the previous one ships, and bugfix or point releases, if any, address only serious bugs and never contain new features. If you are an editor author integrating against this API, that means a minor version jump can break you, and waiting for a major release does not buy you stability. The version history reflects the cadence, with v0.63.1 on 2026-10-03, v0.63.0 on 2026-10-02 and v0.62.2 on 2026-07-18.

A Makefile is the recommended path for local development

The README recommends using the Makefile for local tasks, since some aspects can be hard to grasp for newcomers, and it gives the main targets. The tests come in two flavours, with make test using mranderson for a slower but more realistic run and make quick-test skipping it for a considerably faster run. Installing into your local Maven repository is make install, which uses version 99.99 as a placeholder unless you set PROJECT_VERSION. Linting runs clj-kondo, cljfmt and Eastwood in that order with fail-fast, and the README asks contributors to run it before pushing commits. Documentation is regenerated with make docs, and the README notes that when you modify a middleware so its schema changes, you should reflect that in the cider.nrepl namespace and run the target.

make test
make quick-test
make install
make lint
make docs

The underlying build is a tools.deps project with a deps.edn at the root, and the Makefile pins the versions it tests against, with Clojure 1.12 and nREPL 1.7 as overridable variables.

The test setup explains why Java parsing needs its own toolchain

The Makefile carries more detail than a build file usually needs to, and the reason is Java interop testing. The comments explain that Java sources are needed to test Java parsing functionality, but the Docker images used on CircleCI do not include src.zip, so the sources have to be downloaded from GitHub and repackaged into a form resembling the src.zip from a normal distribution. There are separate targets for that download and for compiling Java with and without tests. The fast test target runs against the real, non-inlined dependencies and excludes the ClojureScript tests, which run separately through a cljs-test target. The stated reason for keeping ClojureScript off the base classpath is that its 1.12 Closure compiler needs JDK 21 or newer, and the macroexpand middleware would try to load it. There is also a lein plugin compatibility wrinkle, with the LEIN_VERSION environment variable set explicitly because the Clojure CLI does not set it the way Leiningen does.

Releases are scripted, deployed to Clojars by CI, and EPL licensed

The release process is scripted, with PROJECT_VERSION=X.Y.Z make release followed by pushing the branch and the tag. That rolls the changelog, bumps the version in the docs, commits, tags and pushes, and the CI takes it from there and deploys to Clojars, where the artifact is published as cider/cider-nrepl. The project is on Clojars, has CircleCI and codecov badges in the README, and the repository is not archived with the last push on 2026-10-20, so work is still landing. The licence is the Eclipse Public License, the same as Clojure, with copyright held by Bozhidar Batsov, and that choice is worth understanding before you vendor the code into a differently licensed product. The repository also carries a CHANGELOG.md, a .clj-kondo configuration directory, a .cljfmt.edn, a .dir-locals.el, a markdownlint configuration and a doc directory holding the manual sources.

Editorial conclusion

cider-nrepl fits anyone building or maintaining a Clojure editor integration on nREPL, whether that is CIDER, Calva, Conjure or a Vim plugin, and who wants the generic tooling behaviour maintained in one place instead of duplicated per client. It does not fit a Clojure developer who only wants to use an editor, since the README itself points those users to the CIDER manual rather than the nREPL manual. Verify first which middleware your client actually requests, read the release policy before pinning a version, since minor bumps carry breaking API changes, and remember the licence is the Eclipse Public License rather than a permissive one if you plan to relicense or vendor the code.

Frequently asked questions

Official sources

1. clojure-emacs/cider-nrepl on GitHub
2. Issues
3. Project website
4. README
5. Releases