= Using Figwheel
:experimental:

Figwheel is one of the most popular ClojureScript REPLs today. Below you'll find
instructions on how to set up and use it with CIDER.

NOTE: There are two versions of Figwheel out there - the legacy https://github.com/bhauman/lein-figwheel[figwheel] and
the modern https://github.com/bhauman/figwheel-main[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 https://figwheel.org/docs/installation.html[excellent documentation].

=== Leiningen Setup

NOTE: 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`.

. Add this to your dev `:dependencies` (not needed for `cider-jack-in-cljs`):
+
[source,clojure]
----
[cider/piggieback "0.6.1"]
----
+
. Add this to your dev `:repl-options` (not needed for `cider-jack-in-cljs`):
+
[source,clojure]
----
: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):

[source,clojure]
----
(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

. Ensure your `deps.edn` contains these dependencies available from an
alias such as `fig`. These should already be present if you used the
https://github.com/bhauman/figwheel-main-template[figwheel-main-template]
with https://github.com/seancorfield/clj-new[clj-new] to generate your
deps.edn.
+
[source,clojure]
----
{:aliases {:fig {:extra-deps
                 {com.bhauman/rebel-readline-cljs {:mvn/version "0.1.4"}
                  com.bhauman/figwheel-main {:mvn/version "0.2.17"}}}
           :build {:main-opts ["-m" "figwheel.main" "-b" "dev" "-r"]}}}
----
+
. 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`.)
+
[source,lisp]
----
((clojurescript-mode . ((cider-clojure-cli-aliases . ":fig:build"))))
----

TIP: 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:

. Start the REPL with `cider-jack-in-cljs` (kbd:[C-c C-x (C-)j (C-)s]). When CIDER prompts about the ClojureScript REPL type,
select `figwheel-main`.
. Select the Figwheel build to run when prompted for it. (e.g. `:dev`).
. When CIDER prompts for the ClojureScript REPL type, select `figwheel-main`.
. 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.

WARNING: 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.

NOTE: 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 https://github.com/bhauman/figwheel-main/blob/master/src/figwheel/main/api.clj[figwheel.main.api/start]
for details.

== Using legacy Figwheel (Leiningen-only)

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

You can also use https://github.com/bhauman/lein-figwheel[Figwheel] with CIDER.

. Set up Figwheel as normal, but make sure `:cljsbuild` and `:figwheel` settings are
in the root of your Leiningen project definition.
. Add these to your dev `:dependencies`:
+
[source,clojure]
----
[cider/piggieback "0.6.1"] ; not needed for cider-jack-in-cljs
[figwheel-sidecar "0.5.19"] ; use here whatever the current version of figwheel is
----
+
WARNING: Keep in mind that CIDER does not support versions of Piggieback older than 0.4. Make sure that you use a compatible version of Figwheel.
+
. Add this to your dev `:repl-options` (not needed for `cider-jack-in-cljs`):
+
[source,clojure]
----
:nrepl-middleware [cider.piggieback/wrap-cljs-repl]
----
+
. Start the REPL with `cider-jack-in-cljs` (kbd:[C-c C-x (C-)j (C-)s]). Select
`figwheel` when prompted for the ClojureScript REPL type.
. Open a browser to the Figwheel URL so that it can connect to your application.

You should also check out
https://github.com/bhauman/lein-figwheel/wiki/Using-the-Figwheel-REPL-within-NRepl[Figwheel's wiki].

== Additional Resources

=== Official Figwheel Documentation

* https://figwheel.org/docs/installation.html[Installation]
* https://figwheel.org/docs/emacs.html[Using Figwheel with CIDER].

=== Tutorials

* https://cjohansen.no/tools-deps-figwheel-main-devcards-emacs/[tools.deps, figwheel-main, Devcards, and Emacs]
* https://lambdaisland.com/episodes/figwheel-emacs-cider[Using Figwheel with CIDER]
