Question

15.1. Cursive

Cursive does not currently support resolving dependencies via shadow-cljs.edn. You can run shadow-cljs pom to generate a pom.xml and import that using the IntelliJ.

$ shadow-cljs pom

Then in Cursive File → New → Project from Existing Sources then select the generated pom.xml in the project directory.

Important

You need to have the "Build Tools" → "Maven" Plugin enabled for this. It might not be enabled by default.

Alternatively you can create a dummy project.clj or use the full Leiningen integration.

(defproject your/project "0.0.0"
  :dependencies
  [[thheller/shadow-cljs "X.Y.Z"]]
  :source-paths
  ["src"])

You can run npx shadow-cljs server inside the Terminal provided by IntelliJ and use Clojure REPL → Remote Run Configuration to connect to the provided nREPL server. Just select the "Use port from nREPL file" option in Cursive Clojure REPL → Remote or configure a fixed nREPL port if you prefer.

Note that the Cursive REPL when first connected always starts out as a CLJ REPL. You can switch it to CLJS by calling (shadow/repl :your-build-id). This will automatically switch the Cursive option as well. You can type :cljs/quit to drop back down to the CLJ REPL.

Note	You cannot switch from CLJ→CLJS via the Cursive select box. Make sure you use the call above to switch.

15.2. Emacs / CIDER

This section is written for CIDER version 0.20.0 and above. Ensure your Emacs environment has this version of the cider package or later. Refer to the CIDER documentation for full installation details.

15.2.1. Launch the ClojureScript REPL

Launch the nREPL and a ClojureScript REPL.

M-x cider-jack-in-cljs

CIDER will prompt you for the type of ClojureScript REPL:

Select ClojureScript REPL type:

Enter shadow.

Select shadow-cljs build:

Enter the name of your build target, for example, app.

Emacs should now open a new nREPL connection to the shadow-cljs server of its sibling, bootstrapping into a ClojureScript REPL environment:

shadow.user> To quit, type: :cljs/quit
[:selected :app]
cljs.repl>

You should now be able to eval ClojureScript, jump to the definitions of vars (with cider-find-var) and much more.

For example, to display an alert in the browser:

cljs.repl> (js/alert "Jurassic Park!")

15.2.2. Simplify startup with dir-local

You can simplify startup flow by a creating a .dir-locals.el file at project root.

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

Or, when watching several builds:

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

Read about Emacs and shadow-cljs, using the .dir-locals.el file at the Cider docs

15.2.3. Using deps.edn with custom repl intialization.

In case you want to manage your dependencies via deps.edn, you can use custom cljs-repl init form. Create a :dev alias with an extra source path of "dev" and add the following namespace

(ns user
  (:require [shadow.cljs.devtools.api :as shadow]
            [shadow.cljs.devtools.server :as server]))
(defn cljs-repl
  "Connects to a given build-id. Defaults to `:app`."
  ([]
   (cljs-repl :app))
  ([build-id]
   (server/start!)
   (shadow/watch build-id)
   (shadow/nrepl-select build-id)))

Supposing your build-id is :app, add the following to your .dir-locals.el

((nil . ((cider-clojure-cli-global-options . "-A:dev")
         (cider-preferred-build-tool       . clojure-cli)
         (cider-default-cljs-repl          . custom)
         (cider-custom-cljs-repl-init-form . "(do (user/cljs-repl))")
         (eval . (progn
                   (make-variable-buffer-local 'cider-jack-in-nrepl-middlewares)
                   (add-to-list 'cider-jack-in-nrepl-middlewares "shadow.cljs.devtools.server.nrepl/middleware"))))))

cider-jack-in-cljs should then work out of the box.

15.3. Proto REPL (Atom)

Proto REPL is mostly intended for Clojure development so most features do not work for ClojureScript. It is however possible to use it for simple evals.

You need to setup a couple of things to get it working.

1) Create a user.clj in on of your :source-paths.

 (ns user)
 (defn reset [])

The file must define the user/reset fn since Proto REPL will call that when connecting. If user/reset is not found it will call tools.namespace which destroys the running shadow-cljs server. We don’t want that. You could do something here but we don’t need to do anything for CLJS.

2) add [proto-repl "0.3.1"] to your :dependencies in ~/.shadow-cljs/config.edn or shadow-cljs.edn.

3) Configure a fixed nREPL port

4) Start shadow-cljs server or shadow-cljs watch your-build.

5) Run the Atom Command Proto Repl: Remote Nrepl Connection connect to localhost and the port you configured

6) Eval (shadow.cljs.devtools.api/watch :your-build) (if you used server in 4)

7) Eval (shadow.cljs.devtools.api/nrepl-select :your-build). The REPL connection is now in CLJS mode, meaning that everything you eval will be eval’d in JS. You can eval :repl/quit to get back to Clojure Mode. If you get [:no-worker :browser] you need to start the watch first.

8) Before you can eval CLJS you need to connect your client (eg. your Browser when building a :browser App).

