Getting Started

Mostly Calva just works, but there are still some things to know beforehand. One good thing to know is that all commands and settings are of the category Calva, so bringing up the VSCode's list of commands or settings and searching for ”Calva” will take you a long way.

To connect Calva to your project, the procedure is:

0. Set up dependencies
1. Start a REPL
   1. For ClojureScript, also start a cljs-repl
2. Connect Calva

Dependencies

Calva depends on Cider and nREPL middleware. One place to configure them is in the ~/.lein/profiles.clj like so:

Clojure

{:repl {:plugins [[cider/cider-nrepl "0.18.0-SNAPSHOT"]]
        :dependencies [[org.clojure/tools.nrepl "0.2.13"]]}}

ClojureScript

Depends on if you are using Figwheel or Shadow-cljs. For shadow-cljs see the Calva section in the shadow-cljs User Guide.

For Figwheel, most projects has this setup in the project configuration file. But you can have it configured in your profiles.clj as well. A complete repl profile (from Calva's point of view), will look like so:

{:repl {:plugins [[cider/cider-nrepl "0.18.0-SNAPSHOT"]]
        :dependencies [[org.clojure/tools.nrepl "0.2.13"]
                       [cider/piggieback "0.3.8"]
                       [figwheel-sidecar "0.5.16"]]
        :repl-options {:nrepl-middleware [cider.piggieback/wrap-cljs-repl]}}}

Starting the REPLs

You need to start the REPLs outside Calva (usually in a terminal), then connect. If you are using Leiningen, that means something like:

$ lein repl

ClojureScript

For ClojureScript currently Figwheel and Shadow-cljs are supported.

Shadow-cljs

Shadow-cljs folks do not need to start an interactive repl. It's enough to start the app like so:

$ shadow-cljs watch <build>

For Calva to be able to connect the app needs to be started (opened in the browser or node running). Again see the Calva section in the shadow-cljs User Guide.

Figwheel

Start the ClojureScript REPL from the Clojure REPL prompt:

 => (use 'figwheel-sidecar.repl-api) (start-figwheel!) (cljs-repl)

(Consider adding a (start) function in your projects dev namespace to pack these calls together.)

The CLJS REPL will start when you open your app in the browser.

Connecting

In VSCode, connect Calva: ctrl+alt v, c.

Note If your workspace root is not the same as the project root of your Clojure project you must tell Calva which sub directory is the project root. Search for calva.projectRootDirectory in settings and modify the workspace settings. This path should be relative to the workspace root (which is why it defaults to .).

Customisations

Don't like my defaults? I just started a new page about customising things (work in progress).

Autolinting

The extension comes with autolinting disabled. This is because you will need to have Joker installed in order for it to work. You will probably want to have Joker installed regardless so, just do it and then enable autolinting by setting:

"calva.lintOnSave": true

Strange linting errors?

The Joker way of linting has its limitations. If you think the linting reporting is off, it is probably something you should check with the Joker project.

That said, this one might be worth a mention here:

Unrecognized macros

One thing to note with this linter is that it doesn't do a full scan of all files and does not recognize macros it doesn't know about. Leading to false complains about Unable to resolve symbol x. You might now and then tell it about macros you use. Create a .joker file somewhere in the path from the root of your project to where you are using the macro (the project root might be the best choice), and add:

{:known-macros [some-ns/some-macro some-other-ns/some-other-macro]}

Read more about Joker's linter mode here: https://github.com/candid82/joker#linter-mode

Other stuff

Paredit & Parinfer

Calva works nicely together with Paredit. Make sure you use the maintained version. We call it Paredit Revived.

However Parinfer clashes with the auto adjustment of indents feature. Therefore Calva provides a command for toggling the auto adjustment off and on (ctrl+alt+v tab), just like Parinfer has commands for enabling and disabling its assistance.

Consider these settings for keeping auto adjust of indents on:

    "parinfer.defaultMode": "disabled",
    "calva.autoAdjustIndent": true,

Switch them around if you prefer to default to Parinfer on. We'll be looking for a solution to this problem.