fix(router): hot-reload CSS imported by route files

CSS imported by route files (index/layout) is resolved by Qwik and
injected as a <link>, so it only lives in the SSR module graph. Vite
watches its own client graph plus the route source-file globs, never
this CSS, so edits produced no HMR event and styles stayed stale until a
dev server restart. CSS imported by client-loaded components was
unaffected because Vite handles those natively.

Register the injected CSS files with the watcher and, on change, emit a
css-update so Vite's client swaps the <link> in place. CSS already in
the client graph is left to Vite's native HMR.

Author: briancarbone

.changeset/router-css-hmr.md

@@ -0,0 +1,5 @@
+---
+'@qwik.dev/router': patch
+---
+
+fix: hot-reload CSS imported by route files in dev. Such CSS is resolved by Qwik and injected as a `<link>`, so Vite never watched it and edits required a server restart. The router now watches these files and emits a `css-update` so the stylesheet swaps in place.

packages/qwik-router/src/buildtime/vite/dev-middleware.spec.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect, vi } from 'vitest';
+import type { ViteDevServer } from 'vite';
+import { sendRouterCssHotUpdate } from './dev-middleware';
+
+const file = '/app/src/routes/docs/docs.css';
+
+/** Minimal ViteDevServer stand-in with controllable client/SSR graphs and a spy on the HMR channel. */
+function makeServer(opts: { client?: { url: string }[]; ssr?: { url: string }[] }) {
+  const send = vi.fn();
+  const graph = (mods?: { url: string }[]) => ({ getModulesByFile: () => (mods ? new Set(mods) : undefined) });
+  const server = {
+    environments: {
+      client: { moduleGraph: graph(opts.client), hot: { send } },
+      ssr: { moduleGraph: graph(opts.ssr) },
+    },
+  } as unknown as ViteDevServer;
+  return { server, send };
+}
+
+describe('sendRouterCssHotUpdate', () => {
+  it('ignores non-CSS files', () => {
+    const { server, send } = makeServer({ ssr: [{ url: '/x.tsx' }] });
+    expect(sendRouterCssHotUpdate(server, '/app/src/routes/index.tsx', 1)).toBe(false);
+    expect(send).not.toHaveBeenCalled();
+  });
+
+  it('emits a deduped css-update for route CSS that only lives in the SSR graph', () => {
+    const { server, send } = makeServer({
+      ssr: [{ url: '/src/routes/docs/docs.css' }, { url: '/src/routes/docs/docs.css?inline' }],
+    });
+    expect(sendRouterCssHotUpdate(server, file, 123)).toBe(true);
+    expect(send).toHaveBeenCalledWith({
+      type: 'update',
+      updates: [
+        {
+          type: 'css-update',
+          path: '/src/routes/docs/docs.css',
+          acceptedPath: '/src/routes/docs/docs.css',
+          timestamp: 123,
+        },
+      ],
+    });
+  });
+
+  it('defers to Vite when the CSS is already in the client graph', () => {
+    const { server, send } = makeServer({
+      client: [{ url: '/src/routes/docs/docs.css' }],
+      ssr: [{ url: '/src/routes/docs/docs.css' }],
+    });
+    expect(sendRouterCssHotUpdate(server, file, 1)).toBe(false);
+    expect(send).not.toHaveBeenCalled();
+  });
+});

packages/qwik-router/src/buildtime/vite/dev-middleware.ts

@@ -138,6 +138,11 @@ const getCssUrls = (server: ViteDevServer) => {
 
         if ((isEntryCSS || hasJSImporter) && !hasCSSImporter && !cssImportedByCSS.has(mod.url)) {
           cssModules.add(`${mod.url}${mod.lastHMRTimestamp ? `?t=${mod.lastHMRTimestamp}` : ''}`);
+          // These files only live in the SSR graph, so Vite doesn't watch them. Watch explicitly
+          // so edits fire handleHotUpdate -> sendRouterCssHotUpdate instead of needing a restart.
+          if (mod.file) {
+            server.watcher.add(mod.file);
+          }
         }
       }
     }
@@ -152,3 +157,33 @@ export const getRouterIndexTags = (server: ViteDevServer) => {
     attrs: { rel: 'stylesheet', href: url },
   }));
 };
+
+/**
+ * Live-reload route CSS that Qwik injects as `<link>` tags (see {@link getCssUrls}). Qwik resolves
+ * these imports itself, so they only exist in the SSR graph; Vite finds no client module and skips
+ * HMR, leaving stale styles until a restart. We emit a `css-update` so Vite's client swaps the
+ * `<link>` in place. Returns `true` when handled; CSS in the client graph is left to Vite's HMR.
+ */
+export const sendRouterCssHotUpdate = (
+  server: ViteDevServer,
+  file: string,
+  timestamp: number
+): boolean => {
+  const { client, ssr } = server.environments;
+  if (!isCssPath(file) || client.moduleGraph.getModulesByFile(file)?.size) {
+    return false;
+  }
+  const paths = new Set<string>();
+  for (const mod of ssr.moduleGraph.getModulesByFile(file) ?? []) {
+    mod.lastHMRTimestamp = timestamp; // keep getCssUrls' cache-busting query fresh on full reloads
+    paths.add(mod.url.split('?')[0]);
+  }
+  if (!paths.size) {
+    return false;
+  }
+  client.hot.send({
+    type: 'update',
+    updates: [...paths].map((path) => ({ type: 'css-update' as const, path, acceptedPath: path, timestamp })),
+  });
+  return true;
+};

packages/qwik-router/src/buildtime/vite/plugin.ts

@@ -41,7 +41,11 @@ import type {
   QwikRouterVitePluginOptions,
 } from './types';
 import { validatePlugin } from './validate-plugin';
-import { getRouterIndexTags, makeRouterDevMiddleware } from './dev-middleware';
+import {
+  getRouterIndexTags,
+  makeRouterDevMiddleware,
+  sendRouterCssHotUpdate,
+} from './dev-middleware';
 
 export const QWIK_ROUTER_CONFIG_ID = '@qwik-router-config';
 /**
@@ -366,7 +370,11 @@ function qwikRouterPlugin(
       }
     },
 
-    handleHotUpdate({ file, modules, server }: HmrContext) {
+    handleHotUpdate({ file, modules, server, timestamp }: HmrContext) {
+      // Route CSS is injected as a <link>; swap it in place rather than forcing a restart.
+      if (sendRouterCssHotUpdate(server, file, timestamp)) {
+        return [];
+      }
       if (!ctx || !isRouterSourceFileForContext(file, ctx)) {
         return;
       }