feat(gatsby-source-filesystem): Expose usePolling option

[markphilpot]

Description

In scenarios where the use of file system polling is necessary (network file systems, hard links, etc).

Relevant chokidar option description here -- https://github.com/paulmillr/chokidar#performance

Documentation

Related Issues

Fixes #36877

[markphilpot]

The plugin README needs to be updated -- If you have any guidance on how you want to incorporate it, I can take a shot at it.

[LekoArts]

Is the CHOKIDAR_USEPOLLING environment variable not working for you?

You may also set the CHOKIDAR_USEPOLLING env variable to true (1) or false (0) in order to override this option.

[LekoArts]

The plugin README needs to be updated -- If you have any guidance on how you want to incorporate it, I can take a shot at it.

The https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-source-filesystem#options section could use a little revamp.

• Add h3 headings for each option
• Below a little paragraph explaining it

[markphilpot]

Is the CHOKIDAR_USEPOLLING environment variable not working for you?

You may also set the CHOKIDAR_USEPOLLING env variable to true (1) or false (0) in order to override this option.

I could not get it to work. Both from the command line and explicitly in package.json, using CHOKIDAR_USEPOLLING=1 gatsby devleop in any combination I tried didn't trigger polling to be used.

[LekoArts]

It works for me CHOKIDAR_USEPOLLING=1 yarn develop 🤷

I'd also be surprised to not have https://github.com/paulmillr/chokidar/blob/0f163b89f3ae76607900aa48fec9fa3fdefd7ca1/index.js#L341 working - so with this in mind I'm actually inclined to not add the option at all. Better to not give people the option (less footguns).

We should update the readme tho (which e.g. could point out the env var)

[markphilpot]

I found the issue:

When you use the options parameter in chokidar, setting usePolling to true also sets useFsEvents to false, but only on macOS.

If you just use the environment variable, both usePolling and useFsEvents are set to true, and you don't get the desired behavior (let's set aside this side effect behavior is not great). I confirmed that to correctly handle my original hard link issue, I need chokidar running with usePolling as true and useFsEvents as false.

It doesn't seem like setting useFsEvents is exposed via an environment variable override.

I'm not sure what the best course of action here is since you need to understand the behavior of an internal library to understand what to do (not to mention the wierd macOS only side effect behavior).

I could try submitting a PR to chokidar to expose a CHOKIDAR_USEFSEVENTS env parameter I guess...

[LekoArts]

Yeah, I fear this is out of our hands then. Best course of action then is to open an issue with them to fix this behavior. Either by introducing a new environment variable or moving the code around so that usePolling is set with the env var before the fsEvents check.