Using shadow-cljs

shadow-cljs is one of the most popular toolchain for doing ClojureScript development these days. In this section we’ll discuss how to set it up and use it together with CIDER.

Setting up shadow-cljs

This section assumes you’ve already installed node.js.

Installing shadow-cljs is pretty straight-forward. You can do it via npm or yarn:

$ npm install -g shadow-cljs
$ yarn global add shadow-cljs

While it’s not necessary to do a global installation that’s generally the recommended approach.

Starting a shadow-cljs REPL

Using cider-jack-in-cljs

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

  • Press C-c C-x j s (or do M-x cider-jack-in-cljs)

  • When prompted for the ClojureScript REPL type to start, select shadow

This will automatically start the shadow-cljs server and connect to it. You’ll also be prompted for the shadow-cljs build to use. Select your desired build (e.g. app) and you should see something like:

shadow.user> To quit, type: :cljs/quit
[:selected :app]
cljs.repl>
CIDER will extract the list of available builds automatically from the shadow-cljs.edn file in the root of the current project.

You can get rid of the prompts for the REPL type and the target build by creating a .dir-locals.el file with the following contents in the root of your project.

((nil . ((cider-default-cljs-repl . shadow)
         (cider-shadow-default-options . "<your-build-name-here>")
         (cider-shadow-watched-builds . ("<first-build>" "<other-build>")))))

Using cider-connect-cljs

Alternatively you can start the server manually with something like:

$ npx shadow-cljs server

And connect to it with cider-connect.

If cider-nrepl isn’t in your classpath you should make sure it’s there. You can do this by adding it to :dependencies in the shadow-cljs.edn configuration file residing in the root of your project. Alternatively you can set cider-repl-auto-detect-type to nil, as the auto-detection of REPL types doesn’t work without cider-nrepl.

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.

Configuration

You can tweak the command used by cider-jack-in-cljs to start the shadow-cljs server via the following configuration variables:

  • cider-shadow-cljs-command (its default value is npx shadow-cljs)

  • cider-shadow-cljs-global-options (its default value is blank)

  • cider-shadow-cljs-parameters (its default value is server)

All of this results in the following default command to start the shadow-cljs server:

$ npx shadow-cljs server

The command is visible in the minibuffer when you’re doing cider-jack-in-cljs.

As noted earlier you can also set a default build via cider-shadow-default-options:

(setq cider-shadow-default-options "app")

Additional Resources

Official shadow-cljs Documentation

Here are a few useful sections from shadow-cljs's own documentation:

Tutorials