Silent runtime failures after switching ClojureScript build to :advanced optimizations mid-migration

Direct answer

You cannot reliably detect missing externs without running :advanced optimizations. The :simple level does not rename or mangle property names — that only happens under :advanced. Keep your dev build at :none for fast hot reloading, and run a separate :advanced build in CI (or locally on demand) to surface externs gaps before release.

Why :simple does not help here

Closure Compiler's :simple mode renames local variables and function parameters but leaves object property names untouched. Externs errors — where a third-party library's React.createElement gets renamed to a.b — only appear when global property renaming is enabled, which is exclusive to :advanced. Switching dev to :simple adds compilation time without catching the failure mode you described.

Practical CI-first configuration

1. Define two builds in shadow-cljs.edn:

   {:builds
     {:dev    {:target :browser
               :optimizations :none
               :output-dir "public/js/dev"
               :modules {:main {:init-fn my.app/init}}
               :devtools {:after-load my.hooks/on-reload}}
      :ci     {:target :browser
               :optimizations :advanced
               :output-dir "public/js/ci"
               :modules {:main {:init-fn my.app/init}}
               :compiler-options {:infer-externs true
                                  :externs ["externs/custom.js"]}}}}

2. Local dev: shadow-cljs watch dev — fast, hot-reloading, no externs checking.
3. CI step: shadow-cljs compile ci (or release ci for full output). Fail the build on any Closure Compiler warning. shadow-cljs exits non-zero on errors; warnings appear in stdout/stderr.
4. Externs strategy:
   • Enable :infer-externs true (shadow-cljs 2.16+) — it reads ^js type hints and js/ property access to generate externs automatically.
   • For npm dependencies consumed via :npm-module or shadow.cljs.devtools.api/npm-install, add :js-provider :import and rely on inference.
   • For globals or libraries without type hints, write a small externs/custom.js file declaring the exact property names you call (e.g., var React = {createElement: function() {}};).
   • CLJSJS packages ship externs automatically; if you use them, no extra work is needed.

Preserving atom state across hot reloads

Move long-lived atoms into a namespace that shadow-cljs never reloads (e.g., my.app.state). Require that namespace from components instead of defining atoms inline. This is the simplest and most reliable method.

If you must keep atoms in reloaded namespaces, use the :devtools {:after-load ...} hook (not a top-level :hooks key). The hook receives the changed namespaces; you can re-attach prior values:

;; my.hooks
(ns my.hooks
  (:require [my.app.ui :as ui]))

(def ^{:private true} saved-state (atom nil))

defn capture-state []
  (reset! saved-state @ui/app-state))

defn restore-state []
  (when-let [prev @saved-state]
    (reset! ui/app-state prev)))

In shadow-cljs.edn dev build add :devtools {:before-load my.hooks/capture-state :after-load my.hooks/restore-state}. Note: this only preserves values across reloads in the same browser session; a full page reload resets everything. Test a cold :advanced build locally before cutover to ensure initialization works without the hook.

Verification you can run today

• shadow-cljs compile dev — confirms dev build works.
• shadow-cljs compile ci 2>&1 — runs :advanced compilation; review output for WARNING lines mentioning "property" or "externs".
• Open dev build, trigger a hot reload, verify atom-backed UI state persists.
• Run shadow-cljs release ci locally once before merging to simulate the exact production artifact.

Assumptions and uncertainty

• Assumes shadow-cljs ≥ 2.20 (current stable as of 2026-10-14) where :infer-externs and :devtools hooks are stable.
• Assumes third-party libraries are consumed via npm or CLJSJS; foreign-libs with :global-exports may need manual externs.
• Generated externs via inference cover dotted property access (js/React.createElement) but may miss string-based access (aget obj "createElement") — use cljs-oops or manual externs for those cases.
• State-preservation hooks add complexity and can mask cold-load bugs; treat them as a migration aid, not a production pattern.

One missing detail that would change the recommendation

Are your third-party libraries installed via npm (ES modules/CommonJS) or provided as CLJSJS/foreign-libs globals? If npm, :infer-externs true with :js-provider :import handles most cases automatically. If globals, you will likely need to write manual externs for each library's public API surface.