[macOS] Config file watcher causes infinite reload loop due to spurious fs.watch events

[schalkneethling]

Description

On macOS, the config file watcher triggers continuous reloads (~every 5 seconds) even when the .miyagi.js file has not been modified. This is caused by macOS system processes (Spotlight indexing, Time Machine, etc.) triggering fs.watch events.

Environment

• OS: macOS
• Miyagi: 4.0.1
• Node.js: 20+

Steps to Reproduce

1. Create a Miyagi project on macOS
2. Run miyagi start
3. Wait 15-20 seconds without making any changes
4. Observe terminal output

Observed Behavior

2026/01/04 13:56:17 Info: Updating configuration…
2026/01/04 13:56:18 Success: Reloading browser window!
2026/01/04 13:56:18 Success: Updating done!

2026/01/04 13:56:22 Info: Updating configuration…
2026/01/04 13:56:22 Success: Reloading browser window!
2026/01/04 13:56:22 Success: Updating done!

This repeats indefinitely at ~5 second intervals.

Expected Behavior

No config reloads should occur unless the user actually modifies .miyagi.js.

Root Cause Analysis

The config file watcher in lib/init/watcher.js (lines 335-341) uses Node's fs.watch:

if (global.config.userFileName) {
  fs.watch(global.config.userFileName, async (eventType) => {
    if (eventType === "change") {
      configurationFileUpdated();
    }
  });
}

Issues identified:

1. No debouncing: Unlike the regular file watcher (which uses a timeout), the config watcher processes every event immediately
2. macOS FSEvents quirks: fs.watch on macOS receives spurious "change" events from system processes (Spotlight, Time Machine, mds, etc.) that access/index files
3. No way to disable: There is no config option to turn off config file watching

Proposed Solution

Add a ui.watchConfigFile option (default: false to avoid this issue):

1. In lib/default-config.js:

ui: {
  // ... existing options
  watchConfigFile: false,  // Disable by default due to macOS issues
}

2. In lib/init/watcher.js:

if (global.config.userFileName && global.config.ui.watchConfigFile) {
  fs.watch(global.config.userFileName, async (eventType) => {
    if (eventType === "change") {
      configurationFileUpdated();
    }
  });
}

Workaround

Users can patch locally using patch-package with the changes above.

Additional Context

• This issue does NOT affect Linux (inotify is more reliable than FSEvents)
• The spurious events occur regardless of whether the user is actively using the system
• Tested with fresh projects—the issue persists

[schalkneethling]

Update: Root Cause Identified

After tracing with fs_usage, we identified the exact process triggering the spurious events:

sudo fs_usage -w -f filesys | grep "\.miyagi\.js"

Output:

14:19:57.867836  lstat64    apps/component-library/.miyagi.js   0.000002   git.8931223
14:19:57.867858  lstat64    apps/component-library/.miyagi.js   0.000002   git.8931222
14:19:57.867875  open       apps/component-library/.miyagi.js   0.000039   git.8931223
14:19:57.867880  open       apps/component-library/.miyagi.js   0.000022   git.8931222
14:19:57.867904  lstat64    apps/component-library/.miyagi.js   0.000001   git.8931224
14:19:57.867919  open       apps/component-library/.miyagi.js   0.000015   git.8931224

The Culprit: IDE Git Integration

The git.XXXXXX process names indicate IDE git integration (VS Code, Cursor, etc.) is the source. Modern IDEs run git status checks every 3-5 seconds to update:

• Modified file indicators in the file tree
• Git status in the status bar
• Source control panel

Each git status check does lstat64 and open calls on tracked files, which triggers fs.watch events on macOS.

Why This Affects macOS Specifically

macOS's FSEvents/fs.watch is more sensitive than Linux's inotify. On Linux, lstat64 (stat calls) typically don't trigger watch events, but on macOS they can.

Conclusion

This is unavoidable in modern development workflows—any user with IDE git integration will hit this issue. The proposed ui.watchConfigFile: false option is the correct fix, as config file watching provides minimal value compared to the disruption it causes.