[thelazylamaGit]

Changes

• Builds on fix(dev): refresh stale CSS during HMR #16957 by adding the missing component <style> block cases to dev CSS HMR handling.

Fixes stale dev CSS after editing component style blocks that are compiled into virtual CSS modules.

Astro’s dev CSS collector already treats style block requests like these as CSS:

• *.astro?astro&type=style...
• *.svelte?svelte&type=style...
• *.vue?vue&type=style...

But astro:hmr-reload only recognized real CSS file paths, so these style block modules could skip the per-route virtual:astro:dev-css:* invalidation path. This caused stale SSR/dev CSS after HMR edits.

This PR classifies Astro, Svelte, and Vue style block requests as style modules, invalidates per-route dev CSS when client CSS HMR can handle the update, and preserves SSR invalidation/full reload when no client module exists to apply the update.

Also addresses #17083

Testing

• Added unit coverage for Astro, Svelte, and Vue style block virtual modules invalidating per-route dev CSS modules.

• Added coverage for SSR-only style block modules using SSR invalidation/full reload.

• Added negative coverage for non-style component queries, raw CSS imports, unrelated type=style requests, and component-style-looking requests without the matching compiler marker.

Docs

• No docs changes. This fixes dev-server HMR behaviour without changing user-facing APIs.

[changeset-bot]

🦋 Changeset detected

Latest commit: d365a8c

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[codspeed]

Merging this PR will not alter performance

✅ 21 untouched benchmarks

---

_{Comparing thelazylamaGit:astro-css-fix (d365a8c) with main (82bf7e2)¹}

Footnotes

1. No successful run was found on main (112d3ea) during the generation of this report, so 82bf7e2 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[felmonon]

Traced this against main to confirm the root cause; the fix direction looks right.

Root cause verified: on main, an Astro component style virtual module (/src/Component.astro?astro&type=style&index=0&lang.css) is never classified as a style module — hasStyleExtension fails on both mod.file (.astro) and mod.id.split('?')[0] (also .astro) — so it falls through to the generic branch. When the module also exists in the client graph, the update is skipped outright (clientModule != null → continue), meaning the hasSkippedStyleModules path never runs and the per-route dev-css virtual modules are never invalidated — so the inline anti-FOUC styles keep serving stale CSS until a dev-server restart. Classifying via parseAstroRequest is the right discriminator, and the query-order-permutation test is a good catch given the params have no guaranteed order.

The SSR-only special case is also justified as written: without it, the new classification would route SSR-only style modules into the skip path, where there is no client-side CSS HMR to actually deliver the update — restoring invalidate + full-reload for exactly that sub-case preserves main's behavior for those modules. A one-line comment on the new branch saying "no client module means nothing will apply the CSS update client-side, so force a reload" would make the asymmetry (one sub-case skips, the other reloads) obvious to the next reader.

Non-blocking nit: isAstroStyleModule parses the query twice per style module (once inside isStyleModule, once in the hotUpdate branch). Trivial cost, but hoisting the parse result would avoid it.

Unit coverage (css/scss/less, query-order permutations, ws expectations) looks solid.

[thelazylamaGit]

Noticed this same issue was happening for other framework <style> blocks too so updated this to handle the broader component style block case, not only Astro <style> blocks.

The same stale dev CSS path can happen for Svelte and Vue style block modules like:

• *.svelte?svelte&type=style...
• *.vue?vue&type=style...

These are collected by Astro’s dev CSS graph, but were not recognised by astro:hmr-reload as style modules because the filename before the query is .svelte/.vue, not .css.

The fix now classifies Astro/Svelte/Vue style block requests explicitly, keeps the client-CSS-HMR path when a client module exists, and keeps the SSR invalidation/full-reload fallback when no client module exists. I've personally tested and verified that with this fix, component <style> block changes now update as expected in dev.

[thelazylamaGit]

@matthewp would you mind giving this a review when you have a chance?

This builds on my previous PR you approved #16957 and includes some cases I missed.

It addresses a dev CSS HMR regression that’s been around since the Astro 5 to Astro 6 transition, and I think it would be valuable to get into the next release if possible.

[matthewp]

@thelazylamaGit Yes, adding it to my review stack, thanks!

[thelazylamaGit]

Noticed after some more testing that normal CSS files could be swallowed when no client style module was available, requiring a manual reload.

This was because the previous PR logic invalidated virtual:astro:dev-css:* and then always skipped SSR reload for style updates, assuming Vite client CSS HMR would apply the browser update. That works when the style exists in the client graph, but fails for cases like global.css when there is no exact client module to receive the update.

This now does one exact client lookup first, then falls back to getModulesByFile() for query-varied style ids, and only skips reload when a client style module actually exists. Otherwise it invalidates SSR and forces a reload.

[thelazylamaGit]

Note whilst this PR fixes some genuine bugs and makes css hmr better than it was, its still not perfect and can cause some false positives due to hasClientStyleModuleByFile() being a bit too broad which means the css wont update and requires a manual reload, at which point hot-updates will start working again.

The alternative which is doing exact matches only would result in forcing full reloads a lot of the time even when it doesn't necessarily have to.

I'm going to do some more investigating into how vite 8 client modules work and do another PR that hopefully should fix this and prevent false positives whilst still allowing hot-reloads when applicable.