ClojureScript Build Tooling and JavaScript Dependency Management: Ensuring Repeatable Development Environments

The short answer

Delegating JavaScript dependency resolution to Yarn or npm with a committed lockfile yields more deterministic builds than the built-in :npm-deps foreign-lib mechanism, assuming :optimizations and :source-map stay fixed. The lockfile pins every direct and transitive version once; :npm-deps re-resolves through the Closure compiler at each build and has no lockfile of its own, so transitive versions can drift between machines and over time.

Why the two approaches differ

With :npm-deps, the ClojureScript compiler asks the Closure compiler to resolve npm packages during compilation. Unless you pin every version explicitly in the map, resolution can float, and different developer machines can end up feeding different JavaScript into the same build. That changes generated asset bytes and shifts source-map line numbers, even though your ClojureScript source is identical.

With Yarn or npm, yarn.lock or package-lock.json fixes the entire dependency tree. The node_modules directory becomes effectively immutable between lockfile changes, so the compiler sees byte-identical inputs on every machine. This is the likely explanation for most "works on my machine" build-hash mismatches; the confirmed fact is simply that a lockfile constrains resolution and :npm-deps does not.

Effect on watch modes and hot reload

• shadow-cljs integrates directly with npm/yarn. Its watch mode rebuilds only when actual source or JS files change, so hot reload stays stable and release builds are reproducible as long as the lockfile is unchanged.
• Figwheel Main with :npm-deps works without Node tooling, which is convenient, but you must pin exact versions manually. It can be deterministic in practice, yet nothing prevents a teammate from adding an unpinned dep that resolves differently on their machine.

Both systems invalidate caches by content hash, so predictable inputs mean predictable cache behavior. The external-tool approach makes those inputs predictable by construction.

Caveats

• Commit the lockfile. An uncommitted lockfile is the most common way this strategy silently fails.
• Keep Node.js and package-manager versions consistent across machines; different installer versions can produce slightly different node_modules layouts even from the same lockfile.
• Foreign libs that bundle their own dependencies are not captured by the npm/yarn lockfile — verify those bundled copies are version-locked separately.

Verifying you have no hidden variability

1. On two machines at the same Git commit, run a clean build (rm -rf target public/js or your output dirs) and compare SHA-256 hashes of the compiled JS and source maps. They should match.
2. Run shadow-cljs release :advanced twice with no changes and diff the artifacts; expect byte-for-byte identity.
3. Compare dependency trees across machines with npm ls --json or yarn list --json.
4. In a Figwheel watch session, edit a file, revert it, and confirm the output hash returns to its original value.
5. Bump one JS dependency, commit the updated lockfile, and confirm only the expected output hash changes.

One caveat on scope: exact behaviors depend on your compiler and build-tool versions, so treat the verification steps above as the real test for your setup rather than any general claim. If your team cannot standardize on Node tooling at all, pinned :npm-deps is the fallback — but enforce the pins in code review, because nothing else will.