Clojure Workflowλ︎

The REPL workflow is an effective way to develop Clojure projects.

Create Projectλ︎

Creating projects using a template is a quick way to get started. A template will create the project structure, add libraries and even include example code.

Practicalli Project Templates

practicalli/project-templates provide production level templates that include Practicalli REPL Reloaded Workflow tools, Docker & Compose configurations, Makefile tasks for a consistent command line UI and GitHub workflows to manage quality of code and configuration.

practicalli/minimal - production level project with minimal code examples
practicalli/application - production level project template with Mulog, Docker, Make, MegaLinter, etc.
practicalli/service - production level web services template with Integrant, Http-kit, Reitit, Mulog, Docker, Make, MegaLinter, etc.

Use deps-new to create a project, specifying a template and a name for the project.

Open a terminal window and change to a suitable folder and create a project using :project/create alias from Practicalli Clojure CLI Config

clojure -T:project/create

The -T execution option runs the tool with Clojure.exec which uses keywords to specify the options for creating the project.

:project/create alias uses :template practicalli/minimal :name practicalli/playground arguments by defauls, which can e overridden on the command line

The name of the project is of the form domain/app-lib-name. Use a company name or Git Service account name as the domain.

Open Projectλ︎

Run the command code . from the root of a Clojure project or run VSCode and use the VSpaceCode key bindings to open a project.

Space f f and open the Folder that contains a Clojure project. Select the top level of the folder, e.g. playground and click OK

Start a REPLλ︎

Either start a terminal UI repl and connect to it from Calva, or use Calva jack-in to start a repl and automatically connect.

Start REPL via VSCode terminal

Ctrl+` toggles open the VSCode Integrated terminal. Or open your operating system terminal.

In the terminal, change to the folder than contains your project, e.g. cd projects/clojure/playground

Configure the VS Code internal terminal to use the GitBash shell.

Terminal UICalva jack-in

Change into the directory and test the project runs by starting a REPL with Terminal REPL

Start rich terminal UI REPL

cd playground && clojure -M:repl/rebel

A repl prompt should appear

Type code expressions at the repl prompt and press RETURN to evaluate them.

Evaluate code at REPL prompt

(+ 1 2 3 4 5)

Switch to VSpaceCode with the Clojure playground project open.

, ' to connect to the REPL process started in the terminal UI

Select the tool to use to start the repl

Confirm the host and port of the REPL, this should be automatically detected. These details were shown when the REPL was run in the terminal.

Wait a few moments for the REPL to start.

Open the playground project in VS Code.

, " to jack-in to a Clojure REPL for the project. This starts an external REPL process and connects to it.

Select deps.edn for Clojure CLI when prompted for the project type

Select the tool to use to start the repl

Wait a few moments for the REPL to start.

Once the REPL is connected, the REPL name with a lightning bolt icon is displayed in the status bar.

Troubleshooting

If the REPL did not start, the nREPL link in the bottom blue bar will show the word "Disconnected".

Open the Output tab to see the progress of the REPL starting.

Try running a REPL in a terminal and connecting to it.

Evaluating Clojure codeλ︎

, e f to evaluate a top-level expression and see the results inline. Or , e s to select a specific expression and , e e to evaluate it.

, e l to clear all the evaluated results.

Keybinding	Description
`, e ;`	Evaluate the current expression and paste as comment
`, e :`	Evaluate the current expression and paste as comment
`, e e`	Show the result of the current expression
`, e f`	Show the result of the top level expression
`, e l`	Clear all the evaluated results
`, e n`	Evaluate all code in the current file/namespace
`, e w`	Replace the expression with its result

Running testsλ︎

, e n to evaluate all the unit test code in the current window

, t a to run all the unit tests in the project

, t f to run just the failing tests

Keybinding	Description
`, t a`	Run all tests in the project
`, t f`	Run all tests for the current namespace
`, t n`	Run all tests for the current namespace
`, t t`	Run all tests for the current namespace

Test results shown in REPL

The REPL window is used to display the results of running unit tests

Commenting / uncommenting codeλ︎

SPC c l toggles a comment on the current line.

Use the Add Line Comment command to place ;; at the start of a line, which comments it out.

Lintingλ︎

, c n and , c N cycle through clj-kondo linting warnings

Increase / decrease font sizeλ︎

Ctrl + and Ctrl - will increase and decrease the size of the whole editor.

SPC SPC and type the command Preference: Open Settings (JSON) to open the settings.json configuration file. Update the value for editor.fontSize and save the file. The font should update immediately in the VS Code UI.

Other useful options that can be added to the settings.json configuration

settings.json

   "workbench.colorTheme": "Solarized Light",
    "editor.fontSize": 14,
    "editor.fontFamily": "'Fira Code', 'Ubuntu Mono', 'Droid Sans Mono', 'monospace', monospace, 'Droid Sans Fallback'",
    "window.zoomLevel": 1,
    "calva.paredit.defaultKeyMap": "strict"

Structural editing - Pareditλ︎

, k is the structural editing menu.

Structural editing ensures code can be written and edited without breaking the structure of Clojure. Structural editing ensures you dont have uneven parentheses, (), [], {}, etc.

The Calva visual Guide to Paredit includes lots of examples of using Structural editing.

Keybinding	Description
`, k .`	Toggle paredit strict mode
`, k b`	Barf forwards
`, k c`	Convolute expression
`, k h`	Jump backwards
`, k j`	Jump forward down an expression
`, k k`	Jump backwards down an expression
`, k l`	Jump forward an expression
`, k r`	Raise an expression (over-write parent expression)
`, k s`	Slurp forward
`, k t`	Transpose expression
`, k w (`	Wrap with ()
`, k w [`	Wrap with []
`, k w {`	Wrap with {}
`, k w "`	Wrap with ""
`, k w p`	rewrap with ()
`, k w s`	rewWrap with []
`, k w c`	rewWrap with {}
`, k w q`	rewWrap with ""