Clojure REPL-Driven Development with VS Code

In Software Development, fast feedback loops are essential to validating that code does what we intend. One of my favorite things about the Clojure ecosystem is the emphasis on REPL-driven development (Read Eval Print Loop).

This article explains at a basic level, how the REPL server communicates with the text editor and how to set up a Clojure REPL with VS Code.

Exploring the REPL

There are many ways to REPL, but this article focuses on exploring Clojure REPL with Leiningen, VS Code and the Calva extension.

What powers the REPL? The Calva extension uses nREPL under the hood, nREPL being a REPL server/client API for evaluating code remotely at run time. See more about it at nREPL.

What is REPL useful for?

The REPL is useful for getting fast feedback on code by evaluating code blocks and getting the response printed on a terminal session or output file. This allows one to see the expected return values and experiment with different types of inputs. We can initiate REPL sessions with any environment variable, we can mock code dependencies at run time, etc.

Set Up

• Make sure Leiningen installed on your environment. If this is your first time installing Clojure, Leiningen will also install Clojure for you.
• Clojure.
• VS Code.
• The VS Code Calva Extension

Create a Demo App

Use the lein command to create a new Clojure project. This command creates a new project with the necessary configurations to run Clojure with Leiningen:

lein new app my-app-name

Once the command runs, you will see the following file structure:

.
├── CHANGELOG.md
├── doc
│   └── intro.md
├── LICENSE
├── project.clj
├── README.md
├── resources
├── src
│   └── repl_demo
│       └── core.clj
└── test
    └── repl_demo
        └── core_test.clj

The REPL Workflow

The typical REPL workflow looks like this:

• Start the REPL session
• Evaluate a Clojure form
• See the output

Start the REPL

The demo project we created prints a string to standard output when we run it with lein run. Let's see how we can run the main function with the REPL:

On you terminal, run lein repl. You should see something like the below text, indicating that the REPL session has started.

nREPL server started on port 42815 on host 127.0.0.1 - nrepl://127.0.0.1:42815
REPL-y 0.5.1, nREPL 1.0.0
Clojure 1.11.1
OpenJDK 64-Bit Server VM 17.0.8.1+1-Ubuntu-0ubuntu122.04
    Docs: (doc function-name-here)
          (find-doc "part-of-name-here")
  Source: (source function-name-here)
 Javadoc: (javadoc java-object-or-class-here)
    Exit: Control+D or (exit) or (quit)
 Results: Stored in vars *1, *2, *3, an exception in *e

repl-demo.core=> 

Env Vars

To start a REPL session with environment variables, simply declare them before running the command:
MY_ENV_VAR=this-is-cool lein repl

Calva REPL Actions

All of these have a corresponding shortcut. I’m not including this here, due to OS and key-binding differences.

Connect to a running REPL

Open the VS Code command palette and search for connect to a running repl server . On the next prompt select Leiningen.

Load Current File and Its Deps

From the command palette, search form load/evaluate current file. This will evaluate all the code and imports.

Evaluate a Code Block

From the command palette, search for evaluate top level form. This will evaluate the code block where your editor cursor is.