Webpack Watch External Files Plugin

4.1.0 verified Sat Apr 25 auth: no javascript

A zero-dependency Webpack 5 plugin that triggers recompilation when external files (not part of the build graph) change. Current version 4.1.0 is ESM-only with Node >=20 required. Key differentiator: no dependencies, supports glob patterns and negations, lightweight alternative to manual watchers.

Common errors

error Cannot find module 'webpack-watch-external-files-plugin' ↓

cause Missing install or Node.js version too low for ESM.

fix

npm install webpack-watch-external-files-plugin --save-dev and use Node >=20

error WatchExternalFilesPlugin is not a constructor ↓

cause Using require() on ESM-only v4+.

fix

Change require to import: import { WatchExternalFilesPlugin } from 'webpack-watch-external-files-plugin'

error Error: [webpack-cli] Invalid configuration object. Webpack has been initialized using a configuration object that does not match the API schema. ↓

cause Passing empty or invalid options (e.g., files missing).

fix

Ensure files option is an array of glob patterns.

Warnings

breaking ESM-only since v4.0: Cannot require() the module. ↓

fix Use import syntax or downgrade to v3.x.

breaking Node.js >=20 required since v4.0. ↓

fix Upgrade Node.js to v20+ or use v3.x (requires Node >=16).

breaking Node.js >=16 required since v3.0. ↓

fix Upgrade Node.js to v16+ or use v2.x (requires Node >=14).

gotcha Negated glob patterns are supported but must be part of the same array. ↓

fix Use the same pattern as in the example: files: ['**/*.txt', '!**/ignore.txt'].

gotcha The plugin does not ignore node_modules by default; you must explicitly add !**/node_modules/** if needed. ↓

fix Add '!**/node_modules/**' to the files array.

Install

npm install webpack-watch-external-files-plugin

yarn add webpack-watch-external-files-plugin

pnpm add webpack-watch-external-files-plugin

Imports

WatchExternalFilesPlugin

wrong

const WatchExternalFilesPlugin = require('webpack-watch-external-files-plugin')

correct

import { WatchExternalFilesPlugin } from 'webpack-watch-external-files-plugin'

ESM-only since v4.x; use v3.x for CJS.

default (WatchExternalFilesPlugin)

wrong

import WatchExternalFilesPlugin from 'webpack-watch-external-files-plugin'

correct

import WatchExternalFilesPlugin from 'webpack-watch-external-files-plugin'

Default export also works, but named is preferred.

ts type

import type { WatchExternalFilesPluginOptions } from 'webpack-watch-external-files-plugin'

TypeScript types are bundled since v2.x.

Quickstart

Example webpack config showing how to watch external JSON configs excluding secrets.

import { WatchExternalFilesPlugin } from 'webpack-watch-external-files-plugin';

export default {
  plugins: [
    new WatchExternalFilesPlugin({
      files: ['/config/**/*.json', '!/config/secrets.json'],
    }),
  ],
};