Lambda Island

Learn how to integrate Figwheel’s browser connected REPL into Emacs, for an ever greater degree of interactive development, using inf-clojure-mode.

Transcript

Figwheel is one of the greatest tools available for ClojureScript. It provides hot code reloading, so every time you save a ClojureScript file, your browser is updated live. It does the same for CSS, and also provides a browser connected REPL, so you can interact with your running application.

I’ll set up a basic project skeleton, containing a single ClojureScript source file, a resources directory for things like HTML and CSS, which will also contain the compiled ClojureScript, and a project.clj for Leiningen.

The easiest way to use Figwheel is through its Leiningen plugin. Add it to project.clj, and also configure a single ClojureScript build with the figwheel: true flag set. This config compiles each ClojureScript file under src to a JavaScript file under resources/public/js/out. The entry point for the browser will be js/figmacs.js.

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

  :plugins [[lein-figwheel "0.5.4-7"]]

  :cljsbuild {:builds
              [{:id "figmacs"
                :source-paths ["src/"]
                :figwheel true
                :compiler {:main "figmacs.core"
                           :asset-path "js/out"
                           :output-to "resources/public/js/figmacs.js"
                           :output-dir "resources/public/js/out"}}]})

It’s possible to integrate the Figwheel REPL with Emacs, which gives you the type of interactive development that LISP and Emacs developers are used to. There’s a couple ways to go about it though, so I want to dig into this a bit.

We configured our ClojureScript build to use figmacs.core as main namespace, so let’s create that. I’ll enable console print, and then print something to the console so we see it’s working.

(ns figmacs.core)

(enable-console-print!)

(println "Figwheel is live!")

Like any browser-based ClojureScript project you’ll also need an index.html as entry point, this one goes under resources/public. From there load the output target and you’re good to go.

<script src="js/figmacs.js"></script>

Now from a terminal you can start lein figwheel, and off you go. The first time it needs a moment to do the first compilation. Figwheel starts a web server on port 3449 that you can connect to.

Ok Figwheel is waiting for your browser to connect back to Figwheel over a websocket, so compiled code can be sent back back to the browser, so open your browser at port 3449. You can see your code is already running. And now that the connection is established the REPL prompt appears.

Now if we type some ClojureScript code into the REPL, it gets compiled to JavaScript, sent to the browser and executed. Pretty neat.

Similarly when we change our source file, and then save it, the browser immediately reflects those changes. The whole file gets evaluated every time you save it, so that’s something you’ll have to keep in mind, by making sure your code is reloadable.

So that’s all great, but we’ve seen some of that cool Emacs live evaluation from a Clojure source buffer, and we want some of that for our ClojureScript. For Clojure it seems most people can figure things out, but when it comes to ClojureScript and Figwheel a lot of folks are getting stuck. This isn’t too surprising, there’s a lot more machinery involved, and there are least three different ways to approach it.

I’ll show you the simplest way first using inferior Lisp mode and inf-clojure, before moving on to more full-featured nREPL based solutions with CIDER.

Here’s the secret that no-one is telling you: you don’t need to install a single package to interact with a ClojureScript REPL from Emacs. The built-in functionality for working with an external LISP process is all you need to get started. Emacs calls this “inferior” because the Lisp process runs as a sub-process, but it doesn’t mean it’s any less valuable!

To tell Emacs that Figwheel will provide our REPL, we need to set the inferior-lisp-program variable. I’m just doing that from Emacs *scratch* buffer here (C-x C-e). If you want this to persist you’ll have to add the code to you emacs configuration. This variable contains the incantation to start the REPL, in our case that’s lein figwheel.

(setq inferior-lisp-program "lein figwheel")

Now switch back to one of the files in your project, this is simply so the working directory of leiningen is inside your project, that way leiningen will use the right project.clj. Now you can run the built-in M-x run-lisp command, and assuming inferior-lisp-program is set correctly you should see Figwheel booting up. If you still have your browser open it should straight away drop to a REPL prompt, although it might take a minute for Figwheel to reconnect.

If you get an error message saying “figwheel is not a task” then either you didn’t correctly add the Figwheel plugin in project.clj, or more likely you’re starting the REPL from a different directory.

You can use the REPL directly, but we could do that from the terminal as well. It gets more fun when we interact with it from a source buffer. Open core.cljs, and use split windows so you can see the REPL and the source code side by side (C-x 3C-x oC-x b *inferior-lisp*).

Now you can send forms to the REPL with M-x lisp-eval-last-sexp, and the result will show up in the REPL. This causes Emacs to find the form (sexp) before “point” (your cursor position), and send that form to the REPL process, which then returns the result.

Having to type M-x lisp-eval-last-sexp is tedious, we can quickly set up some keybindings so they behave as they do in most Lisp modes in Emacs.

