June 15, 2015

GSoC: Week 3 - Adding CommonJS support

I have been accepted to this years Google's Summer of Code to work on ClojureScript. The goal of my project is to improve the integration of ClojureScript with the existing JavaScript ecosystem. I will post weekly updates about the progress of the project here. For more details about the project have a look at the ClojureScript GitHub wiki page.

Last week, David merged the first patch for CommonJS support into the ClojureScript compiler. This is a good first step. Following, I will describe how you can try out the changes and include a CommonJS module into a ClojureScript project.

Build ClojureScript

For this to work, we need to compile our own ClojureScript compiler as the most recent version 0.0-3308 doesn't include the changes yet. So go ahead and clone the ClojureScript repository:

$ git clone git@github.com:clojure/clojurescript.git

Now we need to build a version of the ClojureScript compiler. I will describe two ways to do this. Which way you choose depends on your ClojureScript project setup.

Without a build tool

For a simple setup follow the ClojureScript Quick Start tutorial, but instead of downloading an existing stand-alone ClojureScript JAR, we will build our own. Change to your ClojureScript directory that you just cloned and build the JAR using an existing script:

$ ./script/uberjar

This will create a stand-alone jar in the target directory under the name cljs.jar. Now go to your project directory and copy the JAR:

$ cp CLJS_PATH/target/cljs.jar .

Assuming you followed the ClojureScript Quick Start tutorial and your build script is located under build.clj you can build your project with:

$ java -cp cljs.jar:src clojure.main build.clj
With a build tool

If you are using a build tool, you need to install a new version of ClojureScript into your local maven repository. For this, change to the ClojureScript repository you just cloned and execute the following script:

$ ./script/build

This should install a new version of ClojureScript. To get the version, check the output of the script, e.g. it should say something similar to this:

[INFO] Installing /Users/marianeise/Documents/development/clojurescript/target/clojurescript-0.0-3332.jar to /Users/marianeise/.m2/repository/org/clojure/clojurescript/0.0-3332/clojurescript-0.0-3332.jar

In this case, the version you would need to use is 0.0-3332.

Compiler Options

To support JavaScript modules we added the compiler option :module-type for foreign libraries, which later on should support the values :commonjs, :amd and :es6. For now, only :commonjs is supported. You can include a CommonJS module as follows:

:foreign-libs [{:file "libs/greeting.js"
                :provides ["greeting"]
                :module-type :commonjs}]

If your CommonJS module depends on other modules, you also need to add them, e.g.:

:foreign-libs [{:file "libs/greeting.js"
                :provides ["greeting"]
                :module-type :commonjs}
               {:file "libs/german.js"
                :provides ["german"]
                :module-type :commonjs}]

Known issues

This feature is still "work in progress". You can read about known issues here:

Tags: cljs js modules commonjs gsoc