@ms-cloudpack/file-watcher

@ms-cloudpack/file-watcher

An abstraction on the file watching capabilities used in Cloudpack.

Example usage

• Create a watcher:

const watcher = createWatcher();

• Subscribe to a particular package path using watch. (Returns an unwatch function.)

const unwatch = await watcher.watch({ path: 'path/to/package' }, () => console.log(`package changed`));

• To dispose, call the returned unwatch, or call watcher.dispose to unsubscribe from all watchers.

// Dispose an individual watcher.
await unwatch();

// Dispose all watchers.
await watcher.dispose();

createWatcher options

• 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 performance
• policies (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

Shared Root Watcher for Large Monorepos

For optimal performance when watching many packages (100+), use SharedRootWatcher - an orchestrator that wraps any watcher:

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:

const underlyingWatcher = createWatcher({ backend: 'parcel' });
const watcher = new SharedRootWatcher(underlyingWatcher, '/path/to/monorepo');

watcher.watch options

• 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.