How should filesystem cache track an optional build dependency that may not exist?

[hardfist]

Context

I want to treat an optional configuration file, such as tailwind.config.js, as a build dependency of webpack's filesystem cache.

For example:

const path = require("path");

const tailwindConfig = path.resolve(__dirname, "tailwind.config.js");

module.exports = {
	cache: {
		type: "filesystem",
		buildDependencies: {
			config: [__filename, tailwindConfig]
		}
	}
};

The build output may depend on whether this file exists:

• If it exists, its contents affect the build.
• If it does not exist, the build uses default behavior.
• If it is later created or removed, the filesystem cache should be invalidated.

Current behavior

When a directly configured buildDependency cannot be resolved, webpack logs a warning similar to:

[webpack.cache.PackFileCacheStrategy]
Caching failed for pack: Error: Can't resolve '.../tailwind.config.js'

The compilation can still succeed, but the filesystem pack cache cannot be successfully created or updated. Webpack does not appear to treat the unresolved path as a missing dependency automatically.

Expected behavior

I would expect the absence of an optional build dependency to be a valid snapshot state:

State when caching	State when restoring	Expected result
missing	missing	cache remains valid
missing	exists	cache is invalidated
exists	missing	cache is invalidated
exists, unchanged	exists, unchanged	cache remains valid
exists, changed	exists, changed	cache is invalidated

In other words, absence itself should not invalidate the cache repeatedly. A change in existence should invalidate it.

API gap

Webpack has missingDependencies and loaderContext.addMissingDependency(), but these are primarily associated with module snapshots and watch behavior.

There does not appear to be an equivalent build-level API such as cache.missingBuildDependencies, or a way to declare an optional build dependency:

{
	request: tailwindConfig,
	optional: true
}

Webpack internally tracks resolveDependencies.missing, but this is an output of build dependency resolution rather than a public input.

Questions

1. Is the current failure to store the filesystem cache intentional when a directly configured build dependency does not exist?
2. What is the recommended way to track an optional configuration file that affects the whole build?
3. Should webpack allow unresolved cache.buildDependencies and snapshot their missing resolution paths, or introduce an explicit optional/missing build dependency API?
4. Would an API like the following be appropriate?

cache: {
	type: "filesystem",
	buildDependencies: {
		config: [
			__filename,
			{
				request: path.resolve(__dirname, "tailwind.config.js"),
				optional: true
			}
		]
	}
}

Related discussions

There is some precedent for optional transitive build dependencies:

• [PackFileCacheStrategy error because of 'fsevents' on windows #13026
• fix caching crash when using fsevents in build dependencies #13062

That change allows missing dependencies discovered through package.json#optionalDependencies, such as fsevents, to remain optional. However, it does not seem to cover optional build dependencies configured directly by users.

[xiaoxiaojx]

The optional flag looks good — we could consider { dependency, optional: true } instead of request.

[hai-x]

Is the current failure to store the filesystem cache intentional when a directly configured build dependency does not exist?

I think it's intentional. So the resolving fails and with it fails the caching. A warning it printed to the output is stated in #12195 (comment) and also https://github.com/webpack/webpack/pull/12207/changes#diff-a36395db0ecc4d68d7e07145347559f12b21e7df8368886ca1d2c5c355d3c36fR57 added the specific test case about it.

What is the recommended way to track an optional configuration file that affects the whole build?

Given that this behavior is intentional, I would support introducing an optional flag.