Code Splitting in ClojureScript with Closure Compiler Modules

Desired Outcome

Produce multiple JavaScript bundles from a single ClojureScript build so that feature-heavy code (admin panels, charting libraries, rarely used dialogs) loads on demand while a shared base module containing cljs.core and common dependencies loads once. This reduces initial payload and improves Time-to-Interactive for large applications.

Prerequisites

• ClojureScript 1.10.773 or newer for cljs.main module support, or shadow-cljs 2.20+ for the ergonomic :modules configuration.
• Familiarity with your build tool (clj -M --main cljs.main or npx shadow-cljs) and the project's namespace graph.
• A list of candidate entry-point namespaces (e.g., app.admin.core, app.charts.dashboard) identified via build reports or manual inspection.

Procedure: cljs.main (Built-in Compiler)

1. Define the Module Graph in build.edn

Create a :modules map where each key is a module ID. The :base module has no :entries (it implicitly contains cljs.core). Feature modules declare :entries (the namespace that triggers the load) and :depends-on #{:base}.

{:main app.core
 :output-dir "out"
 :optimizations :advanced
 :modules
 {:base {}
  :admin {:entries [app.admin.core]
          :depends-on #{:base}}
  :charts {:entries [app.charts.dashboard]
           :depends-on #{:base}}}}

2. Implement Runtime Loading

In the entry namespace (e.g., app.admin.core), call cljs.loader/load with the module keyword and a callback. The compiler emits a manifest.edn mapping namespaces to module IDs.

(ns app.admin.core
  (:require [cljs.loader :as loader]))

(defn init []
  (loader/load :admin
    (fn [] (println "Admin module loaded"))
    (fn [err] (js/console.error "Admin load failed" err))))

3. Build and Verify Output

clj -M --main cljs.main --compile-opts build.edn --compile app.core

Run from the project root. Requires write permission to out/. Expected artifacts: out/base.js, out/admin.js, out/charts.js, and out/manifest.edn.

Procedure: shadow-cljs (Recommended for Complex Splits)

1. Configure shadow-cljs.edn

Use :module-type :esm for native ES modules (browser) or :commonjs for Node/SSR. shadow-cljs automatically resolves the dependency graph; you only declare entry points.

{:builds
 {:app {:target :browser
        :output-dir "public/js"
        :modules
        {:base {}
         :admin {:entries [app.admin.core]}
         :charts {:entries [app.charts.dashboard]}}
        :devtools {:loader-mode :eval}}}}

2. Use Dynamic import() in Code

Shadow-cljs translates (:require ["@module/admin" :as admin]) into a dynamic import() that returns a Promise. No cljs.loader needed.

(ns app.router
  (:require ["@module/admin" :as admin]))

(defn navigate-to-admin []
  (-> (admin/load) ; returns a Promise
      (.then (fn [mod] (mod/init)))
      (.catch (fn [err] (js/console.error "Admin load failed" err)))))

3. Build

npx shadow-cljs release app

Run from project root. Outputs hashed files (e.g., public/js/app.base.abc123.js) and a manifest.edn per module.

Expected Checks

1. Base module purity: grep -r "app.admin\|app.charts" out/base.js should return nothing. Base must only contain cljs.core and shared deps.
2. Module size budget: Each feature module < 200KB gzipped. Check with gzip -c out/admin.js | wc -c.
3. Network tab verification: Open browser DevTools → Network, trigger the lazy route (e.g., click "Admin"). Only the corresponding chunk (admin..js) should fetch with 200 OK.
4. Load callback / Promise resolution: Confirm the success callback fires or the dynamic import Promise resolves. Add a console.log in the callback to verify.

Recovery Options

Runtime Load Failure

• cljs.main: Use the :error callback in cljs.loader/load to log to your monitoring service, render a fallback UI (e.g., "Admin panel unavailable, retry?"), and optionally retry with exponential backoff.
• shadow-cljs: Attach .catch() to the dynamic import Promise. Same fallback strategy applies.

Build-Time Misconfiguration

Circular dependencies or missing entries produce clear compiler errors. As an immediate unblock, revert to a single-module build by removing :modules (or setting :modules :none in shadow-cljs) and rebuild.

Critical Cautions

• Advanced optimizations rename symbols: Annotate entry-point functions with ^:export or provide externs so the module loader can find them after minification.
• Don't mix module systems: cljs.loader expects CommonJS-style goog.module.get; shadow-cljs with :module-type :esm emits ES dynamic import(). Pick one strategy per build.
• Shared dependencies duplicate if not in :base: Large libs (Reagent, Chart.js) must be required by a namespace that ends up in :base (e.g., a app.shared ns listed in :base entries) or they will appear in every feature module. Audit with shadow-cljs build-report or cljs.build.api/print-module-graph.
• Cache busting: shadow-cljs adds content hashes by default. With cljs.main you must implement your own (e.g., :output-dir "out/[hash]" via a wrapper script).
• Node/SSR targets: Require :module-type :commonjs and a CommonJS loader. ES modules in Node need .mjs or "type": "module" in package.json and break cljs.loader.

Automated Regression Guard

Add a CI step that parses shadow-cljs build-report.json (or manifest.edn for cljs.main) and fails if any module exceeds a size budget (e.g., 150KB gzipped). Example using jq:

npx shadow-cljs run shadow.cljs.build-report --json > report.json
MAX=153600  # 150KB
for size in $(jq '.modules[].size' report.json); do
  if [ $size -gt $MAX ]; then
    echo "Module exceeds budget: $size bytes"
    exit 1
  fi
done

Verification Checklist

• Build with :optimizations :none and inspect generated JS: base.js contains goog.provide('cljs.core') but no feature namespaces; feature modules goog.require('cljs.core') and their entry namespace.
• Trigger lazy load in browser, confirm only the relevant chunk loads.
• Simulate network failure (DevTools → Offline) and verify fallback UI appears and retry works.
• Validate source maps: production stack traces should map to original .cljs files for each module (shadow-cljs emits .map per module by default).