(define-key clojure-mode-map (kbd "C-x C-e") 'lisp-eval-last-sexp)
(define-key clojure-mode-map (kbd "C-M-x")   'lisp-eval-defun)
(define-key clojure-mode-map (kbd "C-x C-r") 'lisp-eval-region)

If you were already using inf-clojure or CIDER then these new keybindings will clash with the ones provided by those packages. I wouldn’t worry about, we’ll get to better solutions soon, but if you do feel like trying these out then make sure cider-mode and inf-clojure-minor-mode are disabled.

Having inferior-lisp built-in is great, but there’s a version of inferior-lisp specifically tailored for Clojure, so we might as well use that. It’s called inf-clojure and is available on MELPA.

If you’ve ever installed something from MELPA then just a M-: (package-install 'inf-clojure) will do the trick. I have slightly more elaborate instructions in the show notes in case that command fails for you.

(package-install 'inf-clojure) ;;  Install inf-clojure

The equivalent of the inferior-lisp-program variable for inf-clojure is called inf-clojure-program. By default it runs lein repl, giving you a standard Clojure REPL. To get a Figwheel REPL instead we’ll change it to lein figwheel.

(setq inf-clojure-program "lein figwheel")

Now go back to core.cljs, and enable inf-clojure-minor-mode. This minor mode adds all the relevant keybindings. If you’re planning to use inf-clojure regularly you should set up a hook so inf-clojure-minor-mode is enabled wherever clojure-mode is active.

(add-hook 'clojure-mode-hook 'inf-clojure-minor-mode)

If you were already using CIDER then make sure it’s disabled! The functionality of inf-clojure and CIDER largely overlaps, and having them both enabled will only cause a mess. cider-mode is a minor mode, so running the cider-mode command will toggle it on or off. Check the modeline to make sure it’s not there.

M-x cider-mode

You can’t tell looking at the modeline wether inf-clojure-minor-mode is enabled or not, but you can see it when looking at the list of active modes (C-h m).

You will also see a list of all the keybindings that inf-clojure-minor-mode adds. The starting point is C-c C-z, inf-clojure-switch-to-repl, which will start the REPL if it’s not running already, and then switch to the REPL buffer.

Now just like before we can evaluate forms, but we also get keybindings to look up documentation, look at macroexpansions, switch namespaces, and more. inf-clojure’s README is pretty sparse, but I’ve documented all it’s key combinations in the show notes, and of course you can also find them through Emacs’ help system.

I told you you can configure inf-clojure-program in your Emacs config, but what if it’s not the same for all projects?

How can you configure one project to use lein repl, and another to use lein figwheel? The answer is Emacs’ Directory Local Variables.

In the project root create a file named .dir-locals.el. In there you can configure variables that will only be set inside this project. The syntax is a bit tedious I admit, but it’s a powerful mechanism.

The file contains a list of cons pairs. If the first element of the pair is nil then these variables are applied to all files under this directory. It can also be the name of a major mode (a symbol), or a subdirectory (a string), and then the variables will only be applied to the files that match.

((clojure-mode . ((inf-clojure-program . "lein figwheel"))))

Here’s a formatted example that shows all the possibilities. snacks and drinks will be set in all file buffers for this project. Buffers set to clojure-mode as their major mode will also have the music and vibes variables set, whereas files under src/example also get the hours and light variables.

(
 (nil .
   ((snacks . "tasty")
    (drinks . "cold")))

 (clojure-mode .
   ((music . "loud")
    (vibes . "good")))

 ("src/example" .
   ((hours . "small")
    (light . "disco")))
)

Show Notes

Inferior LISP

Emacs Manual: External Lisp

inf-clojure

GitHub: clojure-emacs/inf-clojure

If you don’t have MELPA set up yet something like this should do the trick

(add-to-list
   'package-archives
   '("melpa" . "http://melpa.org/packages/")
   t) ;; append MELPA to the list of package sources

(package-initialize) ;; initialize the package system

(unless (file-exists-p "~/.emacs.d/elpa/archives/melpa")
  (package-refresh-contents)) ;; fetch the list of packages

(package-install 'inf-clojure)

Keybindings (inf-clojure-minor-mode). All the “eval” commands take an optional prefix argument which makes them switch to the REPL buffer.

C-c C-z (inf-clojure-switch-to-repl): Switch to the inferior Clojure process buffer. With prefix argument, positions cursor at end of buffer
M-C-x / C-c C-c (inf-clojure-eval-defun): Send the current defun to the inferior Clojure process.
C-x C-e / C-c C-e (inf-clojure-eval-last-sexp): Send the previous sexp to the inferior Clojure process.
C-c C-b (inf-clojure-eval-buffer): Send the current buffer to the inferior Clojure process.
C-c C-r (inf-clojure-eval-region): Send the current region to the inferior Clojure process.
C-c C-n (inf-clojure-eval-form-and-next): Send the previous sexp to the inferior Clojure process and move to the next
C-c C-i (inf-clojure-show-ns-vars): Send a query to the inferior Clojure for the public vars in NS. Like doing (dir ,,,) in a REPL.
C-c C-A (inf-clojure-apropos): Send a command to the inferior Clojure to give apropos for VAR.
C-c C-m (inf-clojure-macroexpand): Send a command to the inferior Clojure to give apropos for VAR. With a prefix arg uses ‘macroexpand-1’.
C-c C-l (inf-clojure-load-file): Load a Clojure file into the inferior Clojure process.
C-c C-a (inf-clojure-show-arglist): Show the arglist for a function in the mini-buffer.
C-c C-v (inf-clojure-show-var-documentation): Send a command to the inferior Clojure to give documentation for a var.
C-c C-s (inf-clojure-show-var-source): Send a command to the inferior Clojure to give source for a var.
C-c M-n (inf-clojure-set-ns): Set the ns of the inferior Clojure process to NS. Defaults to the ns of the current buffer.

Emacs Per-directory Variables

Emacs Manual Entry

Code

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; inferior lisp
(setq inferior-lisp-program "lein figwheel")

(define-key clojure-mode-map (kbd "C-x C-e") 'lisp-eval-last-sexp)
(define-key clojure-mode-map (kbd "C-M-x")   'lisp-eval-defun)
(define-key clojure-mode-map (kbd "C-x C-r") 'lisp-eval-region)

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; inf-clojure

(setq inf-clojure-program "lein figwheel")
(add-hook 'clojure-mode-hook 'inf-clojure-mode)

Using Figwheel With Emacs, part 1: inf-clojure-mode