The ns form will not work in the ClojureScript REPL (either the Rhino REPL or the browser REPL). To switch the current namespace in the REPL, you can use the in-ns special form, passing it the quoted namespace:

ClojureScript:cljs.user> (in-ns 'foo.bar)

This switches the REPL’s current namespace to be foo.bar.

Note that in-ns is a special tool for REPL development, and doesn’t actually exist in ClojureScript’s standard library. It is implemented as a special case in the REPL’s reader. As such, it won’t work at all in *.cljs source files, or anywhere else except in a REPL session.

Also, because ClojureScript namespaces can be defined only at compile time, using in-ns to switch to a namespace does not implicitly create the namespace (as it does in Clojure). If you specify a namespace that isn’t already loaded, the REPL will switch to it, but almost everything you try to do will fail with a “namespace is not defined” error.

When you compile a directory containing *.cljs files, the compiler emits a directory with the same structure containing compiled *.js files; each input *.cljs file has exactly one output *.js file with the same name and path.

Each emitted *.js file contains code allowing it to participate in the namespace system provided by the Google Closure Library. You can read about the Google Closure Library’s dependency management system here. Note that as a user of ClojureScript, you don’t have to worry about writing a deps.js file, or using the ClojureBuilder or DepsWriter scripts described in the Google Closure documentation. The ClojureScript compiler performs those functions internally. This is the mechanism by which ClojureScript actually resolves namespace dependencies: under the hood, ClojureScript’s namespace dependency system is that of Google Closure.

In the Google Closure Library, dependency management is handled by two functions: goog.provide() and goog.require(). The goog.provide() function is intended to be called once per file, and passes the namespace the file contains. The goog.require() function may be called multiple times, each time with a dependency of the file. Both are emitted directly by ClojureScript when compiling an ns form. The mapping is very straightforward:

(ns application
    (:require [foo.bar :as bar]
              [foo.baz :as baz]))

It is compiled to:

goog.provide("application");
goog.require("foo.bar");
goog.require("foo.baz");

What happens next depends on what :optimizations mode the ClojureScript compiler is running in.

When using :optimizations :none, the ClojureScript compiler will write a list of calls to goog.addDependency() to the specified :output-to file. These serve to create mappings between namespace names, dependencies, and relative paths, and are necessary to inform Google Closure of the location of dependencies (unlike ClojureScript, Google Closure has no convention regarding source file location). After you include this dependencies file in your web page, calls to goog.require() will dynamically add new <script> tags to the page using the provided relative path.

It follows, then, that when using :optimizations :none you must also make the compiler output directory (specified with :output-dir) publicly available on a relative path appropriate to the URL of the page. This is necessary because the page will end up loading each of the needed *.js files directly. You must also manually include goog/base.js first in your HTML, to bootstrap the Google Closure Library, as we showed in Chapter 3.

On the other hand, when using any :optimizations mode other than :none, the compiler will concatenate all the required files into one gigantic JavaScript file, in dependency order, and write it out as the :output-to file. This is the only *.js file you need to include on your HTML page, since it contains a full copy of every dependency, even the core Google Closure library. Therefore, in this case, it isn’t necessary to expose the output directory like it is with :optimizations :none.

Because vanilla JavaScript has no built-in namespace support, it’s standard practice to use objects as a poor man’s namespace system, nesting all the variables a library uses under a single top-level object.

The ClojureScript compiler does exactly the same thing, when compiling ClojureScript symbols to JavaScript variables. Each dot-separated level of the namespace becomes a nested object, with the symbol’s name as the final name. For example, the symbol my.cool.new-project/some-data in ClojureScript will be my.cool.new_project.some_data in JavaScript. (Hyphens in ClojureScript symbols become underscores in JavaScript.)

For pure ClojureScript applications, this is just an implementation detail. However, it does become important when you want to call a ClojureScript function from JavaScript, since you must refer to it by its fully qualified (i.e., nested) name.

These are files that include a call to goog.provide(), allowing them to participate in Google Clojure’s dependency management system, and by extension, ClojureScript’s. A JS file that invokes goog.provide('x.y.z') effectively has the namespace x.y.z.

Unless you work at Google, you aren’t likely to see many libraries that fit into this category, as Google Closure doesn’t have a particularly large uptake in the JavaScript community. However, if you’re using a mixed JavaScript/ClojureScript codebase, and you’d like anyone to have the freedom to modify the library, you can consider making your JavaScript compatible with Google Closure to make it easier to use with ClojureScript.

First, to use them, you must start by putting the *.js files on the classpath so they are accessible to the compiler (just like ClojureScript files).

Second, you must tell the ClojureScript compiler where on the classpath the files are located. Unlike ClojureScript file paths, *.js pathnames don’t necessary have any relationship to the namespaces they provide. To indicate this to the compiler, use the :libs compiler option, which is a vector of *.js pathnames relative to the classpath. The compiler will inspect these files for calls to goog.provide() and handle them appropriately.

For example, to include a library in a file located at jslib/magic.js, the compiler options map might look something like this:

{:output-to "resources/public/js/main.js"
 :optimizations :advanced
 :libs ["jslib/magic.js"]}

Finally, to use these libraries in your ClojureScript code, :require or :use their namespaces in your ns declaration form. This will ensure that the library is available. Then, use ClojureScript’s JS interop to reference the JavaScript vars. Note that the namespace of a Google Closure library doesn’t always match the names of the variables it declares; that’s another ClojureScript convention that is stricter than what Google Closure alone requires.

Because libraries built for Google Clojure should already be compatible with Advanced mode compilation, you shouldn’t need to worry about preserving variable names against munging: Advanced-mode processing will be consistent across the entire codebase, including the required libraries.

This is likely the most common type of library you might wish to use in ClojureScript: a normal, possibly popular JavaScript library that wasn’t written with ClojureScript or Google Closure in mind.

With these libraries, there is just one major choice to make: do you want to attempt to use the Google Closure Compiler’s Advanced Optimizations mode to compile the library together with your code, or include it separately on the HTML page? When you use Advanced mode, the Google Closure Compiler will perform whole-program optimization across both the library and your code. When you leave it separate, your program will still be compiled, but the external library will be loaded and run without any transformations.

As discussed above, compiling in Advanced mode has many benefits in emitted code size and runtime speed. Also, as you will see below, it’s slightly easier to use with ClojureScript. However, the fact is that most JavaScript code written without Advanced mode in mind probably doesn’t meet its rather stringent requirements.

If you do want to compile an existing library in Advanced mode, you should do a careful audit of the library’s code to make sure it meets the restrictions of Advanced mode. Be cautious: this is the one area where it is possible to go badly wrong. Sometimes incompatibilities don’t manifest in an obvious way until they’ve caused you serious trouble.

{:output-to "resources/public/js/main.js"
 :optimizations :advanced
 :foreign-libs [{:file "http://foo.com/foobar.js"
                 :provides ["foo.bar"]}]}

(let [image (js/Raphael. 10 50 320 200)]
    (.circle image 50 50 50))

var Raphael = {};
Raphael.circle = function() {};

{:output-to "resources/public/js/main.js"
 :optimizations :advanced
 :externs ["raphael_externs.js"]}

If you want to compile your libraries with Advanced mode, you’ll need to make one small additional change. JavaScript libraries can reference ClojureScript vars by name, but Advanced mode compilation munges all the var names. If you want to be able to reference a var from external JavaScript, you’ll need to mark it specifically for preservation.

To do this, tag the vars whose names you want to preserve using the :export metadata tag. ClojureScript metadata is data that can be attached to any ClojureScript object, and since it can be inspected by the compiler it can be used to alter the emitted JavaScript. In the case of :export, it indicates that the tagged var should not be munged.

Adding the :export metadata tag to a function using the metadata reader macro looks like this:

(ns foo)

(defn ^:export hello [name]
    (js/alert (str "Hello, " name)))

This code defines a very simple function called hello in the foo namespace, but tags it with :export so that it won’t be munged during advanced compilation. This means that a JavaScript caller can invoke it directly: foo.hello("Luke") would result in an alert box popping up that says “Hello, Luke”.