Using Figwheel With Emacs, part 2: CIDER

By using Figwheel with CIDER you get both a Clojure and a ClojureScript REPL at the same time, and you get all the nice features of CIDER. It’s a more complex setup than just straight inf-clojure, so before we get there we need to talk a bit about nREPL and Piggieback, tooling you should be familiar with, no matter which editor you are using.

Transcript

So if inf-clojure is so great, why are all the cool kids talking about CIDER? Well, to understand that we need to talk about nREPL.

nREPL isn’t so much a REPL as it is a backend server for Clojure tooling. You can use it to power a REPL, or a documentation browser, or a refactoring tool, anything that can benefit from hooking into and interacting with a Clojure process.

You can send a message to an nREPL server, and it will send you one or more messages in return. If you send it an “eval” message, it will evaluate some code and send back the result. If you send it a “describe” message it will tell you all the operations it supports. Send it a “load-file” message and it will (re)load a certain file.

Messages are sent over the wire using a binary format called BEncode, but that’s not so important, conceptually you can think of a message as a map with key-value pairs.

All main Clojure IDEs and editors are powered by nREPL, including CIDER. Communicating programmatically with a REPL process over input and output streams is tedious, it also means it’s impossible to distinguish between a REPL result and other program output. In contrast nREPL provides a richer interaction model.

Enough theory, how do we use Figwheel with CIDER?

First of all you’ll need CIDER, which can be installed just like inf-clojure from MELPA.

