@@ -0,0 +1,5 @@
+---
+"webpack": minor
+---
+
+Allow optional filesystem cache build dependencies.
@@ -25,6 +25,22 @@ export type CacheOptions = true | CacheOptionsNormalized;
  */
 export type CacheOptionsNormalized =
 	false | MemoryCacheOptions | FileCacheOptions;
+/**
+ * A build dependency for filesystem cache invalidation.
+ * @since 5.111.0
+ */
+export type BuildDependencyItem =
+	| string
+	| {
+			/**
+			 * Request to a dependency (resolved as directory relative to the context directory).
+			 */
+			dependency: string;
+			/**
+			 * When true, the dependency may be missing. Existence changes invalidate the cache.
+			 */
+			optional?: boolean;
+	  };
 /**
  * The base directory (absolute path!) for resolving the `entry` option. If `output.pathinfo` is set, the included pathinfo is shortened to this directory.
  */
@@ -1213,7 +1229,7 @@ export interface FileCacheOptions {
 		/**
 		 * List of dependencies the build depends on.
 		 */
-		[k: string]: string[];
+		[k: string]: BuildDependencyItem[];
 	};
 	/**
 	 * Base directory for the cache (defaults to node_modules/.cache/webpack).
 
@@ -70,8 +70,11 @@ class Cache {
 			get: new AsyncSeriesBailHook(["identifier", "etag", "gotHandlers"]),
 			/** @type {AsyncParallelHook<[string, Etag | null, Data]>} */
 			store: new AsyncParallelHook(["identifier", "etag", "data"]),
-			/** @type {AsyncParallelHook<[Iterable<string>]>} */
-			storeBuildDependencies: new AsyncParallelHook(["dependencies"]),
+			/** @type {AsyncParallelHook<[Iterable<string>, Iterable<string>]>} */
+			storeBuildDependencies: new AsyncParallelHook([
+				"dependencies",
+				"optionalDependencies"
+			]),
 			/** @type {SyncHook<[]>} */
 			beginIdle: new SyncHook([]),
 			/** @type {AsyncParallelHook<[]>} */
