CSS Module HMR leaves server-rendered React components with stale class names when also used by a hydrated island

[forberg]

Astro Info

- Astro: `7.3.3`
  - `@astrojs/react`: `6.0.6`
  - React / React DOM: `19.2.6`
  - Vite, resolved by Astro: `8.2.2`
  - Node.js: `24.11.0`
  - OS: Linux x64
  - Browser: Chromium, tested using Playwright

If this issue only occurs in one browser, which browser is a problem?

No response

Describe the Bug

When a React component using a CSS Module is rendered both without hydration and inside a hydrated island, editing the CSS updates the hydrated instance but leaves t he server-rendered instance with stale class names.

The stylesheet is updated successfully, but its generated class names change. The non-hydrated HTML still references the previous class names, so it loses its stylin
g. Manually refreshing the page fixes it.

This was reproduced in a minimal Astro project without custom PostCSS plugins or application-specific integrations.

Actual behavior

Stage	Non-hydrated card	Hydrated card
Initial load	Red background	Red background
After CSS edit	Old class name; transparent background	New class name; blue background
After manual refresh	New class name; blue background	New class name; blue background

The browser receives a js-update for Card.tsx, and Vite logs:

[vite] hot updated: /src/components/Card.tsx

No full page reload occurs.

Inspecting the DOM confirms that only the hydrated card receives the updated CSS Module class name. The stylesheet contains the new selector but no longer contains the selector referenced by the non-hydrated card.

Possible cause

The default CSS Module scoped-name generator incorporates stylesheet contents, so even a declaration-only edit changes the exported class names.

In the installed version, astro:hmr-reload appears to skip the server-side full reload when the stylesheet also exists in the client module graph. Client HMR updates the hydrated instance, but cannot update the non-hydrated HTML.

The presence of a stylesheet in the client graph does not necessarily mean all HTML using its exported class names is client-managed.

Workaround

Using stable CSS Module names in development fixes ordinary declaration edits. For example, in astro.config.mjs, keep production defaults and configure stable names for development:

import { defineConfig } from "astro/config";
import react from "@astrojs/react";

export default defineConfig({
  integrations: [react()],
  vite: {
    css: {
      modules: import.meta.env.DEV
        ? {
            generateScopedName: "[name]__[local]__[hash:base64:5]",
          }
        : undefined,
    },
  },
});

With this scoped-name pattern, both cards updated correctly without a reload in the same reproduction.

This is not a complete fix: changes to exported class mappings, such as class renames or composition changes, can still require refreshing the server-rendered HTML.

What's the expected result?

Both cards should reflect the updated CSS.

If updating the non-hydrated instance requires regenerating its HTML, a full page reload would also be an acceptable fallback.

Link to Minimal Reproducible Example

https://github.com/forberg/astro-hmr-bug

Participation

• I am willing to submit a pull request for this issue.

[astro-factory]

Triage complete

• Prepare the workspace: ready
• Install dependencies: complete
• Build the project: complete
• Reproduce the issue: confirmed
• Diagnose the cause: high confidence
• Verify the diagnosis: bug
• Attempt a fix: verified
• Publish the result: set triage: fix pending

---

• Reproduced: Yes
• Exploration: Yes — View branch
• Unit Test: Yes — test/units/vite-plugin-hmr-reload/hmr-reload.test.ts and test/units/dev/hmr-css-invalidation.test.ts
• Priority: P3: minor bug. This only affects development HMR for CSS Modules in the specific scenario where the same component is used both with and without hydration. Production builds are unaffected, and a manual page refresh resolves the issue. The reporter also documented a workaround using stable generateScopedName in dev config.

The root cause is in packages/astro/src/vite-plugin-hmr-reload/index.ts. The astro:hmr-reload plugin's hotUpdate handler treats CSS Module files (.module.css) identically to regular CSS files. When a CSS Module has a client-side counterpart (because a hydrated island imports it), the handler skips the full page reload, trusting client-side CSS HMR to handle it. This is correct for regular CSS where class names are stable, but CSS Modules export JS class-name mappings whose hashes change with file content — so the server-rendered HTML ends up with stale class names that no longer match any CSS rule.

I found a potential fix for this issue. The fix adds a isCSSModuleFile() check that detects .module.css/.module.scss/etc. files and forces a full page reload when they change, ensuring server-rendered HTML is re-generated with the updated class names. Four unit tests were added covering CSS module reload, SCSS module reload, regular CSS non-reload, and dev-css invalidation.

Try this fix

You can test this fix right now without waiting for a release:

# astro
npm i https://pkg.pr.new/astro@0612ffd

If this fixes your issue, please leave a comment letting us know (for example
"confirmed, this fixes it"). A pull request will then be opened to get it merged.

Full Triage Report

Reproduction

Cloned the reporter's reproduction repo and tested against current main.

Setup: A React component (Card.tsx) imports Card.module.css and is rendered in index.astro both without hydration (<Card id="ssr" />) and with hydration (<Card id="hydrated" client:load />).

Steps:

1. Started dev server, opened page in browser
2. Verified both cards initially share class _card_11n3w_1
3. Changed Card.module.css background from red to blue
4. After HMR: SSR card retained stale class _card_11n3w_1, hydrated card updated to _card_pvi5i_1
5. Stylesheet only contained the new selector — SSR card lost all styling
6. Manual page refresh fixed both cards

Diagnosis (High Confidence)

The bug is in the hotUpdate handler of astro:hmr-reload (packages/astro/src/vite-plugin-hmr-reload/index.ts). The handler's getStyleModuleType() returns 'file' for both regular CSS and CSS Modules. When the module has a client counterpart, it sets hasSkippedStyleModules = true and skips the full reload.

Debug instrumentation confirmed the exact code path:

processing mod.id: .../Card.module.css styleType: file clientModule: true
  -> skipping style (has client counterpart)

Git history context: PR #14924 introduced this skip behavior to prevent unnecessary reloads for SCSS/CSS modules. Its commit message explicitly acknowledges that "CSS module HMR requires a client-side framework to re-render components with updated class name hashes — pure SSR pages cannot hot-update CSS module class names without a full reload." However, it only tested the client:load-only scenario and didn't consider the mixed-usage case where the same CSS Module is used by both hydrated and non-hydrated components.

Fix Details

File changed: packages/astro/src/vite-plugin-hmr-reload/index.ts

• Added CSS_MODULES_RE regex to detect .module.css, .module.scss, etc.
• Added isCSSModuleFile() helper checking both mod.file and mod.id
• In the style handling branch, CSS Module files now always trigger a full page reload regardless of client counterpart

Trade-off: This causes full reloads even when a CSS Module is used exclusively by hydrated components. This is acceptable because (1) the fix is simple and safe, (2) a full reload is brief during development, and (3) detecting non-hydrated usage would require complex module graph analysis.

Tests added (4 new, all passing):

• hmr-reload.test.ts: CSS module reload, SCSS module reload, regular CSS non-reload
• hmr-css-invalidation.test.ts: CSS Module dev-css invalidation

Changeset: .changeset/proud-yaks-start.md — astro patch

This report was made by an LLM. The analysis may be wrong, and the potential fix might not work, but is intended as a starting point for exploring the issue.

[forberg]

confirmed, this fixes it

[astro-factory]

The fix has been verified! A pull request has been created: #18109

[forberg]

@astro-factory is there a way of doing this without doing full page reload?

[forberg]

Bot, is there a way of doing this without doing full page reload?

[matthewp]

Bot, this fix is not correct, we do not want to do a full page reload. Please triage again.