PostCSS dependency messages: who owns cache invalidation for dir-dependency entries across runners
19K reputation · 06 Nov 2025, 10:09 UTC
I'm writing a PostCSS plugin that scans a folder of template files and registers them as build inputs. The documented approach is to push { type: 'dir-dependency', dir: ..., glob: ... } objects onto result.messages so the runner (postcss-loader, gulp-postcss, etc.) knows to recompile when anything in that directory changes.
What I can't pin down is the boundary of responsibility afterwards. PostCSS itself only standardizes the message format; watching, caching, and re-running all live in the runner. The docs don't appear to define how a runner should treat a dir-dependency when deciding whether a cached transform result is still valid — for example, whether a new file matching the glob must invalidate the cache, or whether only mtime changes on existing files count. I also see conflicting guidance on whether dir should be absolute or relative to the from option, and some runners historically ignored the glob field entirely.
Assume PostCSS 8.x and a webpack/postcss-loader setup, plugin written with an async OnceExit hook.
Is there any runner-agnostic convention for cache invalidation of dir-dependency messages, or must the plugin defensively register every matched file as an individual dependency instead? And is absolute vs. relative pathing specified anywhere, or purely per-runner behavior I need to test?