Can building ClojureScript assets be integrated into my build process?

Summary: ClojureScript’s official build process is a simple shell command. There is also integration into Leiningen and Boot.

It really depends on your build process. But the short answer is probably yes. I’ll go over three ways to add advanced compilation for a production build to your project. You can pick whichever works better for you.

Command line

The official way to use the ClojureScript compiler is from a ClojureScript release JAR on the command line. And since the JVM runs on almost every platform, you’re probably golden. You can just add it to your build script.

A production build is simple. With this release.clj file:

(require 'cljs.build.api)

(cljs.build.api/build "cljs-src"
  {:output-to "out/main.js"
   :optimizations :advanced})

(System/exit 0)

You can run the command from your shell:

> java -cp cljs.jar:cljs-src clojure.main release.clj

You’ll need Java 8 and cljs.jar. That will do an advanced optimization compile of ClojureScript code in cljs-src/ and the output will be in out/main.js, ready to include in your HTML page or elsewhere.

This is great if you’re using Make or some other shell language to build your system. Note also that the cljs.jar can also do other types of builds, including incremental builds. See the Quickstart for more information.

Leiningen

If you’re already using Leiningen, you might as well use it to build you ClojureScript as well. There’s a well-supported plugin called lein-cljsbuild. Getting it set up is a little trickier but depending on how things are already set up, it may fit right in.

In your project’s project.clj, you’re going to add some directives inside of defproject.

First, let’s add the plugin (check Clojars for the most recent version):

:plugins [[lein-cljsbuild "1.1.0"]]

configure the build:

:cljsbuild {:builds {:prod {;; where your code is
                            :source-paths ["cljs-src"]
                            ;; do build this when making a jar
                            :jar true
                            ;; the same compiler options as above
                            :compiler {:output-to "out/main.js"
                                       :optimizations :advanced}}}}

Then, you should turn on the cljsbuild hooks, which will make sure ClojureScript is handled in common Leiningen commands:

:hooks [leiningen.cljsbuild]

Now if you type:

> lein uberjar

Code in cljs-src/ will be compiled and included in your jar (in the out/ directory; change that to where you want it, of course!). If you just want to build the ClojureScript:

> lein cljsbuild once

I use cljsbuild when I’m deploying stuff to Heroku or CircleCI.

Boot

Boot is another build tool for Clojure. If you’re using it, there is a ClojureScript build task called boot-cljs.

In your boot.boot file, add this dependency (check Clojars for the latest version):

:dependencies [...
               [adzerk/boot-cljs "1.7.48-3"]
               ...]

And this source path:

:source-paths #{... "cljs-src" ...}

Add this requires:

(require '[adzerk.boot-cljs :refer [cljs]])

Then create a file called cljs-src/out/main.cljs.edn and put this in there:

{:require [foo.core]}

Replace foo.core with the main namespace of your application. Typically, the ClojureScript compiler would read in all of the .cljs files in your source directory. But Boot adds a way to restrict what gets compiled.

Then run:

> boot cljs -O advanced

That will compile your code and output it to out/main.js

If you already have a build task scripted up, you can add the cljs task to it to have your ClojureScript compiled for you.

Conclusions

The ClojureScript build story is very mature now. There are multiple options available to suit different existing build processes.

If you’re interested in getting started with ClojureScript, I recommend LispCast Single Page Applications with ClojureScript and Om. It uses Om (a React wrapper) to build an application from the ground up. The course teaches everything you need using animations, exercises, code screencasts, and more. It’s the fastest and most effective way to learn to build ClojureScript applications.