9) Eval some JS, eg. (js/alert "foo"). If you get There is no connected JS runtime the client is not connected properly. Otherwise the Browser should show an alert.

15.4. Chlorine (Atom)

Chlorine connects Atom to a Socket REPL, but also tries to refresh namespace. So first, open up Chlorine package config and check if configuration Should we use clojure.tools.namespace to refresh is set to simple, otherwise it’ll destroy the running shadow-cljs server.

Once you checked that the configuration is right, you can start your shadow app (replace app with whatever build):

$ shadow-cljs watch app

Now, all you have to do is to run the atom command Chlorine: Connect Clojure Socket Repl. This will connect a REPL to evaluate Clojure code. Next you need to run Chlorine: Connect Embeded, and it’ll connect the ClojureScript REPL too.

Now, you can use the Chlorine: Evaluate…​ commands to evaluate any Clojure or ClojureScript REPL. It’ll evaluate .clj files as Clojure, and cljc files as ClojureScript.

15.5. Calva (VS Code)

Calva has built-in support for shadow-cljs.

15.5.1. Dependencies

You need VS Code and the Calva extension.

15.5.2. Start the REPL

The easiest way to start the REPL is to use Calva’s Jack-in command and then select the shadow-cljs Project Type. This will start the shadow-cljs watcher and inject the necessary cider-nrepl dependencies.

If you want to start the REPL yourself you can:

1. Use the Calva command Copy Jack-in Command to Clipboard

2. Start the REPL from the terminal (VS Code’s built-in terminal works great for this)

3. Use the Calva command Connect to a Running REPL

15.5.3. Connecting Calva to the build

Once shadow is done with its initial compile, start the app (in the browser, or node, or whatever, depending on your app).

Calva will prompt you for witch build to attach the REPL connection to. Calva has a command (and a statusbar button) for switching witch build is attached.

Hack away!

See calva.io for information about how to use Calva.

15.6. Fireplace.vim (Vim/Neovim)

Fireplace.vim is a Vim/Neovim plug-in which provides Clojure REPL integration by acting as an nREPL client. When combined with Shadow-CLJS, it also provides ClojureScript REPL integration.

This guide uses as an example the app created in the official Shadow-CLJS Quick Start guide therefore refers to a few configuration items in the app’s shadow-cljs.edn. That being said, these configuration items are fairly generic so should be applicable to other apps with minor modifications.

15.6.1. Dependencies

Install Fireplace.vim using your favorite method of installing plug-ins in Vim/Neovim.

As an nREPL client, Fireplace.vim depends on CIDER-nREPL (which is nREPL middleware that provides common, editor-agnostic REPL operations) therefore you need to include this dependency in ~/.shadow-cljs/config.edn or shadow-cljs.edn (as shown in the next sub-section.) Shadow-CLJS will inject the required CIDER-nREPL middleware once it sees this dependency.

15.6.2. Preparing the app

Create the example app by following the official Shadow-CLJS Quick Start guide and modify its shadow-cljs.edn as follows:

;; shadow-cljs configuration
{:source-paths
 ["src/dev"
  "src/main"
  "src/test"]
 ;; ADD - CIDER-nREPL middleware required by Fireplace.vim
 :dependencies
 [[cider/cider-nrepl "0.22.4"]]
 ;; ADD - a port (e.g., 3333) for the REPL server to which Fireplace.vim connects
 :nrepl
 {:port 3333}
 ;; ADD - a port (e.g., 8080) for the development-time HTTP server that serves the app
 :dev-http
 {8080 "public"}
 :builds
 {:frontend  ; NOTE - This is the build ID referenced at various places below.
  {:target :browser
   :modules {:main {:init-fn acme.frontend.app/init}}}}}

Once that is done, start the app (note the Shadow-CLJS build ID, frontend, specified in shadow-cljs.edn):

npx shadow-cljs watch frontend

Open the app in a browser at http://localhost:8080/. Without this step, you would get the following error message from Fireplace.vim if you attempt to connect to the REPL server from within Vim/Neovim:

No application has connected to the REPL server.
Make sure your JS environment has loaded your compiled ClojureScript code.

15.6.3. Connecting Fireplace.vim to REPL Server

Open a ClojureScript source file in Vim/Neovim and execute the following command to connect Fireplace.vim to the REPL server (note the port for the REPL server, 3333, specified in shadow-cljs.edn):

:Connect 3333
=>
Connected to nrepl://localhost:3333/
Scope connection to: ~/code/clojurescript/acme-app (ENTER)

This creates a Clojure (instead of ClojureScript) REPL session. Execute the following command to add ClojureScript support to the session (note the Shadow-CLJS build ID, frontend, specified in shadow-cljs.edn):

:CljEval (shadow/repl :frontend)
=>
To quit, type: :cljs/quit
[:selected :frontend]
Press ENTER or type command to continue

You should now be able to execute Fireplace.vim commands against the REPL server. Please refer to the Fireplace.vim documentation for the full list of commands you can execute.