Code Splitting

NOTE: This guide requires ClojureScript 1.9.854 or later.

As client applications become larger it becomes desirable to load only the code actually required to run a particular logical screen. Previously ClojureScript :modules compiler option permitted such code splitting, but this feature only worked under :advanced compilation and users would still have to manage loading these splits. :modules also required manual explicit placement of many entries to produce optimal splits otherwise dependencies would get moved to :cljs-base.

All of these issues are now addressed directly in ClojureScript. This guide will walk you through code splitting a simple project and demonstrate these new enhancements.

Make a Simple Project

Create a project folder:

mkdir -p hello-modules
cd hello-modules
mkdir src

Copy the cljs.jar into this directory.

Create a REPL script:

touch repl.clj

Edit this script to look like the following:

(require '[cljs.repl :as r])
(require '[ :as b])
(require '[cljs.repl.browser :as rb])

(def opts
  {:watch "src"
   :output-dir "out"
   :asset-path "/out"
   :optimizations :none
   :modules {:foo {:entries '#{foo.core}
                   :output-to "out/foo.js"}
             :bar {:entries '#{bar.core}
                   :output-to "out/bar.js"}}
   :browser-repl true
   :verbose true})

(b/build "src" opts)
(r/repl* (rb/repl-env) opts)

Now make an index.html file:

         <button id="button">Load Bar!</button>
         <script src="out/cljs_base.js" type="text/javascript"></script>
         <script src="out/foo.js" type="text/javascript"></script>

The Sources

Create the foo.core namespace:

mkdir -p src/foo
touch src/foo/core.cljs

Edit this file to look like the following:

(ns foo.core
  (:require [goog.dom :as gdom]
            [ :as events]
            [cljs.loader :as loader])
  (:import [ EventType]))


(println "I'm foo!")

(events/listen (gdom/getElement "button") EventType.CLICK
  (fn [e]
    (loader/load :bar
      (fn []
        ((resolve 'bar.core/woz))))))

(loader/set-loaded! :foo)

Notice the unfamiliar namespace cljs.loader. This namespace provides a Google Closure ModuleManager singleton to manage the loading of code splits. This manager will be initialized with whatever module graph you have defined in :modules.

When the user clicks the button we load the :bar module and invoke a function that exists in the bar.core namespace. Notice that we use resolve. This is because we cannot directly call something we never required. If we tried to do this without resolve the ClojureScript compiler would emit an undeclared var warning during compilation.

Finally, note that it is necessary to manually mark a module as loaded via cljs.loader/set-loaded!. Without this dependencies may be loaded multiple times which may lead to unpredictable behavior.

Create the bar.core namespace:

mkdir -p src/bar
touch src/bar/core.cljs
(ns bar.core
  (:require [cljs.loader :as loader]))


(println "I'm bar!")

(defn woz []
  (println "WOZ!"))

(loader/set-loaded! :bar)

Build the Project

Run the REPL script:

rlwrap java -cp cljs.jar:src clojure.main repl.clj

You will be prompted to connect via browser. Navigate to http://localhost:9000/index.html.

Click the button. You will see that the :bar module gets loaded and the function in the other namespace gets invoked.

Release Builds

Make a new script release.clj:

touch release.clj

Make it look like the following:

(require '[ :as b])

(b/build "src"
  {:output-dir "out"
   :asset-path "/out"
   :optimizations :advanced
   :verbose true
   :modules {:foo {:entries '#{foo.core}
                   :output-to "out/foo.js"}
             :bar {:entries '#{bar.core}
                   :output-to "out/bar.js"}}})

(System/exit 0)

Build your project:

java -cp cljs.jar:src clojure.main release.clj

Start a browser REPL just for serving content from current directory:

java -jar cljs.jar -m cljs.repl.browser

Navigate to http://localhost:9000/index.html. Your application should function correctly even though advanced compiled.

Change the foo.core to take a new require like cljs.reader. Rebuild.

You should see that cljs.reader gets moved into the :foo module but not :bar.

If you examine the split files in out you will see that foo.js is larger than bar.js.

Additional Notes

Because the code in splits is running in JavaScript’s global scope, sometimes it may interfere with other JavaScript loaded on the same page, which may result in unpredictable behaviour. To make sure this will not happen, it’s recommended to prefix all variables in generated JavaScript by specifiyng :rename-prefix compiler option. While the output size for each split may increase significantly due to longer variable names, this cost is usually removed by gzipping the assets.

Original author: David Nolen