Stale cached JavaScript output after dependency file change in figwheel-main watcher

Why the watcher does not see dependency file changes

Figwheel‑main’s file‑watcher is built on Java NIO WatchService. It generates a recompilation only when it receives a file‑system event for a path it is actively watching. By default the watcher monitors only the directories listed in :source-paths. Files that live outside those directories (e.g., external dependency source files, JAR‑unpacked libs, or files in a separate lib/ folder) are not watched unless they are explicitly added to :watch-dirs. Because the watcher does not fall back to polling timestamps or content hashes, a change that does not produce a WatchEvent (or occurs in an unwatched directory) leaves the in‑memory cache unchanged, resulting in stale JavaScript output when :optimizations :none is used.

Confirmed facts from the implementation

• The watcher relies exclusively on WatchService events; there is no automatic timestamp‑based polling for dependencies.
• Cache invalidation occurs only after a watched file emits a change event; the :cache-dir setting only controls where intermediate build artifacts are stored and does not affect event detection.
• Adding a directory to :watch-dirs extends the watcher’s scope to that path, causing events from files inside it to trigger recompilation.

Steps to ensure dependency changes trigger recompilation

1. Identify the dependency location: Determine whether the file you are editing is a loose file on the filesystem or resides inside a JAR. Only loose files can be watched.
2. Add the directory to :watch-dirs: In your figwheel‑main build config, include the absolute or relative path to the directory containing the dependency source, e.g.,

   :watch-dirs ["src" "dev-resources" "../shared-lib/src"]

3. Restart the figwheel‑main process so the new watcher registration takes effect.
4. Verify: Modify the dependency file and observe the browser reload (or the console log) showing updated JavaScript. Enable verbose logging (:verbose true) to see which files triggered the recompilation.

When the above does not help

If the dependency file is inside a JAR or located on a filesystem where WatchService is unreliable (e.g., certain NFS mounts, Docker volumes, or Windows shared folders), events may be dropped. In that case consider:

• Unpacking the JAR into a watched directory during development.
• Using a polling‑based wrapper (e.g., chokidar via a custom script) as a temporary workaround.
• Ensuring the host filesystem supports reliable WatchService notifications.

Only if you discover that the dependency files are JAR‑resident or on an unreliable mount would the recommendation change; otherwise adding the directory to :watch-dirs resolves the issue.