metro-file-map: Remove FallbackWatcher's 1s startup delay on Windows by robhogan · Pull Request #2106 · react/metro

robhogan · 2026-10-25T15:22:28Z

On Windows, FallbackWatcher waits a second after setting up its watches:

metro/packages/metro-file-map/src/watchers/FallbackWatcher.js

Lines 77 to 82 in 56efab3

    
           if (platform === 'win32') { 
        
             // Inherited from sane: win32 needs a settling period after the watches 
        
             // are registered before events can be relied on. 
        
             await new Promise(resolve => setTimeout(resolve, 1000)); 
        
           }

That's a holdover from sane. libuv issues ReadDirectoryChangesW before uv_fs_event_start returns, so a watch is live as soon as fs.watch returns (here in libuv 1.49.2, which Node 22.13 ships):

https://github.com/libuv/libuv/blob/e1095c7a4373ce00cd8874d8e820de5afb25776e/src/win/fs-event.c#L298-L320

Benchmark

Unsurprisingly, this takes ~exactly one second off watch-mode startup on Windows (1,941ms -> 935ms), and is a no-op elsewhere.

	`main`	#2105	This PR	vs `main`	vs #2105
Linux: Watch-mode start, warm cache	1,887ms	975ms	969ms	-48.7% (-49.2% to -47.9%)	-0.7% (-1.4% to +1.2%)
Windows: Watch-mode start, warm cache	2,577ms	1,941ms	935ms	-63.7% (-63.9% to -63.6%)	-51.8% (-52.0% to -51.7%)
Linux: Watch-mode start, cold cache	1,885ms	921ms	931ms	-50.6% (-51.1% to -49.8%)	+1.1% (-0.2% to +2.6%)
Windows: Watch-mode start, cold cache	2,562ms	1,918ms	917ms	-64.2% (-64.4% to -64.0%)	-52.2% (-52.5% to -52.1%)

Changelog

 - **[Performance]**: metro-file-map: Remove a 1s delay from file watcher startup on Windows without Watchman

Test plan