(package-install 'cider)

Now in core.cljs, make sure inf-clojure-minor-mode is disabled, and enable cider-mode. To always have cider-mode active, you can add something like this to your setup.

(add-hook 'clojure-mode-hook 'cider-mode)

CIDER needs an nREPL server that it can talk to. The easiest way to launch an nREPL server is with lein repl, besides the regular REPL you’ll see in the terminal this also starts nREPL. The first line of output contains the port number to connect to. With M-x cider-connect you can connect to it.

Notice we get some warnings here, the more advanced capabilities of CIDER won’t work this way.

For CIDER to work to its full potential, we need to add the CIDER-nREPL plugin to Leiningen. This plugin adds the CIDER middleware to nREPL, which provides extra operations for CIDER to use, things like looking up documentation, or jumping to a function definition.

(defproject example "0.1.0"
  :dependencies [[org.clojure/clojure "1.9.0-alpha10"]
                 [org.clojure/clojurescript "1.9.89"]]

  :plugins [[lein-figwheel "0.5.4-7"]
            [cider/cider-nrepl "0.13.0-SNAPSHOT"]]

  ,,,)

Start lein repl again and connect to it. Notice that the warnings are gone. Now we get the full power of CIDER, so we can ask for the documentation of a symbol, or jump to its definition, things that weren’t so easy with inf-clojure.

Being able to connect to a running nREPL server like this can be convenient, maybe you have a process on another host you want to debug, but having to manually add the plugin is tedious. It can also lead to things breaking in unexpected ways due to a version mismatch between CIDER and the CIDER-nREPL plugin.

Nine times out of ten you’ll use CIDER with an app you’re developing locally. In this case it’s better to just let CIDER take care of launching the REPL, this way CIDER can inject the plugin dependency when starting lein repl, so you don’t have to do that yourself. That way it’s always there and up to date. So take the plugin first out of project.clj, and then ask CIDER to launch nREPL and connect to it with M-x cider-jack-in. You can see the exact invocation CIDER used in the minibuffer. It’s also logged in your *Messages* buffer.

In my case you can also see refactor-nrepl in there, this plugin is added by clj-refactor to provide refactoring operations.

Starting nREPL server via /home/arne/bin/lein update-in :dependencies conj \[org.clojure/tools.nrepl\ \"0.2.12\"\] -- update-in :plugins conj \[refactor-nrepl\ \"2.3.0-SNAPSHOT\"\] -- update-in :plugins conj \[cider/cider-nrepl\ \"0.13.0\"\] -- repl :headless...

After a moment your REPL should be waiting obediently for input. You can also verify that evaluating forms in a Clojure buffer works as expected. One great thing is that with inf-clojure, the results would show up in the REPL buffer, whereas now they show up right next to the expression as an overlay. If you use the C-u prefix to C-x C-e then the result are inserted into the buffer.

There are two more buffers that CIDER created, even though it doesn’t show them by default. When has a name starting with *nrepl-server, the other is called *nrepl-messages.

The nrepl-server buffer contains anything written to the standard out or error streams by the Leinigen process. Remember that with nREPL, communication happens over a network socket, not over the standard input and output streams.

If any of the Clojure code you evaluate does generate output, then nREPL will intercept it and send it back to CIDER, so it also shows up in the REPL buffer. This is why when we evaluate println it shows up in the REPL. If anything else causes output, maybe a background thread is writing out debug information, then it ends up in this *nrepl-server* buffer.

If something goes wrong and an exception happens inside nREPL, or if your Java process segfaults, then that will only be visible here, so if things start misbehaving it’s a good idea to have a look at this buffer.

The nrepl-messages buffer is super interesting because here you can see how CIDER and nREPL are talking to each other. It contains each message back and forth between the two. For instance here you can see what happened when I evaluated this bit of code.

(-->
  ns  "figmacs.scratch"
  op  "eval"
  session  "4e5850bd-cc0d-42aa-99e8-f917f5c1312b"
  code  "(range 7) \n"
  file  "/home/arne/figmacs/src/figmacs/scratch.clj"
  line  7
  column  0
  id  "15"
)
(<--
  id  "15"
  ns  "figmacs.scratch"
  session  "4e5850bd-cc0d-42aa-99e8-f917f5c1312b"
  value  "(0 1 2 3 4 5 6)"
)

So far so good, chances are you figured out this much by yourself, but what about ClojureScript? ClojureScript has its own mechanism for building REPLs, based on JavaScript evaluation environments. To use these ClojureScript REPL environments from nREPL we need Piggieback.

Piggieback is a “middleware” for nREPL. It will intercept “eval”-type messages and route them to ClojureScript.

Add Piggieback as a dependency in the :dev profile, and also add it to the nREPL middleware stack. Now restart CIDER (M-x cider-restart) to make sure Piggieback is loaded.

(defproject example "0.1.0"
  :dependencies [[org.clojure/clojure "1.9.0-alpha10"]
                 [org.clojure/clojurescript "1.9.89"]]

  :profiles {:dev
             {:dependencies [[com.cemerick/piggieback "0.2.1"]]
              :repl-options {:nrepl-middleware [cemerick.piggieback/wrap-cljs-repl]}}}

  ,,,)

To change our Clojure REPL into a ClojureScript REPL, we call Piggieback’s cljs-repl function. We need to tell it which REPL environment to use. ClojureScript has a pluggable system so it’s easy to provide REPL environments for various JavaScript runtimes. This could be a browser, or Node.js, but for now we’ll use a JavaScript runtime that comes bundled with Java, called Rhino.

(require 'cemerick.piggieback)
(require 'cljs.repl.rhino)

(cemerick.piggieback/cljs-repl (cljs.repl.rhino/repl-env))

Now when CIDER sends an “eval” message to nREPL, Piggieback will intercept it, and pass the code to be evaluated to the ClojureScript REPL environment. There it gets compiled to JavaScript, and passed to Rhino, which evaluates the code, and sends back the result.

Using Rhino is an easy option for a quick ClojureScript REPL because it requires no extra dependencies, and we can use all our CIDER goodness like evaluating forms from a CLJS buffer. It’s not quite Figwheel yet though, we’ll get to that in a bit.

There’s another downside to this approach, we can switch between Clojure and ClojureScript REPLs, but we only have one of them active at a time. When doing both front- and backend work at the same time this becomes tedious. We’ll see how to solve that as well.

To use Figwheel with CIDER, so with nREPL and Piggieback, we need one extra ingredient: figwheel-sidecar. Figwheel was originally only available as a Leiningen plug-in, but with Sidecar it can be used as a library, so you can start Figwheel from a running process.

To begin with add sidecar to your dev dependencies, right next to Piggieback.

(defproject example "0.1.0"
  :dependencies [[org.clojure/clojure "1.9.0-alpha10"]
                 [org.clojure/clojurescript "1.9.89"]]

  :profiles {:dev
             {:dependencies [[figwheel-sidecar "0.5.4-7"]
                             [com.cemerick/piggieback "0.2.1"]]
              :repl-options {:nrepl-middleware [cemerick.piggieback/wrap-cljs-repl]}}}

  ,,,)

Restart CIDER, and now we’re ready to start Figwheel! The first command starts the ClojureScript compiler, launches the web server, and sets up the automatic reloading, the second command starts the browser connected REPL.

Under the hood this uses Piggieback, so we still need to set up the Piggieback nREPL middleware in project.clj. This time the REPL environment passed to Piggieback will use Figwheel to do the evaluation.

(require '[figwheel-sidecar.repl-api :as fw])

(fw/start-figwheel!)
(fw/cljs-repl)

Alright, we’re almost there! We have Figwheel running inside nREPL now, which means we can use it from CIDER, and get all the rich editing and interactive development that CIDER offers. There are quite a few moving pieces, but once you get the big picture it becomes a lot easier to figure out how to set things up.

There’s only one thing we would ask Santa if he would listen: having both a Clojure and ClojureScript REPL active at the same time, so forms evaluated from a CLJ or CLJS file automatically go to the right place. Santa in this case doesn’t live on the North Pole, but in beautiful Bulgaria, and he’s already delivered everything we asked for!

Close the CIDER connection (M-x cider-quit). By the way you can always check which CIDER sessions are still open with M-x cider-connection-browser, and from that list you can kill them one by one with k.

Now instead of doing cider-jack-in, do cider-jack-in-clojurescript. This will start two nREPL sessions, one of which will be commanded to use ClojureScript.

But… that doesn’t look like a Figwheel REPL! Seems like CIDER used Rhino, the JavaScript engine bundled with Java. That’s not terribly useful, although it does mean we can use Java classes straight from ClojureScript. Yeah that’s actually not terribly useful either.

We can tell CIDER we’re using Figwheel by customizing the cider-cljs-lein-repl variable. By default it’s set to (cemerick.piggieback/cljs-repl (cljs.repl.rhino/repl-env)). Instead we need to change it to the snippet that starts Figwheel. CIDER makes this easy by providing a list to choose from.

Open the customize interface with M-x customize-variable cider-cljs-lein-repl. Tab your way to the button that reads “Value Menu” and press enter. Now you get a list of choices, the second of which is “Figwheel sidecar”. That’s the one we want. Press 1, and then save the changes the way you would save a file with C-x C-s.

Now if you look at cider-cljs-lein-repl you’ll see it’s exactly the same thing we did earlier to switch to a Figwheel REPL. You can again use Directory Local Variables to change this on a per project basis.

(do
  (require 'figwheel-sidecar.repl-api)
  (figwheel-sidecar.repl-api/start-figwheel!)
  (figwheel-sidecar.repl-api/cljs-repl))

Personally I have this set to a more elaborate snippet that tries to detect the type of project I’m in, and “does the right thing”.

(setq cider-cljs-lein-repl
      "(cond
  (and (resolve 'user/run) (resolve 'user/browser-repl)) ;; Chestnut projects
  (eval '(do (user/run)
             (user/browser-repl)))

  (try
    (require 'figwheel-sidecar.repl-api)
    (resolve 'figwheel-sidecar.repl-api/start-figwheel!)
    (catch Throwable _))
  (eval '(do (figwheel-sidecar.repl-api/start-figwheel!)
             (figwheel-sidecar.repl-api/cljs-repl)))

  (try
    (require 'cemerick.piggieback)
    (resolve 'cemerick.piggieback/cljs-repl)
    (catch Throwable _))
  (eval '(cemerick.piggieback/cljs-repl (cljs.repl.rhino/repl-env)))

  :else
  (throw (ex-info \"Failed to initialize CLJS repl. Add com.cemerick/piggieback and optionally figwheel-sidecar to your project.\" {})))")

We’ve covered a lot of ground now, inf-clojure, CIDER, nREPL, Piggieback, … oh my. I hope you still have everything clear in your mind.

I could have given you a snippet to copy to your Emacs config and be done with it, but I think it’s much more valuable to actually understand what’s going on. Our REPL and editor are our two most important tools, the equivalent of a carpenter’s workbench or a chemist’s lab. Get to know it intimately, and you’ll be able to use it more effectively, and be better equipped to troubleshoot potential issues.

Show Notes

Emacs config

(package-install 'cider)

(add-hook 'clojure-mode-hook 'cider-mode)

;; To auto detect Chestnut or Figwheel projects
;; You can also just use the customize interface to set this variable
(setq cider-cljs-lein-repl
      "(cond
  (and (resolve 'user/run) (resolve 'user/browser-repl)) ;; Chestnut projects
  (eval '(do (user/run)
             (user/browser-repl)))

  (try
    (require 'figwheel-sidecar.repl-api)
    (resolve 'figwheel-sidecar.repl-api/start-figwheel!)
    (catch Throwable _))
  (eval '(do (figwheel-sidecar.repl-api/start-figwheel!)
             (figwheel-sidecar.repl-api/cljs-repl)))

  (try
    (require 'cemerick.piggieback)
    (resolve 'cemerick.piggieback/cljs-repl)
    (catch Throwable _))
  (eval '(cemerick.piggieback/cljs-repl (cljs.repl.rhino/repl-env)))

  :else
  (throw (ex-info \"Failed to initialize CLJS repl. Add com.cemerick/piggieback and optionally figwheel-sidecar to your project.\" {})))")

project.clj

To use Figwheel with CIDER, you need to have both Piggieback and Figwheel Sidecar as dependencies, and also make sure the Piggieback middleware is loaded in nREPL.

(defproject example "0.1.0"
  :dependencies [[org.clojure/clojure "1.9.0-alpha10"]
                 [org.clojure/clojurescript "1.9.89"]]

  :profiles {:dev
             {:dependencies [[figwheel-sidecar "0.5.4-7"]
                             [com.cemerick/piggieback "0.2.1"]]
              :repl-options {:nrepl-middleware [cemerick.piggieback/wrap-cljs-repl]}}})

After that switching an nREPL-based REPL to a Figwheel REPL is as easy as

(require 'figwheel-sidecar.repl-api)

(figwheel-sidecar.repl-api/start-figwheel!)
(figwheel-sidecar.repl-api/cljs-repl)

But instead of doing this manually you can customize cider-cljs-lein-repl and rely on cider-jack-in-clojurescript.

Emacs commands

M-x cider-connect
M-x cider-quit
M-x cider-restart
M-x cider-connection-browser (use k to kill the selected connection)
M-x cider-jack-in (C-c M-j)
M-x cider-jack-in-clojurescript (C-c M-J)
M-x customize-variable cider-cljs-lein-repl

CIDER has elaborate documentation, it’s worth skimming through it just so you have a sense of all that’s in there. Did you know it can run your unit tests, that there’s a debugger, or that you can browse all loaded namespaces?