Last Updated: March 07, 2016

Setting up a ClojureScript project

The goal of this tutorial is to setup a development environment that gives you the building blocks of a ClojureScript application - destined to run in a web browser.

You will create a new ClojureScript project with a simple design goal - to display a greeting in a Web browser saying "Hello Browser" - leaving the rest up to your imagination and determination.

This tutorial is intended for people who have a basic knowledge of the Clojure programming language & its data structures and are interesting in exploring writing Browser applications using ClojureScript.

Since the approach of this tutorial is "by example" - before you start you will need to have a functioning Clojure development environment and Leiningen(version 2.5.0 at time of writing) installed.

Creating a new project

To get started, open a new terminal and create a new project using the lein</code> command:

$ lein new hello-browser

# Generating a project called hello-browser ...

$ cd hello-browser

Organising your source code

Lets take a look at the source code structure of the project leiningen created for us:

$ ls src/hello_browser

# core.clj

By default, leiningen assumes ONLY Clojure source code - it creates the source directory src/hello_browser</code> along with the source file src/hello_browser/code.clj</code> to keep your Clojure source neatly organised.

Since our application uses ClojureScript source code(as opposed to Clojure) we need to structure our project accordingly and make some minor changes to the source structure.

Lets first remove the default Clojure source directory(since we will only be using ClojureScript):

$ rm -rf src/hello_browser

We will be storing our ClojureScript source in the src/cljs/hello_browser</code> directory - so lets create it:

$ mkdir -p src/cljs/hello_browser

Configuring cljsbuild to compile ClojureScript

cljsbuild will be responsible for compiling our ClojureScript into Javascript. In order to do this we have to tell cljsbuild about the location of our ClojureScript source & where to output the compiled javascript.

We do this by editing the project.clj</code> file - adding a dependancy on clojurescript & the cljsbuild leiningen plugin, including build instructions for the cljsbuild:

(defproject hello-browser "0.1.0-SNAPSHOT"
  :dependencies [[org.clojure/clojure "1.6.0"]
                 [org.clojure/clojurescript "0.0-2411"]]

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

  :cljsbuild {
    :builds [{:source-paths ["src/cljs"]
              :compiler {:output-to "resources/public/core.js"}}]})

We are instructing cljsbuild to look for ClojureScript source code in the src/cljs</code> directory and to output the compiled javascript to a single file resources/public/core.js</code>.

Compiling your ClojureScript

Now that we have setup our leiningen project, a directory structure to store our ClojureScript source code and configured cljsbuild - we can create our first ClojureScript source file.

Lets keep things simple - the design goal of this project is to simply display a greeting saying "Hello Browser". Lets create our first ClojureScript source file src/cljs/hello_browser/core.cljs</code>:

(ns hello-browser.core)

  (.write js/document "<h1>Hello Browser</h1>")

We are defining a namespace hello-browser.core and writing the "<h1>Hello Browser</h1>" string to the document(taking into account this ClojureScript is destined to run within a browser).

From a new terminal, we can use the lein command, along with cljsbuild plugin, to compile our ClojureScript into javascript:

$ lein cljsbuild once

#Compiling ClojureScript.
#Compiling "resources/public/core.js" from ["src/cljs"]...
#Successfully compiled "resources/public/core.js"

Based on the cljsbuild configuration in the project.clj</code> file the lein cljsbuild command has compiled all ClojureScript source files(src/cljs</code>) into Javascript(resources/public/core.js</code>).

While building the file once is useful(i.e pre-deploy) during development we will expect a lot of changes to the ClojureScript source files. It would be a pain to run a command after every change - enter lein cljsbuild auto :

$ lein cljsbuild auto
#  Compiling ClojureScript.
#  Compiling "resources/public/core.js" from ["src/cljs"]...
#  Successfully compiled "resources/public/core.js"

Using lein cljsbuild auto</code>, anytime a ClojureScript source file changes, cljsbuild will automatically re-compile the javascript.

It is also occasionally useful to delete all the compiled javascript for a clean slate:

lein cljsbuild clean

#  Deleting files generated by lein-cljsbuild.

An environment for your ClojureScript

Since our ClojureScript is compiled into Javascript, we need a browser environment to run it in. To achieve this we will create a html page that refers to the compiled javascript.

Since our Clojure script is compiled into resources/public/core.js</code> we will create a simple resources/public/index.html</code> html file, which will reference the compiled core.js</code> file.

<!DOCTYPE html>
<html>
    <head><title>ClojureScript Hello Browser</title></head>
    <body>
      <script type="text/javascript" src="core.js"></script>
    </body>
</html>

Opening the resources/public/index.html</code> file, will present a Greeting "Hello Browser" - indicating the ClojureScript was compiled successfully.