Using Figwheel

Figwheel is one of the most popular ClojureScript REPLs today. Below you’ll instructions how to setup and use it with CIDER.

There are two versions of Figwheel out there - the legacy figwheel and the modern figwheel-main. You’re strongly advised to use figwheel-main.

Using Figwheel-main

The setup instructions that follow focus on the bare minimum you need to do to get Figwheel to work with CIDER. For more details you should check out Figwheel’s excellent documentation.

Leiningen Setup

This part of the setup is only necessary if cider-inject-dependencies-at-jack-in has been changed from its default setting of t (enabled), as described earlier. You’ll also have to configure Piggieback manually if you’re planning to use cider-connect-cljs.

  1. Add this to your dev :dependencies (not needed for cider-jack-in-cljs):

    [cider/piggieback "0.5.1"]

  2. Add this to your dev :repl-options (not needed for cider-jack-in-cljs):

    :nrepl-middleware [cider.piggieback/wrap-cljs-repl]

Now it’s time to add figwheel-main to your dependencies as well and you’re good to go. Here’s an example minimal project.clj (sans the optional Piggieback setup):

(defproject example-project "0.1.0-SNAPSHOT"
  :dependencies [[org.clojure/clojure "1.10.1"]]
  :profiles
    {:dev
      {:dependencies [[org.clojure/clojurescript "1.10.339"]
                      [com.bhauman/figwheel-main "0.2.3"]]}})

You can now verify that everything’s properly setup by running:

$ lein run -m figwheel.main

A browser window should pop open and back in the terminal you should see a REPL with a cljs.user⇒ prompt waiting to evaluate ClojureScript code.

Clojure CLI Setup

  1. Ensure your deps.edn contains these dependencies available from an alias such as fig. These should already be present if you used the figwheel-main-template with clj-new to generate your deps.edn.

    {:aliases {:fig {:extra-deps
                 {com.bhauman/rebel-readline-cljs {:mvn/version "0.1.4"}
                  com.bhauman/figwheel-main {:mvn/version "0.2.3"}}}}}

  2. Add this option to your project’s .dir-locals.el before opening the ClojureScript file in a buffer from which you’ll be starting the REPL. (If the file is already open you can either close and open it again or use revert-buffer.)

    ((clojurescript-mode . ((cider-clojure-cli-aliases . "-A:fig"))))
If you didn’t setup .dir-locals.el you can edit the command-line in the minibuffer and insert "-A:fig" at the beginning after the clojure executable. To do this prepend calling cider-jack-in-cljs with the universal argument (e.g. C-u).

Starting a REPL

Now that Figwheel is properly configured it’s time for us to start a Figwheel-powered REPL in CIDER:

  1. Start the REPL with cider-jack-in-cljs (C-c C-x (C-)j (C-)s). When CIDER prompts about the ClojureScript REPL type, select figwheel-main.

  2. Select the Figwheel build to run when prompted for it. (e.g. :dev).

  3. When CIDER prompts for the ClojureScript REPL type, select figwheel-main.

  4. When CIDER prompts for the build name, select one of the build name options which were generated by finding files named <build>.cljs.edn in the project root directory.

If instead of selecting one of the build name options provided, you enter either a non-existent build name (no matching .cljs.edn file) or an empty build name, CIDER will forward that on to figwheel-main which will report an error.
For more advanced usage, you can provide any options supported by figwheel.main/start at either the prompt for the build name or using the cider-figwheel-main-default-options. See figwheel.main.api/start for details.

Using legacy Figwheel (Leiningen-only)

This has been deprecated in favour of using figwheel-main. Check out the instructions in the next section.

You can also use Figwheel with CIDER.

  1. Set up Figwheel as normal, but make sure :cljsbuild and :figwheel settings are in the root of your Leiningen project definition.

  2. Add these to your dev :dependencies:

    [cider/piggieback "0.5.1"] ; not needed for cider-jack-in-cljs
[figwheel-sidecar "0.5.19"] ; use here whatever the current version of figwheel is
    Keep in mind that CIDER does not support versions versions of Piggieback older than 0.4. Make sure that you use a compatible version of Figwheel.

  3. Add this to your dev :repl-options (not needed for cider-jack-in-cljs):

    :nrepl-middleware [cider.piggieback/wrap-cljs-repl]

  4. Start the REPL with cider-jack-in-cljs (C-c C-x (C-)j (C-)s). Select figwheel when prompted for the ClojureScript REPL type.

  5. Open a browser to the Figwheel URL so that it can connect to your application.

You should also check out Figwheel’s wiki.

Additional Resources

Official Figwheel Documentation

Tutorials