withastro · matthewp · Apr 13, 2026 · Nov 28, 2025 · Nov 28, 2025 · Jan 16, 2026
diff --git a/.changeset/famous-heads-flash.md b/.changeset/famous-heads-flash.md
@@ -0,0 +1,5 @@
+---
+'astro': patch
+---
+
+Fixes SCSS and CSS module file changes triggering a full page reload instead of hot-updating styles in place during development
diff --git a/packages/astro/e2e/fixtures/hmr/astro.config.mjs b/packages/astro/e2e/fixtures/hmr/astro.config.mjs
@@ -0,0 +1,6 @@
+import preact from '@astrojs/preact';
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+	integrations: [preact()],
+});
diff --git a/packages/astro/e2e/fixtures/hmr/package.json b/packages/astro/e2e/fixtures/hmr/package.json
@@ -2,6 +2,10 @@
   "name": "@e2e/hmr",
   "version": "0.0.0",
   "private": true,
+  "dependencies": {
+    "@astrojs/preact": "workspace:*",
+    "preact": "^10.28.2"
+  },
   "devDependencies": {
     "astro": "workspace:*",
     "sass": "^1.98.0"

diff --git a/packages/astro/e2e/fixtures/hmr/src/components/ScssModuleHeading.jsx b/packages/astro/e2e/fixtures/hmr/src/components/ScssModuleHeading.jsx
@@ -0,0 +1,5 @@
+import styles from '../styles/scss-module.module.scss';
+
+export default function ScssModuleHeading() {
+	return <h1 class={styles.scssModule}>This is blue</h1>;
+}
diff --git a/packages/astro/e2e/fixtures/hmr/src/pages/scss-external.astro b/packages/astro/e2e/fixtures/hmr/src/pages/scss-external.astro
@@ -0,0 +1,11 @@
+<html>
+	<head>
+		<title>Test</title>
+	</head>
+	<body>
+		<h1 class="scss-external">This is blue</h1>
+		<style>
+			@import "../styles/scss-external.scss";
+		</style>
+	</body>
+</html>
diff --git a/packages/astro/e2e/fixtures/hmr/src/pages/scss-module.astro b/packages/astro/e2e/fixtures/hmr/src/pages/scss-module.astro
@@ -0,0 +1,12 @@
+---
+import ScssModuleHeading from '../components/ScssModuleHeading.jsx';
+---
+
+<html>
+	<head>
+		<title>Test</title>
+	</head>
+	<body>
+		<ScssModuleHeading client:load />
+	</body>
+</html>
diff --git a/packages/astro/e2e/fixtures/hmr/src/styles/scss-external.scss b/packages/astro/e2e/fixtures/hmr/src/styles/scss-external.scss
@@ -0,0 +1,3 @@
+.scss-external {
+	color: blue;
+}
diff --git a/packages/astro/e2e/fixtures/hmr/src/styles/scss-module.module.scss b/packages/astro/e2e/fixtures/hmr/src/styles/scss-module.module.scss
@@ -0,0 +1,3 @@
+.scssModule {
+	color: blue;
+}
diff --git a/packages/astro/e2e/hmr.test.js b/packages/astro/e2e/hmr.test.js
@@ -84,6 +84,36 @@ test.describe('Styles', () => {
 		await expect(h).toHaveCSS('color', 'rgb(255, 0, 0)');
 	});
 
+	test('external SCSS refresh with HMR', async ({ page, astro }) => {
+		await page.goto(astro.resolveUrl('/scss-external'));
+
+		page.once('load', throwPageShouldNotReload);
+
+		const h = page.locator('h1');
+		await expect(h).toHaveCSS('color', 'rgb(0, 0, 255)');
+
+		await astro.editFile('./src/styles/scss-external.scss', (original) =>
+			original.replace('blue', 'red'),
+		);
+
+		await expect(h).toHaveCSS('color', 'rgb(255, 0, 0)');
+	});
+
+	test('SCSS modules refresh with HMR', async ({ page, astro }) => {
+		await page.goto(astro.resolveUrl('/scss-module'));
+
+		page.once('load', throwPageShouldNotReload);
+
+		const h = page.locator('h1');
+		await expect(h).toHaveCSS('color', 'rgb(0, 0, 255)');
+
+		await astro.editFile('./src/styles/scss-module.module.scss', (original) =>
+			original.replace('blue', 'red'),
+		);
+
+		await expect(h).toHaveCSS('color', 'rgb(255, 0, 0)');
+	});
+
 	test('added style tag refresh with full-reload', async ({ page, astro }) => {
 		await page.goto(astro.resolveUrl('/css-inline-component'));
 

diff --git a/packages/astro/src/vite-plugin-hmr-reload/index.ts b/packages/astro/src/vite-plugin-hmr-reload/index.ts
@@ -3,6 +3,18 @@ import { VIRTUAL_PAGE_RESOLVED_MODULE_ID } from '../vite-plugin-pages/const.js';
 import { getDevCssModuleNameFromPageVirtualModuleName } from '../vite-plugin-css/util.js';
 import { isAstroServerEnvironment } from '../environments.js';
 
+const STYLE_EXT_REGEX = /\.(?:css|scss|sass|less|styl|pcss)$/i;
+
+function isStyleModule(mod: EnvironmentModuleNode): boolean {
+	if (mod.file && STYLE_EXT_REGEX.test(mod.file)) return true;
+	// CSS modules and other style files may have query params in their id (e.g. ?used, ?direct)
+	if (mod.id) {
+		const idPath = mod.id.split('?')[0];
+		if (STYLE_EXT_REGEX.test(idPath)) return true;
+	}
+	return false;
+}
+
 /**
  * The very last Vite plugin to reload the browser if any SSR-only module are updated
  * which will require a full page reload. This mimics the behaviour of Vite 5 where
@@ -18,10 +30,16 @@ export default function hmrReload(): Plugin {
 				if (!isAstroServerEnvironment(this.environment)) return;
 
 				let hasSsrOnlyModules = false;
+				let hasSkippedStyleModules = false;
 
 				const invalidatedModules = new Set<EnvironmentModuleNode>();
 				for (const mod of modules) {
 					if (mod.id == null) continue;
+					if (isStyleModule(mod)) {
+						hasSkippedStyleModules = true;
+						continue;
+					}
+
 					const clientModule = server.environments.client.moduleGraph.getModuleById(mod.id);
 					if (clientModule != null) continue;
 
@@ -45,6 +63,16 @@ export default function hmrReload(): Plugin {
 					server.ws.send({ type: 'full-reload' });
 					return [];
 				}
+
+				// When style modules were skipped, return an empty array to prevent Vite's
+				// default SSR HMR propagation. Without this, Vite would propagate through the
+				// module graph to .astro importers, find no HMR acceptor, and trigger a
+				// full page reload. The client environment handles CSS HMR natively via
+				// Vite's built-in style update mechanism, which works for all pages
+				// (with or without framework components).
+				if (hasSkippedStyleModules) {
+					return [];
+				}
 			},
 		},
 	};

diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml