Publishing a ClojureScript library toClojars (in 2017)

Recently, mostly as an exercise in learning the Clojure ecosystem, I decided to try publishing a library to Clojars. I’ve published a handful of hacky things in NPM, and was curious how to do the same in the Clojure ecosystem.

Create your project

Assuming you’ve got Clojure and Leiningen installed, head to a terminal, and create your library:

lein new my-lib

Testing ClojureScript with doo

My project.clj has the following plugins entry:

:plugins [[lein-cljsbuild “1.1.6”]
          [lein-doo “0.1.7”]]

This gives us ClojureScript support and adds in a super handy testing utility called “lein doo” which allows us to re-run all of our ClojureScript tests anytime we make changes.

You can check it out by running this in a new terminal tab/window:

lein doo node test

Prettifying testing errors

Clojure’s default test results are somewhat hard to grok. Fortunately, there’s a handy utility called humane-test-output.

I have the following :profiles section in my project.clj which enables this swank behavior:

:profiles {:dev {:dependencies [[pjstadig/humane-test-output “0.8.2”]]}}

Now, if you stop and restart `lein doo node test`, and modify your tests to error, you’ll see more helpful error output.

Building ClojureScript

Lastly, I added the :cljsbuild section to my project.clj. I’m not sure how important all of this is, but it worked for me, and I wanted to note it here for my own future reference:

:cljsbuild
{:builds {:minify {:source-paths ["src-cljs"]
                   :compiler {:optimizations :advanced
                              :pretty-print false}}
          :dev {:source-paths ["src-cljs"]
                :compiler {:optimizations :whitespace}}
          :test {:id "test"
                 :source-paths ["src-cljs" "test"]
                 :compiler {:output-to "target/cljs-tests.js"
                            :output-dir "target"
                            :main my-lib.runner
                            :optimizations :none
                            :target :nodejs}}}}

I have my ClojureScript source in a “src-cljs” directory, and all of my tests included in “runner.cljs” which looks like this:

(ns my-lib.runner
  (:require [doo.runner :refer-macros [doo-tests]]
            [pjstadig.humane-test-output]
            [my-lib.core-test]))
(doo-tests 'my-lib.core-test)

Publishing to Clojars

After you’ve written your fancy library, and unit tested the snot out of it, you’re ready to publish it for all the world to see.

Sign up for Clojars, and install the visual GPG tools. You want the GPG GUI, not the CLI. The CLI and lein seem to no longer be besties. Many Bothans died to bring us this information.

Once you have GPG’s visual tools installed, you can run this command from your terminal in order to publish:

lein deploy clojars

The first time you run it, you may have some GPG key generation to do, ect, but lein’s messaging should guide you through that easily enough.

That’s all, folks!

Clojure is a really nice language and ecosystem, but sometimes online documentation can be hard to come by. I had a bit of a time trying to get humane test output with ClojureScript, and a bit more of a time trying to get GPG working with the lein deploy clojars command. So, I hope this little writeup will save someone some of this pain, even/especially if that someone is my future self!