Up and Running

Piggieback Setup

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.5.3"]
[org.clojure/clojure "1.11.1"]

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]"]}}}

or in build.gradle:

dependencies {
  devImplementation 'nrepl:nrepl:1.1.2'
  devImplementation 'cider:cider-nrepl:0.49.0'
  devImplementation 'cider:cider-piggieback:0.5.3'
}

tasks.named('clojureRepl') {
  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.

The only ClojureScript REPL type that doesn’t require any additional setup is the browser REPL. To use the Node.js REPL you’ll need to install Node.js.

CIDER will automatically try to check if the required dependencies (e.g. Clojure libraries and/or additional tools like Node.js) to start a certain ClojureScript REPL are present. If you happen to run into a faulty requirements check you can disable them like this:

(setq cider-check-cljs-repl-requirements nil)

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.

If you would prefer to evaluate cljc files in only one of the matching REPLs, you can customize the variable cider-clojurec-eval-destination to either clj or cljs. For example, to evaluate cljc files in the ClojureScript REPL only, add the following to your Emacs configuration:

(setq cider-clojurec-eval-destination 'cljs)

Note: This variable can also be set on a per-buffer basis using setq-local, or project-wide in dir-locals.el.