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 and/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

From scratch using the Reagent Leiningen template

A quick way to get started with Clojure and ClojureScript is to use the reagent-template for Leiningen. It has all the dependencies required if you use the +cider option when creating a new project. From a terminal:

$ lein new reagent <project-name> +cider
$ cd <project-name>
$ lein repl
<project-name>.repl=> (user/start-fw) (user/cljs)

Note where the output says: Starting server at http://0.0.0.0:3449 That's where you surf with your browser to see the Hello World-ish webb app you've just built.

When you see the webb app running, open up <project-name> in VS Code and open a Clojure or ClojureScript file, then tell Calva to connect, ctrl+alt+v c (hold ctrl and alt down while pressing v, release all buttons and then press c). Then evaluate the file, ctrl+alt+v enter and everything should be set.

Not into Reagent, or have an existing project you want to use with Calva? Read on.

Dependencies

Calva depends on nREPL and Cider nREPL middleware. I recommend these versions (for now:

• org.clojure/tools.nrepl - 0.2.13
• cider/cider-nrepl - 0.19.0

I you are using Leiningen you do not need to add the nrepl dependency, just the cider-nrepl one.

One place to configure it (if you're using Leiningen) is in the ~/.lein/profiles.clj like so:

Clojure

{:repl {:plugins [[cider/cider-nrepl "0.19.0"]]
        :dependencies [[nrepl "0.5.3"]]}}

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.19.0"]]
        :dependencies [[cider/piggieback "0.3.10"]
                       [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:

 => (require '[figwheel-sidecar.repl-api :as figwheel]) (figwheel/start-figwheel!) (figwheel/cljs-repl)

(Consider adding something like a (start) function in your projects user 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

Instructions for WSL

If you want to use this extension with WSL, there are a few things that need to be configured first.

1. The useWSL option must be set to true and you must add a valid WSL path to the jokerPath option.
2. Make sure that you have Windows 10 version 1803 since that's the version that includes the wslpath tool which is used to convert between WSL and Windows paths.
3. If you're using Leiningen and if you want to view definitions of source files (e.g. println, defn, def) you will need to change your .m2 directory to a location directly accessible by Windows. For example, you could edit your ~/.lein/profiles.clj like so:

{:user {:local-repo "/mnt/c/Users/<Your User>/.m2"}}

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.