ClojureScript

CIDER works well with ClojureScript, but not all CIDER features are available in ClojureScript (yet). For instance, the test runner and debugger are currently Clojure-only features.

Unlike the Clojure ecosystem that is dominated by Leiningen and Boot, the ClojureScript ecosystem has a number of different choices for REPLs. You’ll have to decide which one you want to run and how you want CIDER to interact with it. This chapter describes some of the more common choices and the configurations required to get them working.

Piggieback

ClojureScript support relies on the piggieback nREPL middleware being present in your REPL session. There’s one exception to this, though: shadow-cljs. It has its own nREPL middleware and doesn’t rely on piggieback at all.

If cider-inject-dependencies-at-jack-in is enabled, which it is by default, then piggieback will be automatically added and configured for your project when doing cider-jack-in-cljs.

If cider-inject-dependencies-at-jack-in is disabled or you’re going to connect to an already running nREPL server using cider-connect-cljs, use the configuration in the following section.

Manual Piggieback Setup

To setup piggieback, add the following dependencies to your project (project.clj in a Leiningen based project or build.boot in a Boot project or deps.edn):

;; use whatever are the most recent versions here
[cider/piggieback "0.4.2"]
[org.clojure/clojure "1.9.0"]

as well as piggieback nREPL middleware:

in project.clj:

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

or in build.boot:

