cpwatch

A minimal utility for performing actions when something changes in the file system.

Overview

cpwatch is a CLI for running automated actions when files. It uses a Watcher-plugin architecture that supports (nay, expects!) modern ESM / JS / Typescript code.

The API is designed to accommodate the following use cases:

• Full build cpwatch does a sweep of the file system being monitored and passes every file / directory it finds to the corresponding Watcher. This is the basic "build all the things" mode.

• Watch Mode After doing a Full Build, cpwatch continues monitoring the file system for changes, notifying each Watcher of changes as needed. This is useful in local dev environments for keeping things in sync in realtime.

• Check Mode cpwatch only looks at files passed on the command line (i.e. no Full Build), and does not alter the filesystem. Instead, terminates with a non-zero exit if changes are needed. This is useful for pre-commit hooks (e.g. lefthook) to ensure files are up to date before committing changes to a repo.

Built in Watchers

cpwatch currently ships plugins that we, CodePen, have found useful in our build environment:

• AssetsWatcher: For ~~copying~~ hard-linking images, stylesheets, and other non-code assets between Typescript's "src" and "dist" directories
• TypescriptCleanupWatcher: For cleaning up vestigial artifacts that get left behind when renaming JS/TSX files
• ScriptIndexWatcher: For auto-generating hierarchical index.js files
• StaticFileWatcher: For copying and building static assets

Configuration

Configuration is done in-code, typically in a codewatch.config.ts file. Examples forthcoming

Custom Watcher plugins

Plugin API documentation forthcoming.