Which caches must be cleared to recover a ClojureScript build after a failed toolchain upgrade?

Answer

For a shadow-cljs project, two directories are strictly required to clear:

• The analysis cache: .shadow-cljs/cache
• The configured output directory (the value of :output-dir in your build config, e.g. public/js or target/public/js)

For a plain cljsbuild/Leiningen project, you must delete:

• The output directory (typically target/cljsbuild or resources/public/js)
• Any REPL cache directories, such as .cljs_node_repl or .cljs_browser_repl

The tools.deps classpath cache (.cpcache) and the local Maven repository (~/.m2/repository) are safe to preserve. They only affect dependency resolution, not the compiler's incremental state, so keeping them avoids a lengthy re-download.

Why these two layers matter

Shadow-cljs stores incremental analysis, foreign-lib metadata, and build state inside .shadow-cljs/cache. If an upgrade is interrupted mid-build, that directory can hold a mix of artifacts written by the old and new compiler versions. The cache format is not guaranteed to be compatible across ClojureScript versions, so a partial clean that leaves it behind risks the next build reusing stale analysis and producing silently incorrect output. This is the main corruption vector, and it is exactly the failure mode your fresh-clone comparison is designed to catch.

The :output-dir holds compiled JavaScript and source maps. Shadow-cljs does not auto-purge it on version change, so it must be removed before restarting the build. Stale source maps left there do not corrupt subsequent compilation, but they can mislead debuggers; clearing the directory removes the ambiguity entirely.

In a cljsbuild workflow the same logic applies, but there is no single clean command: the compiler's incremental state lives in the output directory and ad-hoc REPL caches, so script their removal explicitly.

Recovery steps

# shadow-cljs
shadow-cljs clean            # removes .shadow-cljs/cache and :output-dir
# or manually:
rm -rf .shadow-cljs/cache
rm -rf public/js             # your :output-dir
shadow-cljs compile app

# plain cljsbuild
rm -rf target/cljsbuild
rm -rf .cljs_node_repl .cljs_browser_repl
lein cljsbuild once          # or: clojure -M:cljsbuild once

Verification

Confirm .shadow-cljs/cache is actually gone after cleaning; its presence indicates an incomplete cleanup. Then clone the repo fresh into a temp directory, run the same compile command, and compare bundle hashes (e.g. sha256sum public/js/main.js). Finally, open the app in browser devtools and confirm source maps resolve to the correct original sources. For CI, run shadow-cljs clean before the compile step whenever the toolchain version changes.

One caveat: if you ever suspect a corrupted JAR (checksum errors, broken downloads), then clearing ~/.m2/repository becomes warranted — but that is a dependency problem, not an upgrade-recovery requirement.