Chokidar CLI

Common errors

• command not found: chokidar-cli

  cause The command line utility is named `chokidar`, not `chokidar-cli`, even though the npm package is `chokidar-cli`.
  fix Use `chokidar` instead of `chokidar-cli` in your terminal or scripts. Example: `chokidar "./**/*.js" -c "echo File changed"`.

• Error: EMFILE: too many open files, watch

  cause The operating system's limit for open file descriptors has been reached. This often happens when watching a very large number of files/directories, or when a tool that uses `chokidar` (like `chokidar-cli`) is misconfigured to watch too broadly.
  fix Increase your system's file descriptor limit (e.g., `ulimit -n 2048` on Linux/macOS for the current session, or modify system configuration for permanent changes). Alternatively, refine your glob patterns to watch fewer files and directories, or use `chokidar`'s `ignored` option to exclude unnecessary paths.

• Command not running or syntax error in command specified with -c

  cause Incorrect quoting or shell interpretation of the command string, especially when it contains spaces, variables, or other special characters.
  fix Ensure the command passed to `-c` is enclosed in double quotes. If the command itself contains double quotes (e.g., for string literals), escape them properly. Example for `package.json`: `"watch:build": "chokidar \"src/**/*.ts\" -c \"npm run compile -- --path={path}\""`.

Warnings

• breaking When specifying patterns and commands, especially within `package.json` scripts, cross-platform compatibility requires the use of double quotes (escaped if necessary) around arguments. Single quotes may not be universally supported across all operating systems and shells, leading to parsing issues.
  Fix: Always use double quotes (e.g., `"**/*.js" -c "your command here"`) for patterns and commands. For commands within `package.json` scripts, escape inner double quotes: `"chokidar \"**/*.js\" -c \"echo {event}\"`.
• gotcha The package name is `chokidar-cli`, but the command line utility itself is invoked as `chokidar` (without the `-cli` suffix). Using `chokidar-cli` on the command line will result in a 'command not found' error.
  Fix: After installation (`npm install -g chokidar-cli` or `npm install chokidar-cli`), always use the command `chokidar` to run the utility.
• gotcha Watching files on network directories (e.g., NFS, SMB shares) or within certain Docker environments often requires using the `--polling` option for reliable change detection, as native file system events may not propagate correctly.
  Fix: Append `--polling` to your `chokidar` command when watching network-mounted directories: `chokidar "**/*.less" -c "npm run build-less" --polling`.
• deprecated The underlying `chokidar` library has moved to ESM-only and increased its minimum Node.js requirement to v20+ in its v5 release (Nov 2025). While `chokidar-cli` v3.0.0 only requires Node.js >=8.10.0, it uses an older version of `chokidar`. Compatibility with future `chokidar-cli` versions may require updated Node.js environments and changes if `chokidar-cli` itself updates to `chokidar` v4/v5.
  Fix: Monitor `chokidar-cli` release notes for updates regarding its internal `chokidar` dependency. For `chokidar` itself, ensure Node.js v20+ for v5, or v14+ for v4.

Install

• npm install chokidar-cli npm
• yarn add chokidar-cli yarn
• pnpm add chokidar-cli pnpm

Imports

• chokidar
  wrong:

  import { chokidar } from 'chokidar-cli'

  correct:

  npm install -g chokidar-cli
  # Then use the 'chokidar' command in your terminal

  This package is a command-line utility. Its functionality is accessed via the `chokidar` command in the terminal, not via programmatic JavaScript imports. Attempting to `import` or `require` this package directly will result in errors as it does not expose a public JavaScript API for direct consumption.
• chokidar
  wrong:

  const chokidar = require('chokidar-cli')

  correct:

  npm install chokidar-cli
  # Then use in package.json scripts:
  # {"scripts": {"watch:js": "chokidar \"**/*.js\" -c \"npm run build-js\""}}

  When installed locally, the `chokidar` command is available via npm scripts or by using `npx chokidar`. Direct CommonJS/ESM import is not supported as it's a CLI wrapper. Ensure proper escaping of quotes within package.json scripts for cross-platform compatibility.
• chokidar
  wrong:

  chokidar-cli "src/**/*.less" -c "npm run build-less -- {path}"

  correct:

  chokidar "src/**/*.less" -c "npm run build-less -- {path}"

  The command line utility is invoked as `chokidar`, not `chokidar-cli`. Using `chokidar-cli` as the command name will result in a 'command not found' error.

Quickstart

Demonstrates global installation, watching a glob pattern for `.js` files, and executing a command with event and path details on changes.

#!/bin/bash

# Install chokidar-cli globally for easy command access
npm install -g chokidar-cli

# Create a dummy project directory and a file
mkdir -p my-watched-project/src
echo "// Initial content" > my-watched-project/src/app.js

# Navigate into the project directory
cd my-watched-project

echo "Watching for changes in src/**/*.js. Try modifying src/app.js..."

# Run chokidar to watch JavaScript files and execute a simple echo command
# The -c flag runs a command, and {event} and {path} are placeholders
chokidar "src/**/*.js" -c "echo 'File {path} was {event}ed!' && ls -la src"

# To stop watching, press Ctrl+C in the terminal where chokidar is running.

# Example of how to trigger an event (run this in a separate terminal after starting chokidar):
# echo "console.log('updated content');" >> src/app.js
# rm src/app.js
# echo "// New file" > src/another.js