(task-options!
  repl {:middleware '[cider.piggieback/wrap-cljs-repl]})

or in deps.edn:

{:aliases { :cider-cljs { :main-opts
  ["-m" "nrepl.cmdline" "--middleware"
   "[cider.nrepl/cider-middleware,cider.piggieback/wrap-cljs-repl]"]}}}

Starting a ClojureScript REPL

Open a ClojureScript file in your project and type M-x cider-jack-in-cljs RET. With the correct configuration and after answering a few prompts this will start up the nREPL server and create a ClojureScript REPL buffer.

Prior to CIDER 0.18, cider-jack-in-cljs would create both a Clojure and a ClojureScript REPL. In CIDER 0.18+ if you want to create both REPLs you’ll have to use cider-jack-in-clj&cljs instead.

When you have a combination of Clojure and ClojureScript REPLs, CIDER will automatically direct all the usual CIDER commands to the appropriate REPL based on whether you’re currently visiting a .clj or .cljs file.

cider-jack-in-cljs will prompt you for the type of ClojureScript REPL you want to start. Keep in mind that some of the REPLs will require you to configure additional setup. For example, you’ll need to have Node.js installed to be able to start a Node REPL.

If you frequently use the same ClojureScript REPL, you can set cider-default-cljs-repl and CIDER will skip the prompt and use this instead. For example, the following will make Nashorn the default:

(setq cider-default-cljs-repl 'nashorn)

All supported ClojureScript REPLs are stored in cider-cljs-repl-types. If you need to extend it, you should use cider-register-cljs-repl-type in your Emacs configuration.

(cider-register-cljs-repl-type 'super-cljs "(do (...))" optional-requirements-function)

You can also modify the known ClojureScript REPLs on a per-project basis using .dir-locals.el:

;; replace the list of REPL types and set some default
((nil
  (cider-default-cljs-repl . super-cljs)
  (cider-cljs-repl-types . ((super-cljs "(do (foo) (bar))")))))

;; modify the list of known REPLs and set some default
((nil
  (eval . (cider-register-cljs-repl-type 'super-cljs "(do (foo) (bar))"))
  (cider-default-cljs-repl . super-cljs)))

For one-off REPLs you can also use the custom REPL init form like this:

;; modify the list of known REPLs and set some default
((nil
  (cider-custom-cljs-repl-init-form . "(do (foo) (bar))"
  (cider-default-cljs-repl . custom)))

If you already have a Clojure REPL running and want to add a ClojureScript REPL, you can invoke cider-jack-in-sibling-clojurescript to add it.

Setting up a ClojureScript REPL

The following sections describe the configurations for several common ClojureScript REPL use cases.

Browser-Connected ClojureScript REPL

Using Weasel, you can also have a browser-connected REPL.

Add [weasel "0.7.0"] to your project’s :dependencies.
Type M-x cider-jack-in-cljs RET and choose the Weasel option when prompted about the ClojureScript REPL type you want to use.

Add this to your ClojureScript code:

(ns my.cljs.core
  (:require [weasel.repl :as repl]))
(repl/connect "ws://localhost:9001")

Open a file in your project and type M-x cider-jack-in-cljs.

Provided that a Piggieback-enabled ClojureScript environment is active in your REPL session, code loading and evaluation will work seamlessly regardless of the presence of the cider-nrepl middleware. If the middleware is present then most other features of CIDER will also be enabled (including code completion, documentation lookup, the namespace browser, and macroexpansion).

Browser-Connected ClojureScript REPL in Boot Projects

Add this to your dependencies in build.boot:

[adzerk/boot-cljs        "X.Y.Z"  :scope "test"]
[adzerk/boot-cljs-repl   "X.Y.Z"  :scope "test"]
[pandeiro/boot-http      "X.Y.Z"  :scope "test"]
[weasel                  "0.7.0"  :scope "test"]
[cider/piggieback "0.4.2"  :scope "test"] ; not needed for cider-jack-in-cljs

and this at the end of build.boot:

(require
 '[adzerk.boot-cljs :refer [cljs]]
 '[adzerk.boot-cljs-repl :refer [cljs-repl]]
 '[pandeiro.boot-http :refer [serve]])

(deftask dev []
  (comp (serve)
        (watch)
        (cljs-repl) ; order is important!!
        (cljs)))

Type M-x customize-variable RET cider-boot-parameters and insert dev.
Open a file in your project and type M-x cider-jack-in-cljs.
Connect to the running server with your browser. The address is printed on the terminal, but it’s probably http://localhost:3000.

For more information visit boot-cljs-repl.

Using 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.

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:
```
[cider/piggieback "0.4.2"] ; 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.
Add this to your dev :repl-options (not needed for cider-jack-in-cljs):
```
:nrepl-middleware [cider.piggieback/wrap-cljs-repl]
```
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.
Open a browser to the Figwheel URL so that it can connect to your application.

You should also check out Figwheel’s wiki.

Using Figwheel-main

The instructions here assume you’re using Leiningen. Adapting them to your favourite build tool is up to you.

You can also use Figwheel-main with CIDER.

Leiningen figwheel-main setup

This setup is only necessary if cider-inject-dependencies-at-jack-in has been changed from its default setting of enabled, as described more fully above.

Add this to your dev :dependencies (not needed for cider-jack-in-cljs):
```
[cider/piggieback "0.4.2"]
```
Add this to your dev :repl-options (not needed for cider-jack-in-cljs):
```
:nrepl-middleware [cider.piggieback/wrap-cljs-repl]
```
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.
Select the Figwheel build to run when prompted for it. (e.g. :dev).

Clojure CLI figwheel-main setup

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"}}}}}
```
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-global-options . "-A:fig"))))
```
Start the REPL with cider-jack-in-cljs (C-c C-x (C-)j (C-)s).

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).

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.

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 shadow-cljs

Provided you’ve configured your project correctly, you can simply use cider-jack-in-cljs for shadow-cljs.

This will automatically start the shadow-cljs server and connect to it. You’ll also be prompted for the build to use.

Alternatively you can start the server manually with something like:

$ npx shadow-cljs server

And connect to it with cider-connect.

If you already have a running server watching a build (for instance you have already run npx shadow-cljs watch :dev), you can use the shadow-select CLJS REPL and specify :dev when prompted.

Working with `.cljc` files

Ordinarily, CIDER dispatches code from clj files to Clojure REPLs and cljs files to ClojureScript REPLs. Butcljc files have two possible connection targets, both of which are valid. So, by default, CIDER tries to evaluate cljc files in all matching connection buffers, both clj and cljs, if present.

Thus, if you’re evaluating the code (+ 2 2) in a cljc file and you have both an active Clojure and ClojureScript REPL then the code is going to be evaluated twice, once in each of the REPLs. In fact, you can create multiple clj and cljs sibling connections (C-c C-x C-s C-s/j) within a CIDER session and evaluation will be directed into all REPLs simultaneously. See Managing Connections for more details.