atlas book skeleton

Setting Up Your ClojureScript Environment

Setting Up ClojureScript

ClojureScript is a dialect of Clojure that compiles to JavaScript. Clojure is a Lisp dialect that runs on the Java Virtual Machine. So, in order to use JavaScript, you need Java and Clojure.

Getting Java

You can test to see if Java is already installed on your computer by opening a command window (on Windows) or a terminal window (on Mac OSX or Linux) and type java -version at the command line. If you get some output describing a version of Java, such as the following, you have Java installed. 

java version "1.8.0_40"
    Java(TM) SE Runtime Environment (build 1.8.0_40-b26)
    Java HotSpot(TM) 64-Bit Server VM (build 25.40-b25, mixed mode)

If you get an error message, then you need to install Java. You may either use OpenJDK or Oracle’s Java Development Kit. Follow the download and installation instructons you find there.

Getting Clojure and ClojureScript

If you want to get started quickly with ClojureScript, I recommend that you follow the instructions at the aptly named ClojureScript Quick Start page. From that page, you can download a jar file that has “the ClojureScript compiler and the bundled REPLs without an overly complicated command line interface.”

Creating a ClojureScript Project

Again, using the instructions at the Quick Start page, I created a project named sample-project. (I am sick and tired of “Hello, world!” so I did something slightly different.)

Here is the file structure of the directory, with files organized by category rather than alphabetical order. Notice that the project name sample-project has a hyphen in it, but when used in a directory name, you replace the hyphen with an underscore: sample_project. 

sample_project
├── cljs.jar
├── src
│   └── sample_project
│       └── core.cljs
├── index.html
├── build.clj
├── release.clj
├── repl.clj
└── watch.clj

The cljs.jar file contains ClojureScript, downloaded from the link at the Quick Start page.

ClojureScript File src/sample_project/core.cljs

This is the ClojureScript file for the project; it simply prints to the console. 

;; remove the :require and defonce when building the release version

(ns sample-project.core
  (:require [clojure.browser.repl :as repl]))

(defonce conn
  (repl/connect "http://localhost:9000/repl")) 

(enable-console-print!)

(println "It works!")

File index.html

This file has a bit more than the Quick Start file: the addition of the <meta> element avoids a warning in the web console, and the <title> element lets you distinguish projects from one another if you have multiple browser tabs open. 

<!DOCTYPE html>
<html>
    <head>
        <title>sample-project</title>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    </head>
    <body>
        <script type="text/javascript" src="out/main.js"></script>
    </body>
</html>

File build.clj

Builds an un-optimized version of the project. Run with the command 

(require 'cljs.build.api)

(cljs.build.api/build "src"
  {:main 'sample-project.core
   :output-to "out/main.js"})

File release.clj

Builds an optimized version of the project. 

((require 'cljs.build.api)

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

(System/exit 0)

File repl.clj

Builds an unoptimized version of the project and launches a browser REPL. On Linux and MacOSX, make sure you have rlwrap installed. 

(require 'cljs.repl)
(require 'cljs.build.api)
(require 'cljs.repl.browser)

(cljs.build.api/build "src"
  {:main 'sample-project.core
   :output-to "out/main.js"
   :verbose true})

(cljs.repl/repl (cljs.repl.browser/repl-env)
  :watch "src"
  :output-dir "out")

File watch.clj

This program watches the src directory and recompiles when any file in that directory changes. 

(require 'cljs.build.api)

(cljs.build.api/watch "src"
  {:main 'sample-project.core
   :output-to "out/main.js"})

Getting A Text Editor

You can use any text editor you like to create your ClojureScript programs. The emacs editor seems to be quite popular, with vim another popular choice. Yes, both have plugins for support of Clojure (CIDER for emacs; Fireplace for vim). No, I will not get involved in the theological battle between these two editors. If you are in search of an IDE (Integrated Development Environment), you have a number of choices there as well: