ClojureScript ↔ JavaScript interop boundary for incremental migration without downtime

The short answer

Publish a deliberately thin, versioned JavaScript facade from a single ClojureScript namespace, mark every function in it with ^:export, and keep the rest of the interop boundary internal. Externs are needed only for names the Closure Compiler must not rename that your own exports do not already cover — typically third-party globals or properties you read off JavaScript objects. Do not treat defonce as an export mechanism: it controls redefinition semantics during hot reload, not name preservation in :advanced output.

Confirmed behavior vs. what depends on your setup

Well established: under :advanced optimizations, Closure renames local names and property accesses it believes are private. ^:export metadata (or goog.exportSymbol / goog.exportProperty) emits code that pins the name. Externs files tell the compiler a name is defined elsewhere and must be left alone. These are long-standing behaviors rather than version-specific quirks.

What varies by toolchain: the exact flag names for externs validation, whether the tool emits an export manifest, and how npm packages resolve. shadow-cljs and the official cljs.main CLI differ here, and flags move between releases. Verify against the documentation for the versions you pin.

A contract that survives incremental releases

1. One namespace, for example myapp.api, is the only thing JavaScript may call. Everything else is private by convention.
2. Each exported function is small, takes and returns plain JavaScript values (convert at the edge with clj->js / js->clj), and exposes no ClojureScript-specific types in its signature.
3. Export a version string plus a mount(node, props) / unmount(node) pair. Mounting into an isolated DOM node is what makes per-route migration possible.
4. Keep a checked-in externs file listing every exported symbol, including nested properties, and update it in the same commit as the API change.
5. Emit an export manifest per build and diff it in CI. A removed or renamed symbol should fail the build, not the browser.

Externs vs. exports: which do you need?

Internal boundary or published surface?

For incremental migration without downtime, a thin published surface is usually the better trade. If the boundary stays internal, every change to a component signature forces a rebuild and redeploy of the JavaScript callers, re-coupling the two codebases and undermining the point of migrating incrementally. A small facade with a version string lets old JavaScript keep calling the old shape while new ClojureScript loads alongside.

The cost is discipline: a public surface must be versioned, documented, and deprecated deliberately. If your JavaScript callers live in the same compilation unit as the ClojureScript — one Closure build — externs are largely unnecessary and ^:export alone suffices. That distinction is the single detail that most changes the recommendation.

Deployment reality check

Feature flags and cache busting are what actually deliver zero downtime. A flag that hides a new component does not help if a browser has cached JavaScript that calls a renamed export. Use content-hashed, immutable asset URLs and keep the previous bundle reachable during the rollout window.

Verification

• Build with advanced optimizations and confirm exported names appear verbatim in the output:

  grep -o 'myapp\.api\.[A-Za-z0-9_]*' out/main.js | sort -u

• Run a harness where plain JavaScript imports the facade and calls each function, against every release candidate.
• Enable externs validation in your build and treat warnings as errors.

Flag for review: exact flag names and manifest support differ between shadow-cljs and the official CLI and shift across versions. Confirm against the docs for your pinned versions before wiring CI.