Calva Power Tools

A VSCode extension, and Calva companion, for Clojure and ClojureScript development that adds commands for popular Clojure libraries and tools. Including commands for dynamically loading the tool dependencies.

Usage

1. Install the extension from the VSCode Marketplace.
2. The commands are available from the command palette. There is a default keybinding for filtering the palette on the Calva Power Tools commands: ctrl+shift+space ctrl+shift+space.

There is a quick demo/howto here: https://youtu.be/GiWKX-0NqkM

Default keybindings included

The Calva Power Tools extension generally contributes default keybindings for the commands. They are all chained on a first chord of ctrl+shift+space, a.k.a. the Power Key. Then, generally, each tool has its key, e.g. Snitch uses the Tool Key s. You can thus execute Snitch commands with ctrl+shift+space s something.

There are also default bindings for filtering the command palette on a specific tool. Generally the ctrl+shift+space ctrl+shift+tool-key. E.g. to list the Snitch commands:

• ctrl+shift+space ctrl+shift+s

The Tools

A hopefully growing list of power tools.

Tools-deps, add-libs

• tools-deps

A set of commands leveraging Clojure 1.12 add-libs:

• tools-deps: Load Dependencies...: Will prompt for and load dependencies.
• tools-deps: Load Selected Dependencies): Add one or more deps.edn dependencies coordinate that you have selected in the editor. E.g. if you have added it to your deps.edn file and want to load the dependency without restarting your REPL (or you may have some comment in the code with the dependency coordinates): Select the key-value pair(s) for the dependencies and then run this command.
• tools-deps: Sync deps.edn Dependencies...: Sync (load any missing) dependencies in deps.edn. Prompts for aliases.

Tool Key: d

Clay

• Clay

Tool Key: a

Explore the Clay commands from the VS Code command palette by fuzzy searching “Clay”. Also check this intoduction out: https://www.youtube.com/watch?v=B1yPkpyiEEs

Snitch

Snitch is inline-defs on steroids. See https://github.com/AbhinavOmprakash/snitch. Search the command palette for “Snitch”.

Tool Key: s

This menu screenshot is showing the default key bindings. I (PEZ) am on a Mac and can recommend binding the Snitch: Instrument defn command to cmd+enter.

Performance

There are commands for four important tools when chasing performance gains in Clojure. For loading dependencies as well as basic usage:

Tool Key: s. Further each “sub-tool” has a key, c/d/p/t for Criterium/clojure-java-decompiler/clj-async-profiler/time, respectively. Example: Loading the dependency for Criteriums is ctrl+shift+space p c l, to be read as Power Tools, Performance, Criterium, Load.

Criterium

clojure-java-decompiler

clj-async-profiler

time

Dataspex

Dataspex is an easy to use, and powerful data inspection tool/browser for both frontend and backend applications. It supports watching atoms, Datascript, and Datomic databases. There is a browser extension so you can watch your frontend app's state where it runs.

With Calva Power Tools it is easy to take it for a spin, without updating your project configuration. To use the browser extension, you'll need to install that separately, but without installing anything you can test Dataspex inside VS Code:

With a ClojureScript frontend app you do this by using the command: [CPT] Dataspex: Show Browser Extension Inspects in VS Code

Tool Key: x

Backend workflow

Use the Dataspex command palette to:

• Inspect something
• Open the Dataspex inspector (sidebar) panel (and/or open the inspector in the editor view)
• Inspect something more

If you don't have the Dataspex dependency configured/loaded in your project, you will be offered to do tis dynamically (and this needs Clojure 1.12 or newer to work).

Frontend workflow

This is the most convenient if you have Dataspex configured in the app to inspect the app's state atom/datascript db:

1. Start and connect your frontend app
2. [CPT] Dataspex: Show Browser Extension Inspects in VS Code

Then you can inspect other values using the Dataspex commands.

Without Datspex configured in the project:

1. Start and connect your frontend app
2. [CPT] Dataspex: Show Browser Extension Inspects in VS Code
3. Inspect the app's state atom/db

Backend + frontend workflow

In addition to the above workflows, you can use the Dataspex command palette to show server inspects in the browser extension.

Use the REPL for the full Dataspex API

The commands included in Calva Power Tools support the basic and common workflows. You can of course go beyond this by calling the Dataspex API yourself from the repl.

Contributing

Issues and pull requests are welcome. Please see CONTRIBUTING

Adding a new command

1. Add the command name and title in package.json.
   • The command name should be unique and follow the format <library>.<command>.
   • The title should be a human-readable name for the command.
   • The command should be added to the contributes.commands array.
2. Add keybindings for the command in package.json (optional).
   • The keybinding should be added to the contributes.keybindings array.
3. Add clojure snippets they should invoke in src/calva_power_tools/tool (see src/calva_power_tools/tool/clay.cljs for an example).
   • Fully qualify symbols in snippets to avoid uninitialized namespace issues
4. Register them in src/extension.cljs in the activate function.

Development

The paved path is:

1. npm run watch. This starts Clojure with an nREPL server. (You can run the build task command inside VSCode).
   • Wait for it to report something like:

     nREPL server started on port 56749 on host localhost - nrepl://localhost:56749
     

2. ctrl+alt+c ctrl+alt+c. This runs the command: Calva: Connect to a Running REPL Server in the Project
   • It will connect the Clojure REPL, start a ClojureScript (shadow-cljs) REPL, and build the extension.
   • This will compile the extension and run the tests. Wait for the Build+watch extension to show that the tests have ran, and for Calva to pop up a progress dialog about starting your ClojureScript app (which is your extension in this case).
3. F5. This starts the VS Code Development Extension Host (because configured to do so in .vscode/launch.json)
   • The development extension host is a VS Code window where your extension under development is installed. You now need to activate it to actually start the ClojureScript app.
   • The extension auto-activates, now your ClojureScript app and its REPL is started 🎉
4. Back in the development project you will see the progress dialog go away. Because now the development project window is connected to the Development Extension Host window's REPL.
   • Now you can hack on the extension code, which will update the app in the extension host window while it is running (a.k.a. interactive programming).

An important thing to note here is the steps where you activate your extension in the development host, starting the ClojureScript repl which Calva can connect to.

License

MIT

Free to use, modify and redistribute as you wish. 🍻🗽

Built VSC-ET, the VS Code Extension Template

• https://github.com/PEZ/vscode-extension-template