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

.changeset/router-css-hmr.md

@@ -0,0 +1,5 @@
+---
+'@qwik.dev/router': patch
+---
+
+fix: hot-reload route-imported CSS in dev without a server restart

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

@@ -0,0 +1,55 @@
+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,10 @@ const getCssUrls = (server: ViteDevServer) => {
 
         if ((isEntryCSS || hasJSImporter) && !hasCSSImporter && !cssImportedByCSS.has(mod.url)) {
           cssModules.add(`${mod.url}${mod.lastHMRTimestamp ? `?t=${mod.lastHMRTimestamp}` : ''}`);
+          // SSR-only CSS isn't watched by Vite; watch it so edits fire handleHotUpdate.
+          if (mod.file) {
+            server.watcher.add(mod.file);
+          }
         }
       }
     }
@@ -152,3 +156,36 @@ export const getRouterIndexTags = (server: ViteDevServer) => {
     attrs: { rel: 'stylesheet', href: url },
   }));
 };
+
+/**
+ * Live-reload route CSS that Qwik injects as `<link>` tags; it only lives in the SSR graph, so Vite
+ * skips HMR. Emit a `css-update` to swap the `<link>` in place. Returns `true` when handled.
+ */
+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

@@ -42,7 +42,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';
 /**
@@ -373,7 +377,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;
       }