FileWatcher Webpack Plugin

1.2.0 verified Sat Apr 25 auth: no javascript

Webpack plugin that watches files and folders outside webpack's default watch scope using glob patterns. Version 1.2.0. It relies on chokidar for file system monitoring and triggers webpack recompilation when glob-matched files change. Unlike similar plugins (e.g., file-watcher-webpack-plugin, webpack-watch-files-plugin), this one supports recursive directory watching, custom event handlers via chokidar's API, and granular ignore patterns. The package is ESM-only. Note: The plugin's constructor expects an object with a 'watchFileRegex' property (string or array of strings). Common issues include incorrect require style (CJS vs ESM) and misconfiguring the watch path glob (must be relative to the project root).

Common errors

error Error: Cannot find module 'filewatcher-webpack-plugin' ↓

cause Using CommonJS require() on an ESM-only package.

fix

Switch to import statement: import FileWatcherPlugin from 'filewatcher-webpack-plugin'

error TypeError: Class constructor FileWatcherPlugin cannot be invoked without 'new' ↓

cause Importing the default export incorrectly (e.g., destructuring it).

fix

Use new FileWatcherPlugin(...) after default import, not new (await import(...)).FileWatcherPlugin(...).

error The 'watchFileRegex' option must be a string or an array of strings. ↓

cause Passing a RegExp object instead of a glob string.

fix

Use glob patterns (e.g., './**/*.js') not RegExp (e.g., /\.js$/).

error No changes detected after file save ↓

cause The watched path is incorrect or ignored by 'ignored' option.

fix

Verify absolute/relative path and ensure 'ignored' does not cover the target files.

Warnings

breaking The package switched from CJS to ESM in v1.0.0, breaking all require() calls. ↓

fix Change require() to import statements (ESM) or use a dynamic import wrapper.

deprecated Constructor argument 'watchFileRegex' is required but its name is misleading (it accepts strings/arrays, not RegExp objects). ↓

fix Use a string glob pattern like './dir/**/*.js' — not a RegExp literal.

gotcha The plugin does not automatically ignore node_modules; you must set 'ignored' option explicitly to avoid performance issues. ↓

fix Add `ignored: /node_modules/` to the constructor options.

gotcha Relative paths in 'watchFileRegex' are resolved from the project root (current working directory), not from the webpack config location. ↓

fix Use absolute paths or paths relative to process.cwd().

deprecated As of webpack 5, the 'watchRun' hook signature changed, and some older versions of this plugin may not be compatible. ↓

fix Update to v1.2.0+ which explicitly supports webpack 5.

Install

npm install filewatcher-webpack-plugin

yarn add filewatcher-webpack-plugin

pnpm add filewatcher-webpack-plugin

Imports

default

wrong

const FileWatcherPlugin = require('filewatcher-webpack-plugin')

correct

import FileWatcherPlugin from 'filewatcher-webpack-plugin'

Since v1.0.0, the package is ESM-only. CommonJS require() will fail.

FileWatcherPlugin (if named)

wrong

import FileWatcherPlugin from 'filewatcher-webpack-plugin'

correct

import { FileWatcherPlugin } from 'filewatcher-webpack-plugin'

The package exports a default export, not a named one. Named import will be undefined.

type imports
```
import type { FileWatcherPluginOptions } from 'filewatcher-webpack-plugin'
```
TypeScript definitions are included since v1.1.0. The options type is exported for convenience.

Quickstart

Configures the plugin in a webpack config file, watching JS and CSS files outside webpack's default watch scope.

// webpack.config.js
import FileWatcherPlugin from 'filewatcher-webpack-plugin';

export default {
  // ... other config
  plugins: [
    new FileWatcherPlugin({
      watchFileRegex: ['./src/scripts/**/*.js', './src/styles/**/*.css'],
      // Optional chokidar options:
      ignored: /node_modules/,
      ignoreInitial: true
    })
  ]
};