A file watcher abstraction for use with Cloudpack.
npm install @ms-cloudpack/file-watcherAn abstraction on the file watching capabilities used in Cloudpack.
1. Create a watcher:
``ts`
const watcher = createWatcher();
2. Subscribe to a particular package path using watch. (Returns an unwatch function.)
`tspackage changed
const unwatch = await watcher.watch({ path: 'path/to/package' }, () => console.log());`
3. To dispose, call the returned unwatch, or call watcher.dispose to unsubscribe from all watchers.
`ts
// Dispose an individual watcher.
await unwatch();
// Dispose all watchers.
await watcher.dispose();
`
- type ('default' | 'fork', optional): By default, this will create a watcher in the same thread. Use type: 'fork' to create the watcher in a forked process.backend
- ('default' | 'parcel', optional): Choose the file watching backend.'default'
- : Uses chokidar (default)'parcel'
- : Uses @parcel/watcher for better performancepolicies
- (optional): Enable performance optimizations'shared-root'
- : Multiplexes N package watches into 1 root watch (for monorepos with 100+ packages)'debounce'
- : Batches rapid file changes into single notifications
For optimal performance when watching many packages (100+), use SharedRootWatcher - an orchestrator that wraps any watcher:
`ts
import { SharedRootWatcher, createWatcher } from '@ms-cloudpack/file-watcher';
// Create underlying watcher (can be any backend)
const underlyingWatcher = createWatcher({ backend: 'default' });
// Wrap it with SharedRootWatcher orchestrator
const watcher = new SharedRootWatcher(underlyingWatcher, '/path/to/monorepo');
// Watch multiple packages efficiently (single OS watcher)
await watcher.watch({ path: '/path/to/monorepo/packages/pkg1' }, onPkg1Change);
await watcher.watch({ path: '/path/to/monorepo/packages/pkg2' }, onPkg2Change);
// ... 1000+ packages
`
This uses a single file system watcher at the root instead of creating one per package.
With Parcel backend for maximum performance:
`ts`
const underlyingWatcher = createWatcher({ backend: 'parcel' });
const watcher = new SharedRootWatcher(underlyingWatcher, '/path/to/monorepo');
- path (string): The absolute root path to be watched.id
- (string, optional): ID for the watch job (defaults to path). If you call watch twice using the same id, subsequent calls will be ignored.watchPaths
- (string[], optional): Relative paths/globs from the root path. Currently, only negative globs (starting with !) are supported and will be used to ignore files. Positive globs are ignored - the watcher will watch all files in the root path by default. Defaults are under "@ms-cloudpack/path-utilities" in sourceFilesGlobs`.