New unit test that changes made as soon as startWatching resolves are reported. It runs on Linux and Windows, and is skipped on macOS, where fs.watch starts FSEvents asynchronously (but FallbackWatcher isn't used). Benchmark as in #2104.

Without Watchman, `Watcher` starts its backends before the crawl, so that nothing changed during the crawl is missed: https://github.com/react/metro/blob/56efab302200568c919ac1b3c28dacf8d84fc692/packages/metro-file-map/src/Watcher.js#L118-L127 For `FallbackWatcher` that means walking the tree once to watch it and again to crawl it. This lets the crawl do both: the crawler hands each directory to the watcher just before listing it, the order the watcher's own walk uses. Directories the crawl skips as ignored (eg `node_modules` without `retainAllFiles`) are handed over too, for the watcher to walk unless it ignores them as well. This is internal to the built-in node crawler. A `crawlerFactory` crawler, a recrawl, a root added with `addRoot` and the node crawl after a failed Watchman crawl keep the watcher's own walk. ## Benchmark This takes another 27-30% off watch-mode startup on Linux and Windows. With the rest of this stack, watch-mode startup without Watchman goes from 1,933ms to 505ms (-74%) on Linux, and from 2,584ms to 547ms (-79%) on Windows. RSS after startup is 6MB (4%) higher on Linux, though the heap is unchanged. On macOS, which uses `NativeWatcher`, PRs 2-5 stay within 6% of #2104, which is noise: #2106 changes nothing there and measures +5.6%. | | `main` | #2107 | This PR | vs `main` | vs #2107 | |---|---|---|---|---|---| | Linux: Watch-mode start, warm cache | 1,933ms | 716ms | 505ms | -73.9% (-74.0% to -73.6%) | -29.5% (-29.8% to -28.8%) | | Windows: Watch-mode start, warm cache | 2,584ms | 745ms | 547ms | -78.8% (-78.9% to -78.7%) | -26.6% (-26.9% to -26.3%) | | Linux: Watch-mode start, cold cache | 1,923ms | 706ms | 503ms | -73.8% (-74.0% to -73.4%) | -28.7% (-29.2% to -27.6%) | | Windows: Watch-mode start, cold cache | 2,569ms | 733ms | 532ms | -79.3% (-79.4% to -79.2%) | -27.4% (-27.7% to -27.0%) | | Linux: Heap after a watch-mode start | 31.7MB | 28.1MB | 28.1MB | -11.2% (-11.2% to -11.2%) | -0.1% (-0.1% to -0.1%) | | Windows: Heap after a watch-mode start | 31.7MB | 28.2MB | 28.2MB | -11.2% (-11.2% to -11.2%) | -0.0% (-0.0% to -0.0%) | | Linux: RSS after a watch-mode start | 188.0MB | 160.9MB | 166.7MB | -11.3% (-11.7% to -10.5%) | +3.6% (+3.2% to +3.9%) | | Windows: RSS after a watch-mode start | 209.5MB | 185.4MB | 183.8MB | -12.2% (-12.7% to -10.7%) | -0.8% (-1.0% to -0.6%) | ## Changelog ``` - **[Performance]**: metro-file-map: Set up file watching during the crawl instead of in a separate walk before it, on Linux and Windows without Watchman ``` ## Test plan New unit tests, and a `watch-integration-test.js` case for a directory the crawl skips but the watcher doesn't. Benchmark as in #2104.

On Windows, `FallbackWatcher` waits a second after setting up its watches: https://github.com/react/metro/blob/56efab302200568c919ac1b3c28dacf8d84fc692/packages/metro-file-map/src/watchers/FallbackWatcher.js#L77-L82 That's a holdover from `sane`. libuv issues `ReadDirectoryChangesW` before `uv_fs_event_start` returns, so a watch is live as soon as `fs.watch` returns (here in libuv 1.49.2, which Node 22.13 ships): https://github.com/libuv/libuv/blob/e1095c7a4373ce00cd8874d8e820de5afb25776e/src/win/fs-event.c#L298-L320 ## Benchmark Unsurprisingly, this takes ~exactly one second off watch-mode startup on Windows (1,941ms -> 935ms), and is a no-op elsewhere. | | `main` | #2105 | This PR | vs `main` | vs #2105 | |---|---|---|---|---|---| | Linux: Watch-mode start, warm cache | 1,887ms | 975ms | 969ms | -48.7% (-49.2% to -47.9%) | -0.7% (-1.4% to +1.2%) | | Windows: Watch-mode start, warm cache | 2,577ms | 1,941ms | 935ms | -63.7% (-63.9% to -63.6%) | -51.8% (-52.0% to -51.7%) | | Linux: Watch-mode start, cold cache | 1,885ms | 921ms | 931ms | -50.6% (-51.1% to -49.8%) | +1.1% (-0.2% to +2.6%) | | Windows: Watch-mode start, cold cache | 2,562ms | 1,918ms | 917ms | -64.2% (-64.4% to -64.0%) | -52.2% (-52.5% to -52.1%) | ## Changelog ``` - **[Performance]**: metro-file-map: Remove a 1s delay from file watcher startup on Windows without Watchman ``` ## Test plan New unit test that changes made as soon as `startWatching` resolves are reported. It runs on Linux and Windows, and is skipped on macOS, where `fs.watch` starts FSEvents asynchronously (but `FallbackWatcher` isn't used). Benchmark as in #2104.

Without Watchman, `Watcher` starts its backends before the crawl, so that nothing changed during the crawl is missed: https://github.com/react/metro/blob/56efab302200568c919ac1b3c28dacf8d84fc692/packages/metro-file-map/src/Watcher.js#L118-L127 For `FallbackWatcher` that means walking the tree once to watch it and again to crawl it. This lets the crawl do both: the crawler hands each directory to the watcher just before listing it, the order the watcher's own walk uses. Directories the crawl skips as ignored (eg `node_modules` without `retainAllFiles`) are handed over too, for the watcher to walk unless it ignores them as well. This is internal to the built-in node crawler. A `crawlerFactory` crawler, a recrawl, a root added with `addRoot` and the node crawl after a failed Watchman crawl keep the watcher's own walk. ## Benchmark This takes another 28-30% off watch-mode startup on Linux and Windows. With the rest of this stack, watch-mode startup without Watchman goes from 1,887ms to 492ms (-74%) on Linux, and from 2,577ms to 525ms (-80%) on Windows. On macOS, which uses `NativeWatcher`, PRs 2-5 stay within 5% of #2104, which is noise: #2106 changes nothing there and measures +4.6%. | | `main` | #2107 | This PR | vs `main` | vs #2107 | |---|---|---|---|---|---| | Linux: Watch-mode start, warm cache | 1,887ms | 695ms | 492ms | -73.9% (-74.2% to -73.7%) | -29.2% (-29.9% to -28.6%) | | Windows: Watch-mode start, warm cache | 2,577ms | 727ms | 525ms | -79.6% (-79.7% to -79.5%) | -27.7% (-28.1% to -27.4%) | | Linux: Watch-mode start, cold cache | 1,885ms | 652ms | 462ms | -75.5% (-75.8% to -75.0%) | -29.2% (-30.0% to -27.7%) | | Windows: Watch-mode start, cold cache | 2,562ms | 701ms | 493ms | -80.8% (-80.8% to -80.6%) | -29.6% (-29.9% to -29.3%) | | Linux: Heap after a watch-mode start | 31.7MB | 28.1MB | 28.1MB | -11.3% (-11.3% to -11.3%) | -0.1% (-0.1% to -0.1%) | | Windows: Heap after a watch-mode start | 31.7MB | 28.2MB | 28.2MB | -11.3% (-11.3% to -11.3%) | -0.0% (-0.0% to -0.0%) | ## Changelog ``` - **[Performance]**: metro-file-map: Set up file watching during the crawl instead of in a separate walk before it, on Linux and Windows without Watchman ``` ## Test plan New unit tests, and a `watch-integration-test.js` case for a directory the crawl skips but the watcher doesn't. Benchmark as in #2104.

robhogan added this pull request to stack #2109 October 25, 2026 15:22

meta-cla Bot added the CLA Signed This label is managed by the Facebook bot. Authors need to sign the CLA before a PR can be reviewed. label Oct 25, 2026

robhogan mentioned this pull request Oct 25, 2026

metro-file-map: Track only directories and symlinks in FallbackWatcher #2107

Open

robhogan force-pushed the pr2106 branch from 1217f25 to c955ad5 Compare October 25, 2026 15:23

robhogan force-pushed the pr2106 branch from c955ad5 to 1922c78 Compare October 25, 2026 20:13

robhogan force-pushed the pr2106 branch from 1922c78 to b77936b Compare October 26, 2026 11:50

robhogan force-pushed the pr2106 branch 2 times, most recently from 115807f to b1b6854 Compare November 10, 2026 09:13

robhogan force-pushed the pr2106 branch from b1b6854 to 2435125 Compare November 10, 2026 13:34

robhogan mentioned this pull request Nov 10, 2026

metro-file-map: Watch directories as the node crawler lists them #2108

Draft

robhogan marked this pull request as ready for review November 10, 2026 16:17

robhogan requested a review from huntie November 10, 2026 16:18

robhogan force-pushed the pr2106 branch from 2435125 to 680aaf5 Compare November 11, 2026 19:05

Navigation Menu

Repository navigation

metro-file-map: Remove FallbackWatcher's 1s startup delay on Windows - #2106

metro-file-map: Remove FallbackWatcher's 1s startup delay on Windows#2106
robhogan wants to merge 1 commit into
pr2105from
pr2106

robhogan commented Oct 25, 2026 •

edited

Loading

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant


	if (platform === 'win32') {
	// Inherited from sane: win32 needs a settling period after the watches
	// are registered before events can be relied on.
	await new Promise(resolve => setTimeout(resolve, 1000));
	}

Conversation

robhogan commented Oct 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Benchmark

Changelog

Test plan

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

robhogan commented Oct 25, 2026 •

edited

Loading