Skip to content

Quick Start

Jump to bottom Edit New page
dnolen edited this page Mar 7, 2015 · 218 revisions

NOTE: This wiki page is under development for ClojureScript >= 0.0-3030. Thanks for your patience.

The only dependencies required for this tutorial is an installation of Java 8 and the standalone ClojureScript JAR. ClojureScript itself only requires Java 7 but the standalone JAR comes bundled with useful Nashorn integration that requires Java 8.

Even if you are interested in Leiningen based workflow this Quick Start is essential reading. It covers the fundamentals regardless of what tooling you decide to use.

ClojureScript Compiler

The standalone ClojureScript JAR comes bundled with Clojure 1.6.0. This supports simple scripting of the ClojureScript compiler and the bundled REPLs without an overly complicated command line interface. Thanks to Nashorn and existing Clojure interop support the ClojureScript compiler can even be scripted with JavaScript!

Using ClojureScript on a Web Page

The following example shows the basic steps involved in creating a ClojureScript application and running it from a web page. The example assumes that you are working in the ClojureScript root directory.

First, write some ClojureScript code. In the example below, a function is created which will be called from JavaScript in a web page. The :export metadata ensures that this function name is not minified. The JavaScript function will be available as hello.greet.

(ns hello)
(defn ^:export greet [n]
  (str "Hello " n))

Save this code into a file named hello.cljs and then compile it to JavaScript.

From the command-line:

$ ./bin/cljsc hello.cljs '{:optimizations :advanced}' > hello.js

Or from the REPL:

(cljsc/build "hello.cljs" {:optimizations :advanced :output-to "hello.js"})

Finally, host this JavaScript in a HTML page and call the hello.greet function.

<html>
  <head></head>
  <body>
    <script type="text/javascript" src="hello.js"></script>
    <script>
      alert(hello.greet("ClojureScript"));
    </script>
  </body>
</html>

Running ClojureScript on Node.js

To run ClojureScript on Node.js, set the var *main-cli-fn* to the function you want to use as an entrypoint. For instructions on installing Node.js, see the Node.js wiki. Only the current stable versions of Node.js (0.10.X) are supported at this time. The example below shows how a functional programmer might print "Hello World".

(ns nodehello
  (:require [cljs.nodejs :as nodejs]))

(defn -main [& args]
  (println (apply str (map [\ "world" "hello"] [2 0 1]))))

(nodejs/enable-util-print!)
(set! *main-cli-fn* -main)

Save this to a file named nodehello.cljs and then run the following commands to compile and run.

$ ./bin/cljsc nodehello.cljs '{:optimizations :advanced :target :nodejs}' > nodehello.js
$ node nodehello.js

Note on some platforms (such as ubuntu) the node command may be named nodejs. Another example is available in samples/nodels.cljs, but it currently only works with simple optimizations:

$ ./bin/cljsc samples/nodels.cljs '{:target :nodejs}' > nodels.js
$ node nodels.js src samples

The REPL equivalent of the above two compilation commands are shown below.

(cljsc/build "nodehello.cljs" {:optimizations :advanced :target :nodejs :output-to "nodehello.js"})
(cljsc/build "samples/nodels.cljs" {:target :nodejs :output-to "nodels.js"})

Notes on optimization settings

Prior to this commit, Node.js only worked under :advanced or :simple optimizations. ClojureScript will now emit the Node.js bootstrap script provided by Google Closure Library which implements Node.js compatible versions of goog.require and goog.provide. Under :none and :whitespace the following shell interaction will work:

node
> require("./[:output-dir]/goog/bootstrap/nodejs")
> require("./[:output-to]")
> require("./[:output-dir]/path/to/main/namespace")

Note using advanced compilation on Node.js targets is unnecessary. If for some reason it is desirable you must supply externs for the Node.js APIs.

More about Compiling

Note: This section assumes that you have set the CLOJURESCRIPT_HOME environment variable and have cljsc on your path. All examples show how to compile the project in samples/hello.

The cljsc tool, and the underlying build function, supports three levels of optimization and a development mode where no optimization is performed and each input JavaScript file is kept separate. This section will give a quick overview of how to use each mode.

Development Mode

While developing a new application, leave out the :optimizations option. This will compile all JavaScript into the working directory, which defaults to out and write a "dependencies" file to hello.js.

$ cljsc src '{:main hello}' > hello.js

From the REPL use:

(cljsc/build "samples/hello/src" {:main hello :output-dir "samples/hello/out" :output-to "samples/hello/hello.js"})

To host this application in a web page pull in hello.js.

<script type="text/javascript" src="hello.js"></script>

Production Mode

When ready to deploy, compile the file with advanced optimizations.

$ cljsc src '{:optimizations :advanced}' > hello.js

In this situation, only one script tag is required which will pull in the hello.js file:

<script type="text/javascript" src="hello.js"></script>

The other types of optimizations: :whitespace and :simple each produce less optimized but more readable code. There is also a :pretty-print option.

$ cljsc src '{:optimizations :simple :pretty-print true}' > hello.js

The command above has the same effect as the one below. :output-dir, the location where compiled JavaScript files are stored, defaults to out. When :output-to is not set, compiled output is printed to standard out.

$ cljsc src '{:optimizations :simple :pretty-print true :output-dir "out" :output-to "hello.js"}'

All of the options shown above may also be used when compiling from the REPL with the build function. For a full list of compiler options, see Compiler Options.

Add a custom footer

Home

Intro

Reference

Tooling

Leiningen plugins

Editors

Additional Information

Clone this wiki locally