Biome 1.0.0 File‑Watcher Limitation on Windows: Selecting a Compatible Watcher

Answer to the Core Question

Biome 1.0.0 implements file watching through the Rust notify crate, which on Windows uses ReadDirectoryChangesW. That API is known to be unreliable on network shares, SMBv1, or other legacy file systems, resulting in silent failures of the --watch flag. The current CLI does not expose a dedicated flag to switch to a polling‑based watcher, nor does it provide an alternative watcher library that can be selected via configuration.

Because of this limitation, the most reliable way to get continuous linting on Windows is to run Biome from a local disk that supports ReadDirectoryChangesW (e.g., NTFS). If the code resides on a network drive, the only practical workaround—without writing external scripts—is to rely on Biome’s own fallback to polling, which is enabled automatically when the native watcher fails. However, the fallback is not always guaranteed and may be disabled in some builds.

What to Do If You Must Watch Network Drives

• Run Biome from a local clone of the repository and copy changes to the network share via a build step (e.g., rsync or a simple copy script).
• Use a third‑party watcher such as entr or watchexec to trigger biome lint --watch whenever a file changes. While this introduces an external tool, it keeps the linting command itself unchanged.
• Check the Biome issue tracker for any upcoming releases that expose a --watcher-polling flag; if such a flag appears, you can enable it with biome lint --watch --watcher-polling.

Verifying That Watch Is Working

1. Open a terminal and run:

   biome lint --watch
   

2. Make a small change to any source file and press Enter.
3. Biome should immediately re‑run linting and print the results. If nothing happens, try adding the --verbose flag to see any hidden errors.
4. On a network drive, if the linting still does not trigger, you can test the fallback by editing the file from another machine or by reducing the network latency (if possible). If the fallback is not active, you will need to use a third‑party watcher.

Missing Diagnostic Detail

To refine the recommendation, could you confirm whether your source files are stored on a local NTFS drive or on a network share (SMB, CIFS, etc.)? The choice of solution depends heavily on that detail.

Conclusion

At present, Biome 1.0.0 does not provide a built‑in, configurable alternative to the default Windows watcher beyond the implicit polling fallback. The most reliable path on Windows is to run Biome from a local disk. If you must watch a network drive, consider either a local clone approach or a lightweight external watcher that triggers the Biome command. Keep an eye on the Biome release notes for a future --watcher-polling option that could simplify this workflow.