/clojureVSCode

Clojure support for Visual Studio Code

Primary LanguageTypeScriptMIT LicenseMIT

clojureVSCode

Version Build Status

Clojure and ClojureScript support for Visual Studio Code.

If you are a ClojureScript user, please read this section carefully.

I'm trying, believe me!

Quickstart

Make sure that Leiningen is installed on your machine, open a Clojure file or project, wait until the extension starts the nREPL (see status on the bottom of the VSCode window) and connect to it - now all the goodies should work :-)

Doesn't work? Not exactly what you need? See the Manual Configuration section!

Supported Features

  • Code completion

Code completion example

  • Code navigation

Code navigationtion example

  • Interaction with REPL
  • Showing documentation on hover
  • Code formatting (cljfmt)
  • Function signatures
  • Integration with the Clojure unit test framework

Code completion example

Features That Are not Supported (but Nice to Have)

Connecting to the REPL

  • Open a terminal (either the one embedded in VSCode or a separate one)
  • Change directory to the root directory of the Clojure project (where the REPL started by clojureVSCode will have updated the hidden file .nrepl-port)
  • with lein, do lein repl :connect.

Evaluating code in the REPL

Clojure: Eval (in the command palette) will compile the current file in the editor and load it in the REPL.

Manual Configuration

The method from the Quickstart section utilizes the so-called embedded nREPL that is run as an internal process. Sometimes you need more control on your development environment. In this case you can disable the automatical firing of the embedded nREPL by setting the

"clojureVSCode.autoStartNRepl": true

option in your VSCode settings globally or per-project and connect manually to whichever REPL instance you want by "Clojure: Connect to a running nREPL" command. Note, that in order to make the autocompletion, go to definition, and formatting functionality work you have to write necessary dependencies in your profiles.clj. Put the following content to your ~/.lein/profiles.clj for macOS and Linux:

{:user {:plugins  [[cider/cider-nrepl "0.24.0"]]
        :dependencies [[cljfmt "0.6.7"]]}}

Alternatively, you can put the code above to your project project.clj file.

Contributed Configuration

The extension contributes the configuration parameters listed in the table below.

Parameter Description
clojureVSCode.autoStartNRepl Whether to start an nREPL when opening a file or project.
clojureVSCode.formatOnSave Format files with cljfmt on save.
clojureVSCode.cljfmtParameters Formatting parameters passed to cljfmt each time it runs, e.g. :indentation? true :remove-surrounding-whitespace? false
clojureVSCode.showResultInline Show evaluation result inline.
clojureVSCode.ciderNReplVersion Version of CIDER nREPL to use for the embedded nREPL.
clojureVSCode.cljfmtVersion Version of cljfmt to use for formatting Clojure files.

ClojureScript Project Setup

The extension has the experimental support of ClojureScript. The example of a ClojureScript project setup can be found here. Checkout the project profile.clj file to learn what dependencies you need.

The embedded nREPL does not support ClojureScript, consider to use the "clojureVSCode.autoStartNRepl" setting. You will need to run an nREPL manually and execute the following commands inside it:

(require 'cljs.repl.node)
(cider.piggieback/cljs-repl (cljs.repl.node/repl-env))

After that you can connect to the nREPL using the "Clojure: Connect to a running nREPL" command. Now you can evaluate you ClojureScript code and use the other extension facilities.

Troubleshooting

All kinds of errors on nREPL start

Please check that you're using the latest version of CIDER nREPL. The version the extension uses by default updates periodically, but there still can be a mismatch. In order to redefined the CIDER nREPL version you can either:

  1. Define it in the ~/.lein/profiles.clj (see the "Manual Configuration" section above).
  2. Redefine it with the clojureVSCode.cljfmtVersion extension setting.

How to Contribute

Open an issue if you want to propose new features and ideas or to report bugs. If you want to help with some code and looking for a place to start, please check out the How to Contribute wiki page.

Thanks

License

MIT