Stale CSS after editing a Sass partial: which caching layer is actually responsible?

The short answer

Dart Sass itself is almost never the culprit: it has no persistent compilation cache comparable to the legacy Ruby Sass .sass-cache directory. When editing a partial pulled in via @use or @import produces no change in the emitted CSS, the responsible layer is nearly always one of two things in the surrounding toolchain: a build-tool cache keyed on the entry file (or on stale mtimes), or a watcher dependency-tracking gap where the partial was never registered as a dependency of the entry, so no rebuild is triggered at all.

Signals that separate the two failure modes

The cleanest discriminator is whether a rebuild runs when you save the partial:

• No rebuild is triggered at all (nothing in the dev-server or watch log when you save the partial): this is a watcher/dependency-graph gap. The bundler never learned that the partial feeds the entry. Common causes: the partial is resolved through a custom importer or a non-standard loadPaths entry, so the loader never reported it via the bundler's dependency API (e.g. this.addDependency() in webpack loaders); or the partial lives outside the watched directories/globs.
• A rebuild runs but the output is identical: this is a cache-keying problem. The build tool (or a loader-level cache) decided nothing relevant changed — typically because its cache is keyed on the entry file's content or mtime rather than the full resolved dependency graph, or because mtimes are unreliable on a network filesystem, in a container with a mounted volume, or in CI.

A second useful signal: touch the entry file (add a whitespace change). If that produces correct CSS, the toolchain can compile the new partial content fine — it simply wasn't invalidated by the partial edit. That points at watcher/dependency registration. If even an entry edit yields stale output, suspect a persistent cache directory or content-hash keying that doesn't include partials.

Does the Dart Sass CLI settle it?

Compiling the entry directly is a strong test but not a fully conclusive one:

sass entry.scss /tmp/out.css
# edit the partial, then:
sass entry.scss /tmp/out2.css
diff /tmp/out.css /tmp/out2.css

If the CLI output changes, Sass's compilation is correct and the staleness is in the build-tool layer. The caveat: the CLI only reproduces your setup if it resolves the same files. If your build uses custom importers, package resolution (pkg: URLs), or loader-injected loadPaths, replicate them with --load-path flags, or the CLI may compile a different file than the bundler does and the comparison is meaningless.

Is there a toolchain-independent invalidation contract?

No. There is no shared specification for how Sass integrations must key or invalidate caches. Each integration — sass-loader, Vite's CSS pipeline, framework asset pipelines — implements its own scheme (mtime, content hash, resolved-graph tracking) and its own watcher registration. The one real contract is narrower: the Sass compiler API reports the files it loaded, and a correct integration is expected to register those as watch dependencies. Integrations that resolve files outside that API (custom importers doing their own filesystem work) can silently break it. So behavior must be verified per integration and per version.

Practical verification sequence

1. Enable verbose watch logging (webpack --watch with stats, vite --debug) and save the partial. No change event → watcher gap.
2. Inspect the module graph (webpack stats JSON, or a debug log of resolved dependencies) and confirm the partial appears under the entry.
3. Run the CLI diff test above with matching load paths to clear Sass itself.
4. Clear the build tool's cache directory (e.g. node_modules/.cache) once; if the problem disappears until the next partial edit, the cache keying is at fault.

One caveat worth flagging for review: exact cache locations, debug flags, and watcher behavior vary by version, so confirm flag names against the versions installed rather than assuming the examples above apply verbatim. If the setup turns out to involve a custom importer, that is the first place to look — it is the most common way partials escape both the cache key and the watch graph simultaneously.