Working with Deps

Deps is a simple tool for managing dependencies in Clojure projects. It's designed by the Clojure core team to facilitate two main things - managing dependencies and creating a classpath. It deliberately takes a different approach to Leiningen which is a batteries-included do-everything tool, but Deps has seen a lot of uptake because for the projects it works for it works very well, and it's considerably simpler than Leiningen and other alternatives. Let's see how to use Deps with Cursive.

Configuring Deps

As of version 1.13.0, Cursive uses deps.clj to manage deps. It should just work out of the box, but it has some configuration at Settings→Build, Execution, Deployment→Build Tools→Clojure Deps. Cursive will automatically download both deps.clj and deps itself as needed. Each version of Cursive ships with the list of deps.clj versions which are current at the time it was released, but you can also press Refresh, and Cursive will download the list of currently available versions - generally the latest is the one you want.

If you're in an environment where you don't have outbound access to the internet and you're using an internal Maven repo to fetch your deps, you can use the "Use private repo" option and specify the ID and the URL of your internal repo. Cursive will also respect the IntelliJ HTTP proxy configuration when fetching deps.clj.

Create a new project with Deps

To create a new project in IntelliJ, if you're at the welcome screen, click the "Create New Project" link, or if you already have a project open in IntelliJ you can use File→New→Project.... In the following dialog, choose "Clojure" from the list of project types on the left-hand side. You'll then have a list of Clojure project types to choose from on the right. Here you can choose "Deps".

On the next screen, give your project a name and decide where to put it:

On this screen you're also asked to choose a "Project SDK". On the JVM, this means the JDK or JRE you want to use. If you have a JDK installed then click "New..." to set it up in IntelliJ, it will detect it automatically. If you don't have one already installed IntelliJ will create one for you which uses the JRE bundled with IntelliJ itself. This works fine for Clojure and means that you don't need to download a JDK to get started.

Then, when you click "Finish" you'll have a new project to work with!

Quick project import

For most existing projects you don't need to explicitly import them. Just use File→Open... or select "Open File or Project" from the welcome screen, and select either the deps.edn or the containing directory:

Confirm that you would like to open it as a project:

And your project will be automatically imported:

Import an existing Deps project

For more control over how your project is imported, you can use the Import Project workflow. To do this you can use File→New→Project from Existing Sources.... Here, you can select either the deps.edn file or the directory containing it.

If required, select "Import project from external model" and select Deps.

The root directory of your project will be filled in for you. You can choose to search recursively within that directory for other projects (see Multi Module Projects, below), and you can also choose to put the project files in a directory other than the main project directory.

You will then be presented with a list of the Deps projects found, and you can select which to import. In this case, since this is a simple single-module project, there's only one.

Next, you'll be asked to choose an SDK. This is a generic name that IntelliJ uses for any type of project, but since Clojure is a JVM language this is referring to the Java JDK you would like to use. You can set one up here, or select one you already have set up. If you don't have one already installed IntelliJ will create one for you which uses the JRE bundled with IntelliJ itself. This works fine for Clojure and means that you don't need to download a JDK to get started.

Next, confirm your project name and location, and then press 'Finish' to actually import the project.

Your project will then be opened and is ready to use.

Working with aliases

Often Deps projects will use aliases for different situations. Since aliases will often add source roots and dependencies that you'll need when working with your source code, you can let Cursive know which ones it should use when synchronising your project.

To do that, open the Deps toolwindow, then expand out the Aliases tree. Select the aliases you'd like to use when synchronising, then refresh your project using the icon.

Working with tools

Recent versions of deps contain support for tools, most notably In the Deps toolwindow, under the Aliases tree described above, you'll find a Tool Aliases tree. When you select an alias as a tool and refresh your project, a new library will be created under External Libraries in your Project View. This library will contain the classpath of the tool. That classpath will be used for symbol resolution in files identified by the :ns-default and :ns-aliases entries in the tool alias.

Coming soon: Currently, only namespaces explicitly named in the deps.edn file will get this support, but this will be improved soon to include other transitively included namespaces.

Note: The IntelliJ feature used for this feature can be a little flakey. If you find symbols are not resolving correctly after changing the tool classpath, just close your project (not IntelliJ completely) and then reopen it.

Viewing your project dependencies

One thing that is very useful when working with Deps is being able to see a tree of the dependencies of your project. On the command line you would use clojure -Stree to show this, but Cursive will show you this within the IDE too, also in the Deps toolwindow. The dependencies are nested in a tree structure so you can see how each dependency was pulled into your project:

Refreshing Deps dependencies

When you have updated your deps.edn file, you can press the icon to re-read the project file and refresh the project dependencies. Note that this is not performed automatically when the deps.edn is updated, unlike the Maven plugin, but you will get a notification with a link to update.

Downloading and attaching source artefacts

Often, especially when working with e.g. Java dependencies, it's useful to be able to attach sources to the libraries that are created when a project is imported. IntelliJ does this by default for all Maven or Gradle dependencies, but this is very slow when using Clojure since most artefacts are published without source (or, more correctly, the sources are actually the binary artefact). If Cursive tries to download sources for all artefacts, it is very slow since the Maven resolver will go out to all the remote repositories for every artefact looking for sources which will never exist.

Maven-like things publish the source artefacts using the "sources" classifier. In deps, these can be downloaded using, e.g.:

junit/junit {:mvn/version "4.13.2"}
junit/junit$sources {:mvn/version "4.13.2"}

Cursive will detect if a downloaded artefact contains sources for another, and attach it if so. The sources can also be specified in an alias which is only used to sync to Cursive, meaning that the sources will not be resolved for other uses, e.g:

{:deps    {junit/junit {:mvn/version "4.13.2"}}
 :aliases {:ide {:extra-deps {junit/junit$sources {:mvn/version "4.13.2"}}}}}

This allows you to specify which dependencies you want sources downloaded for in a non-intrusive way.

Cursive has full support for IntelliJ's Package Search feature when working with Deps. You can search for dependencies, add them to your project, see which versions are out of date, etc. You can find this in the Dependencies toolwindow. JetBrains' full documentation for this feature is here.

Working with multi-module projects

If you have a more complex project with multiple modules, Cursive will detect it automatically and set everything up. When importing, make sure you check "Search for projects recursively".

Select the projects you would like to import from the list of discovered projects. Their location within the project is displayed along with the artifact details.

And your project will be set up. An IntelliJ Module will be created for each Deps project, and dependencies between them and the appropriate library dependencies will be set up as well.

You can then add new modules to the project using either the button in the Clojure Deps tool window, or using the context menu in the project tool window. You can remove Leiningen modules from the project and remove the corresponding IntelliJ module using the in the Clojure Deps tool window.

Working with Leiningen Other Project Types