diff --git a/src/content/contribute/writing-a-plugin.mdx b/src/content/contribute/writing-a-plugin.mdx index 7e2604931471..52b369463b41 100644 --- a/src/content/contribute/writing-a-plugin.mdx +++ b/src/content/contribute/writing-a-plugin.mdx @@ -300,6 +300,82 @@ T> We are using synchronous `tap()` method to tap into the `processAssets` hook T> The [`processAssets`](/api/compilation-hooks/#processassets) hook also supports the `additionalAssets` property, that allows your plugin to intercept not only assets that were added by other plugins prior to the execution of the specified stage, but also for assets that were added on a later stages. This allows to intercept absolutely all the assets which are part of the compilation. However, in our example we are fine with using the `SUMMARIZE` stage to capture all the assets generated on previous stages (this should account for all assets in general case). +## Watching for file changes + +When webpack runs in watch mode (`webpack --watch` or `webpack serve`), +it creates a new compilation for each rebuild triggered by file changes. + +The `compiler.modifiedFiles` Set lets your plugin know **which specific +files triggered the rebuild**, so you can skip expensive work for unrelated files. + +This is useful for plugins that need to react only to specific file changes +(e.g., regenerating assets, reprocessing templates, or invalidating caches). + +```js +class WatchNotifierPlugin { + apply(compiler) { + compiler.hooks.watchRun.tap("WatchNotifierPlugin", (compiler) => { + if (compiler.modifiedFiles) { + const changedFiles = [...compiler.modifiedFiles] + .map((file) => ` • ${file}`) + .join("\n"); + + console.log(`\nFiles changed:\n${changedFiles}`); + } + }); + } +} + +export default WatchNotifierPlugin; +``` + +> **Note**: +> +> - `compiler.modifiedFiles` is a `Set`, not an array +> - It is `undefined` on the first (cold) build +> - It is only populated during watch rebuilds + +### Adding custom file dependencies + +If your plugin reads external files (config files, templates, etc.) +that webpack does not track by default, you must tell webpack to watch them. + +You can tell webpack to watch different types of dependencies: + +- `compilation.fileDependencies` is used to track individual files that your plugin depends on, so webpack can trigger a rebuild when those files change + +- `compilation.contextDependencies` is used to watch directories, so any change inside them triggers a rebuild + +- `compilation.missingDependencies` is used to track files that are currently missing, so webpack can trigger a rebuild when they are created + +```js +import path from "node:path"; + +class TemplateWatchPlugin { + apply(compiler) { + compiler.hooks.compilation.tap("TemplateWatchPlugin", (compilation) => { + const templatePath = path.resolve(__dirname, "my-template.html"); + + // Ensure webpack watches this file + compilation.fileDependencies.add(templatePath); + + // Watch a directory (context dependency) + const templatesDir = path.resolve(__dirname, "templates"); + compilation.contextDependencies.add(templatesDir); + + // Example: mark a missing dependency + const missingFile = path.resolve(__dirname, "missing-file.txt"); + compilation.missingDependencies.add(missingFile); + }); + } +} + +export default TemplateWatchPlugin; +``` + +Without calling `fileDependencies.add()`, webpack will not trigger +a rebuild when the file changes — even if your plugin depends on it. + ## Different Plugin Shapes A plugin can be classified into types based on the event hooks it taps into. Every event hook is pre-defined as synchronous or asynchronous or waterfall or parallel hook and hook is called internally using call/callAsync method. The list of hooks that are supported or can be tapped into is generally specified in `this.hooks` property. diff --git a/src/utilities/cn.mjs b/src/utilities/cn.mjs index 9a6521eb4c77..998bb12afcbf 100644 --- a/src/utilities/cn.mjs +++ b/src/utilities/cn.mjs @@ -1,4 +1,3 @@ -/* eslint-disable import/no-extraneous-dependencies */ import { clsx } from "clsx"; import { twMerge } from "tailwind-merge";