@@ -139,12 +142,14 @@ class Cache {
 	 * Persists the set of build dependencies required to determine whether the
 	 * cache can be restored in a future compilation.
 	 * @param {Iterable<string>} dependencies list of all build dependencies
+	 * @param {Iterable<string>} optionalDependencies list of optional build dependencies
 	 * @param {CallbackCache<void>} callback signals when the dependencies are stored
 	 * @returns {void}
 	 */
-	storeBuildDependencies(dependencies, callback) {
+	storeBuildDependencies(dependencies, optionalDependencies, callback) {
 		this.hooks.storeBuildDependencies.callAsync(
 			dependencies,
+			optionalDependencies,
 			makeWebpackErrorCallback(callback, "Cache.hooks.storeBuildDependencies")
 		);
 	}
 
@@ -1458,6 +1458,8 @@ BREAKING CHANGE: Asset processing hooks in Compilation has been merged into a si
 		this.missingDependencies = new LazySet();
 		/** @type {FileSystemDependencies} */
 		this.buildDependencies = new LazySet();
+		/** @type {FileSystemDependencies} */
+		this.optionalBuildDependencies = new LazySet();
 		// TODO webpack 6 remove
 		/**
 		 * @deprecated
@@ -5008,6 +5010,7 @@ Or do you want to use the entrypoints '${name}' and '${runtime}' independently o
 			this.contextDependencies.addAll(child.contextDependencies);
 			this.missingDependencies.addAll(child.missingDependencies);
 			this.buildDependencies.addAll(child.buildDependencies);
+			this.optionalBuildDependencies.addAll(child.optionalBuildDependencies);
 		}
 
 		for (const module of this.modules) {
 
@@ -671,6 +671,7 @@ class Compiler {
 							if (err) return finalCallback(err);
 							this.cache.storeBuildDependencies(
 								compilation.buildDependencies,
+								compilation.optionalBuildDependencies,
 								(err) => {
 									if (err) return finalCallback(err);
 									return finalCallback(null, stats);
 
@@ -1884,10 +1884,13 @@ class FileSystemInfo {
 	 * Resolves build dependencies.
 	 * @param {string} context context directory
 	 * @param {Iterable<string>} deps dependencies
+	 * @param {Iterable<string> | undefined} optionalDeps optional dependencies that may be missing
 	 * @param {(err?: Error | null, resolveBuildDependenciesResult?: ResolveBuildDependenciesResult) => void} callback callback function
 	 * @returns {void}
 	 */
-	resolveBuildDependencies(context, deps, callback) {
+	resolveBuildDependencies(context, deps, optionalDeps, callback) {
+		/** @type {Set<string>} */
+		const optional = new Set(optionalDeps);
 		const { resolveContext, resolveEsm, resolveCjs, resolveCjsAsChild } =
 			this._createBuildDependenciesResolvers();
 
@@ -1979,7 +1982,7 @@ class FileSystemInfo {
 						type: RBDT_RESOLVE_INITIAL,
 						context,
 						path: dep,
-						expected: undefined,
+						expected: optional.has(dep) ? false : undefined,
 						issuer: undefined
 					})
 			),
@@ -2005,6 +2008,7 @@ class FileSystemInfo {
 							if (err) {
 								if (expected === false) {
 									resolveResults.set(key, false);
+									resolveMissing.add(path);
 									return callback();
 								}
 								invalidResolveResults.add(key);
@@ -2060,6 +2064,7 @@ class FileSystemInfo {
 								if (err) {
 									if (expected === false) {
 										resolveResults.set(key, false);
+										resolveMissing.add(path);
 										return callback();
 									}
 									invalidResolveResults.add(key);
 
@@ -307,6 +307,7 @@ class Watching {
 				logger.time("storeBuildDependencies");
 				this.compiler.cache.storeBuildDependencies(
 					compilation.buildDependencies,
+					compilation.optionalBuildDependencies,
 					(err) => {
 						logger.timeEnd("storeBuildDependencies");
 						if (err) return handleError(err);
@@ -338,6 +339,8 @@ class Watching {
 			this.compiler.cache.storeBuildDependencies(
 				/** @type {Compilation} */
 				(compilation).buildDependencies,
+				/** @type {Compilation} */
+				(compilation).optionalBuildDependencies,
 				(err) => {
 					logger.timeEnd("storeBuildDependencies");
 					if (err) return handleError(err, cbs);
@@ -518,6 +521,7 @@ class Watching {
 				logger.time("storeBuildDependencies");
 				this.compiler.cache.storeBuildDependencies(
 					compilation.buildDependencies,
+					compilation.optionalBuildDependencies,
 					(err2) => {
 						logger.timeEnd("storeBuildDependencies");
 						shutdown(err || err2);
 
@@ -9,14 +9,36 @@
 
 const PLUGIN_NAME = "AddBuildDependenciesPlugin";
 
+/**
+ * @typedef {object} NormalizedBuildDependencyItem
+ * @property {string} dependency request to resolve
+ * @property {boolean} optional when true the dependency may be missing
+ */
+
+/**
+ * @param {string | { dependency: string, optional?: boolean }} item build dependency
+ * @returns {NormalizedBuildDependencyItem} normalized build dependency
+ */
+const normalizeBuildDependencyItem = (item) => {
+	if (typeof item === "string") {
+		return { dependency: item, optional: false };
+	}
+	return {
+		dependency: item.dependency,
+		optional: Boolean(item.optional)
+	};
+};
+
 class AddBuildDependenciesPlugin {
 	/**
 	 * Creates an instance of AddBuildDependenciesPlugin.
-	 * @param {Iterable<string>} buildDependencies list of build dependencies
+	 * @param {Iterable<string | { dependency: string, optional?: boolean }>} buildDependencies list of build dependencies
 	 */
 	constructor(buildDependencies) {
-		/** @type {Set<string>} */
-		this.buildDependencies = new Set(buildDependencies);
+		/** @type {NormalizedBuildDependencyItem[]} */
+		this.buildDependencies = [...buildDependencies].map(
+			normalizeBuildDependencyItem
+		);
 	}
 
 	/**
@@ -26,7 +48,14 @@ class AddBuildDependenciesPlugin {
 	 */
 	apply(compiler) {
 		compiler.hooks.compilation.tap(PLUGIN_NAME, (compilation) => {
-			compilation.buildDependencies.addAll(this.buildDependencies);
+			for (const { dependency, optional } of this.buildDependencies) {
+				compilation.buildDependencies.add(dependency);
+				if (optional) {
+					compilation.optionalBuildDependencies.add(dependency);
+					compilation.missingDependencies.add(dependency);
+					compilation.fileDependencies.add(dependency);
+				}
+			}
 		});
 	}
 }
 
@@ -98,10 +98,10 @@ class IdleFileCachePlugin {
 
 		compiler.cache.hooks.storeBuildDependencies.tap(
 			{ name: PLUGIN_NAME, stage: Cache.STAGE_DISK },
-			(dependencies) => {
+			(dependencies, optionalDependencies) => {
 				pendingIdleTasks.set(BUILD_DEPENDENCIES_KEY, () =>
 					Promise.resolve().then(() =>
-						strategy.storeBuildDependencies(dependencies)
+						strategy.storeBuildDependencies(dependencies, optionalDependencies)
 					)
 				);
 			}
 
@@ -1263,6 +1263,8 @@ class PackFileCacheStrategy {
 		this.buildDependencies = new Set();
 		/** @type {FileSystemDependencies} */
 		this.newBuildDependencies = new LazySet();
+		/** @type {FileSystemDependencies} */
+		this.newOptionalBuildDependencies = new LazySet();
 		/** @type {InstanceType<Snapshot> | undefined} */
 		this.resolveBuildDependenciesSnapshot = undefined;
 		/** @type {ResolveResults | undefined} */
@@ -1492,10 +1494,13 @@ class PackFileCacheStrategy {
 	/**
 	 * Stores build dependencies.
 	 * @param {FileSystemDependencies | Iterable<string>} dependencies dependencies to store
+	 * @param {FileSystemDependencies | Iterable<string>} optionalDependencies optional dependencies to store
+	 * @returns {void}
 	 */
-	storeBuildDependencies(dependencies) {
+	storeBuildDependencies(dependencies, optionalDependencies) {
 		if (this.readonly) return;
 		this.newBuildDependencies.addAll(dependencies);
+		this.newOptionalBuildDependencies.addAll(optionalDependencies);
 	}
 
 	afterAllStored() {
@@ -1512,9 +1517,14 @@ class PackFileCacheStrategy {
 				let promise;
 				/** @type {Set<string>} */
 				const newBuildDependencies = new Set();
+				/** @type {Set<string>} */
+				const optionalBuildDependencies = new Set();
 				for (const dep of this.newBuildDependencies) {
 					if (!this.buildDependencies.has(dep)) {
 						newBuildDependencies.add(dep);
+						if (this.newOptionalBuildDependencies.has(dep)) {
+							optionalBuildDependencies.add(dep);
+						}
 					}
 				}
 				if (newBuildDependencies.size > 0 || !this.buildSnapshot) {
@@ -1533,6 +1543,7 @@ class PackFileCacheStrategy {
 							this.fileSystemInfo.resolveBuildDependencies(
 								this.context,
 								newBuildDependencies,
+								optionalBuildDependencies,
 								(err, result) => {
 									this.logger.timeEnd("resolve build dependencies");
 									if (err) return reject(err);
@@ -1667,6 +1678,7 @@ class PackFileCacheStrategy {
 								this.buildDependencies.add(dep);
 							}
 							this.newBuildDependencies.clear();
+							this.newOptionalBuildDependencies.clear();
 							this.logger.timeEnd("store pack");
 							const stats = pack.getContentStats();
 							this.logger.log(
@@ -1887,6 +1899,7 @@ class PackFileCacheStrategy {
 		this.fileSystemInfo.clear();
 		this.buildDependencies.clear();
 		this.newBuildDependencies.clear();
+		this.newOptionalBuildDependencies.clear();
 		this.resolveBuildDependenciesSnapshot = undefined;
 		this.resolveResults = undefined;
 		this.buildSnapshot = undefined;
-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"webpack": minor
 +---
++
 +Allow optional filesystem cache build dependencies.
Original file line number	Diff line number	Diff line change
`@@ -98,10 +98,10 @@ class IdleFileCachePlugin {`
`98`	`98`
`99`	`99`	`compiler.cache.hooks.storeBuildDependencies.tap(`
`100`	`100`	`{ name: PLUGIN_NAME, stage: Cache.STAGE_DISK },`
`101`		`- (dependencies) => {`
	`101`	`+ (dependencies, optionalDependencies) => {`
`102`	`102`	`pendingIdleTasks.set(BUILD_DEPENDENCIES_KEY, () =>`
`103`	`103`	`Promise.resolve().then(() =>`
`104`		`- strategy.storeBuildDependencies(dependencies)`
	`104`	`+ strategy.storeBuildDependencies(dependencies, optionalDependencies)`
`105`	`105`	`)`
`106`	`106`	`);`
`107`	`107`	`}`