docs(platform): clarify FileSystem.watch recursive option behavior #5792
Conversation
|
There was a problem hiding this comment.
Pull request overview
This PR updates the documentation for the FileSystem.watch method to clarify how the recursive option behaves across different backend implementations. Previously, the documentation incorrectly stated that the recursive option was only supported on macOS and Windows, but this has been corrected to reflect the actual behavior.
Key Changes:
- Updated API documentation to explain backend-specific behavior of the
recursiveoption - Clarified that
@parcel/watcher(the default) always watches recursively and ignores the option - Noted that the Node.js
fs.watch()fallback supports the recursive option on all platforms (Node.js v20+)
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| packages/platform/src/FileSystem.ts | Updated JSDoc comment for the watch method to clarify recursive option behavior based on backend implementation |
| packages/platform-node/CHANGELOG.md | Updated changelog entry to match the corrected documentation about recursive option support |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| Added a `recursive` option to `FileSystem.watch` that allows watching for changes in subdirectories. When set to `true`, the watcher will monitor changes in all nested directories. | ||
|
|
||
| Note: The recursive option is only supported on macOS and Windows. On other platforms, it will be ignored. | ||
| Note: The `recursive` option behavior depends on the backend implementation. When using `@parcel/watcher` (default), watching is always recursive on all platforms and this option is ignored. When using the Node.js `fs.watch()` fallback, the `recursive` option is supported on all platforms (Node.js v20+). |
There was a problem hiding this comment.
parcel watcher is not the default
2 participants
Type
Description
Update API docs and previous change log for how
recursiveoption forFileSystem.watchis supported, and how it's handled.Related
It seems that it was AI slop that added "recursive option is only supported on macOS and Windows" to changelog and API docs. By the time recursive option was added, not only that Node.js v18 was already EOL, which meant all LTS at that time supported recursive watch for all OS, but also that
platform-nodewas already using@parcel/watchby default which is always recursive.