What is the current behavior?

fixes: #3151

Currently, the file watching system in Stencil uses separate functions (watchSrcDirectory and watchRootFiles) to handle watching different types of directories. The system only watches the source directory and root directory, with hardcoded exclusion patterns scattered throughout the code. The watch setup is also sequential, which can impact startup performance.

What is the new behavior?

This PR refactors the file watching architecture to:

• Consolidates file watching logic: Replaces watchSrcDirectory and watchRootFiles with a single, more flexible watchFiles function
• Adds external directory watching: Introduces a new watchExternalDirs config option that allows users to specify additional directories to watch (e.g., node_modules for development workflows)
• Improves code organization: Extracts file and directory exclusion patterns into reusable constants (EXCLUDE_DIRS, EXCLUDE_EXTENSIONS)
• Enhances performance: Uses Promise.all to set up file watchers concurrently instead of sequentially
• Better documentation: Adds comprehensive JSDoc comments explaining the watching behavior
• Code quality improvements: Refactors isWatchIgnorePath function with early returns for better readability

Documentation

The new watchExternalDirs configuration option is documented in the TypeScript interface with JSDoc comments.

Does this introduce a breaking change?

• Yes
• No

This is a non-breaking change. All existing functionality is preserved, and the new watchExternalDirs option is optional with a sensible default (empty array).

Testing

• Verified that existing watch functionality continues to work as expected
• Tested the new watchExternalDirs configuration option by adding external directories
• Confirmed that file exclusion patterns work correctly with the new consolidated approach
• Validated that the concurrent watch setup improves startup performance without affecting functionality

Other information

This refactoring lays the groundwork for more flexible file watching configurations and improved developer experience. The new watchExternalDirs option will be particularly useful for development workflows that need to watch dependencies or other external directories for changes.

A dev build is available at @stencil/core@4.33.1-dev.1749248891.8108e9b