CIDER nREPL

Overview

cider-nrepl aims to extend the base functionality of an nREPL server to cater to the needs of Clojure(Script) programming environments. It provides nREPL ops for common operations like:

  • code completion

  • source and documentation lookup

  • profiling

  • debugging

  • code reloading

  • find references

  • running tests

  • filtering stacktraces

The ultimate goal of cider-nrepl is to provide a solid foundation for nREPL clients, so they don’t have to reinvent the wheel all the time.

Despite its name, cider-nrepl is editor-agnostic and is leveraged by several other Clojure editors, besides CIDER (e.g. vim-fireplace, iced-vim, Calva, CCW). While the project is officially a part of CIDER, its development is a joint venture between all interested tool authors.

Design

This section documents some of the major design decisions in cider-nrepl.

While in essence it’s just a collection of nREPL middleware we had to make a few important design decision here and there that influenced the code base and the usability of cider-nrepl in various ways.

REPL-powered

All of the middleware that are currently part of cider-nrepl are relying on REPL state introspection to perform their work. While we might leverage static code analysis down the road for some tasks, cider-nrepl will always be a REPL-first tool.

Editor Agnostic

Although those middleware were created for use with CIDER almost all of them are extremely generic and can be leveraged from other editors.

Projects like vim-fireplace and vim-replant are making use of cider-nrepl already.

Reusable Core Logic

cider-nrepl tries to have as little logic as possible and mostly provides thin wrappers over existing libraries (e.g. compliment, cljfmt, etc). Much of its core functionality lives in orchard, so that eventually it can be used by non-nREPL clients (e.g. Socket REPL clients).

Very simply put - there’s very little code in cider-nrepl that’s not simply wrapping code from other libraries in nREPL operations.

The primary reason for this is our desire to eventually provide support for non-nREPL REPLs in CIDER, but this also means that other editors can directly leverage the work we’ve done so far.

ClojureScript Support

We want cider-nrepl to offer feature parity between Clojure and ClojureScript, but we’re not quite there yet and many features right now are Clojure-only.

We’d really appreciate all the help we can get from ClojureScript hackers to make this a reality.

Isolated Runtime Dependencies

Most of cider-nrepl’s dependencies are processed with mranderson, so that they won’t collide with the dependencies of your own projects. This basically means that cider-nrepl has almost no runtime dependencies in the production artifact - just copies of the deps inlined with changed namespaces/packages. It’s a bit ugly and painful, but it gets the job done.

The exclusion to this rule are the artifacts that are themselves part of the CIDER ecosystem and have to runtime dependencies of their own:

If someone has better ideas how to isolate our runtime dependencies - we’re all ears!

Deferred Middleware Loading

To improve the startup time of the nREPL server all of cider-nrepl’s middleware are loaded for real only when needed.

You can read more about this here.

We’d love to bring the support for deferred middleware loading straight to nREPL down the road.

Middleware Errors Never Hang Requests

See here.