fix(start): preserve dev SSR CSS order

.changeset/fix-dev-ssr-css-order.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/start-plugin-core': patch
+---
+
+Fix dev SSR style collection to preserve CSS order without duplicating imported styles, while retaining styles from code-split routes.

e2e/react-start/dev-ssr-styles/src/components/CodeSplitStyledBox.tsx

@@ -0,0 +1,9 @@
+import styles from '../styles/code-split-route.module.css'
+
+export function CodeSplitStyledBox() {
+  return (
+    <div className={styles.styledBox} data-testid="styled-box">
+      This box should have a blue background when dev styles are enabled.
+    </div>
+  )
+}

e2e/react-start/dev-ssr-styles/src/routeTree.gen.ts

@@ -9,8 +9,14 @@
 // Additionally, you should also exclude this file from your linter and/or formatter to prevent it from being checked or modified.
 
 import { Route as rootRouteImport } from './routes/__root'
+import { Route as CssImportOrderRouteImport } from './routes/css-import-order'
 import { Route as IndexRouteImport } from './routes/index'
 
+const CssImportOrderRoute = CssImportOrderRouteImport.update({
+  id: '/css-import-order',
+  path: '/css-import-order',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const IndexRoute = IndexRouteImport.update({
   id: '/',
   path: '/',
@@ -19,28 +25,39 @@ const IndexRoute = IndexRouteImport.update({
 
 export interface FileRoutesByFullPath {
   '/': typeof IndexRoute
+  '/css-import-order': typeof CssImportOrderRoute
 }
 export interface FileRoutesByTo {
   '/': typeof IndexRoute
+  '/css-import-order': typeof CssImportOrderRoute
 }
 export interface FileRoutesById {
   __root__: typeof rootRouteImport
   '/': typeof IndexRoute
+  '/css-import-order': typeof CssImportOrderRoute
 }
 export interface FileRouteTypes {
   fileRoutesByFullPath: FileRoutesByFullPath
-  fullPaths: '/'
+  fullPaths: '/' | '/css-import-order'
   fileRoutesByTo: FileRoutesByTo
-  to: '/'
-  id: '__root__' | '/'
+  to: '/' | '/css-import-order'
+  id: '__root__' | '/' | '/css-import-order'
   fileRoutesById: FileRoutesById
 }
 export interface RootRouteChildren {
   IndexRoute: typeof IndexRoute
+  CssImportOrderRoute: typeof CssImportOrderRoute
 }
 
 declare module '@tanstack/react-router' {
   interface FileRoutesByPath {
+    '/css-import-order': {
+      id: '/css-import-order'
+      path: '/css-import-order'
+      fullPath: '/css-import-order'
+      preLoaderRoute: typeof CssImportOrderRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/': {
       id: '/'
       path: '/'
@@ -53,6 +70,7 @@ declare module '@tanstack/react-router' {
 
 const rootRouteChildren: RootRouteChildren = {
   IndexRoute: IndexRoute,
+  CssImportOrderRoute: CssImportOrderRoute,
 }
 export const routeTree = rootRouteImport
   ._addFileChildren(rootRouteChildren)

e2e/react-start/dev-ssr-styles/src/routes/css-import-order.tsx

@@ -0,0 +1,17 @@
+import { createFileRoute } from '@tanstack/react-router'
+import '../styles/css-import-order.css'
+
+export const Route = createFileRoute('/css-import-order')({
+  component: CssImportOrder,
+})
+
+function CssImportOrder() {
+  return (
+    <main>
+      <h1>CSS import order</h1>
+      <div className="css-import-order" data-testid="css-import-order">
+        The route stylesheet should override its imported base stylesheet.
+      </div>
+    </main>
+  )
+}

e2e/react-start/dev-ssr-styles/src/routes/index.tsx

@@ -1,4 +1,5 @@
 import { createFileRoute } from '@tanstack/react-router'
+import { CodeSplitStyledBox } from '../components/CodeSplitStyledBox'
 
 export const Route = createFileRoute('/')({
   component: Home,
@@ -8,9 +9,7 @@ function Home() {
   return (
     <div>
       <h1 data-testid="home-heading">Dev SSR Styles Test</h1>
-      <div className="styled-box" data-testid="styled-box">
-        This box should have a blue background when dev styles are enabled.
-      </div>
+      <CodeSplitStyledBox />
     </div>
   )
 }

e2e/react-start/dev-ssr-styles/src/styles/app.css

@@ -4,10 +4,3 @@ body {
   padding: 20px;
   background-color: #f0f4f8;
 }
-
-.styled-box {
-  background-color: #3b82f6;
-  color: white;
-  padding: 24px;
-  border-radius: 12px;
-}

e2e/react-start/dev-ssr-styles/src/styles/code-split-route.module.css

@@ -0,0 +1,6 @@
+.styledBox {
+  background-color: #3b82f6;
+  color: white;
+  padding: 24px;
+  border-radius: 12px;
+}

e2e/react-start/dev-ssr-styles/src/styles/css-import-base.css

@@ -0,0 +1,5 @@
+.css-import-order {
+  --css-import-base-marker: issue-7794;
+  background-color: #ffffff;
+  color: #000000;
+}

e2e/react-start/dev-ssr-styles/src/styles/css-import-order.css

@@ -0,0 +1,7 @@
+@import './css-import-base.css';
+
+.css-import-order {
+  background-color: #111827;
+  color: #ffffff;
+  padding: 24px;
+}

e2e/react-start/dev-ssr-styles/tests/app.spec.ts

@@ -22,6 +22,37 @@ test.describe(`dev.ssrStyles (mode=${ssrStylesMode})`, () => {
   })
 
   if (ssrStylesMode === 'default') {
+    test('dev CSS order is stable after client modules load', async ({
+      page,
+    }) => {
+      const cssBodies: Array<Promise<string>> = []
+      page.on('response', (response) => {
+        if (
+          new URL(response.url()).pathname.endsWith(
+            '/@tanstack-start/styles.css',
+          )
+        ) {
+          cssBodies.push(response.text())
+        }
+      })
+
+      await page.goto('/css-import-order')
+      await expect(page.getByTestId('css-import-order')).toBeVisible()
+      await expect.poll(() => cssBodies.length).toBeGreaterThanOrEqual(1)
+
+      await page.reload()
+      await expect(page.getByTestId('css-import-order')).toBeVisible()
+      await expect.poll(() => cssBodies.length).toBeGreaterThanOrEqual(2)
+
+      const [initialCss, reloadedCss] = await Promise.all(cssBodies.slice(0, 2))
+      expect(reloadedCss).toBe(initialCss)
+      expect(initialCss).toContain('/* /src/styles/app.css */')
+      expect(initialCss).toContain('/* /src/styles/css-import-order.css */')
+      expect(initialCss.indexOf('/* /src/styles/app.css */')).toBeLessThan(
+        initialCss.indexOf('/* /src/styles/css-import-order.css */'),
+      )
+    })
+
     test.describe('default (enabled, basepath = vite base)', () => {
       test.use({ javaScriptEnabled: false, whitelistErrors })
 
@@ -52,7 +83,9 @@ test.describe(`dev.ssrStyles (mode=${ssrStylesMode})`, () => {
         expect(href).toMatch(/^\/@tanstack-start\/styles\.css/)
       })
 
-      test('CSS is applied on initial page load (SSR)', async ({ page }) => {
+      test('CSS from a code-split route component is applied during SSR', async ({
+        page,
+      }) => {
         await page.goto('/')
 
         const element = page.getByTestId('styled-box')
@@ -64,6 +97,36 @@ test.describe(`dev.ssrStyles (mode=${ssrStylesMode})`, () => {
         )
         expect(backgroundColor).toBe('rgb(59, 130, 246)')
       })
+
+      test('CSS @import dependencies are not appended after their importer', async ({
+        page,
+      }) => {
+        await page.goto('/css-import-order')
+
+        const element = page.getByTestId('css-import-order')
+        await expect(element).toBeVisible()
+
+        // css-import-order.css imports a white base rule, then overrides it
+        // with this dark background. Collecting the imported file separately
+        // appends the white rule and reverses the intended cascade.
+        const backgroundColor = await element.evaluate(
+          (el) => getComputedStyle(el).backgroundColor,
+        )
+        expect(backgroundColor).toBe('rgb(17, 24, 39)')
+
+        const devStylesHref = await page
+          .locator(`link[${DEV_STYLES_ATTR}]`)
+          .getAttribute('href')
+        expect(devStylesHref).toBeTruthy()
+
+        const cssResponse = await page.request.get(
+          new URL(devStylesHref!, page.url()).href,
+        )
+        expect(cssResponse.ok()).toBeTruthy()
+
+        const css = await cssResponse.text()
+        expect(css.match(/--css-import-base-marker/g)).toHaveLength(1)
+      })
     })
   }
 

e2e/solid-start/dev-ssr-styles/.gitignore

@@ -0,0 +1,7 @@
+node_modules
+dist
+.routeTree.gen.ts
+src/routeTree.gen.ts
+test-results
+playwright-report
+port*.txt

e2e/solid-start/dev-ssr-styles/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "tanstack-solid-start-e2e-dev-ssr-styles",
+  "private": true,
+  "sideEffects": false,
+  "type": "module",
+  "scripts": {
+    "dev": "vite dev --port 3000",
+    "dev:e2e": "vite dev --port $PORT",
+    "build": "vite build && tsc --noEmit",
+    "start": "pnpx srvx --prod -s ../client dist/server/server.js",
+    "test:e2e:dev": "MODE=dev playwright test --project=chromium",
+    "test:e2e": "rm -rf port*.txt; pnpm run test:e2e:dev"
+  },
+  "dependencies": {
+    "@tanstack/solid-router": "workspace:*",
+    "@tanstack/solid-start": "workspace:*",
+    "solid-js": "^1.9.10"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.61.0",
+    "@tanstack/router-core": "workspace:*",
+    "@tanstack/router-e2e-utils": "workspace:*",
+    "@types/node": "^22.10.2",
+    "srvx": "^0.11.9",
+    "typescript": "^6.0.2",
+    "vite": "^8.0.14",
+    "vite-plugin-solid": "^2.11.11"
+  }
+}

e2e/solid-start/dev-ssr-styles/playwright.config.ts

@@ -0,0 +1,31 @@
+import { defineConfig, devices } from '@playwright/test'
+import { getTestServerPort } from '@tanstack/router-e2e-utils'
+import packageJson from './package.json' with { type: 'json' }
+
+const PORT = await getTestServerPort(packageJson.name)
+const baseURL = `http://localhost:${PORT}`
+
+export default defineConfig({
+  testDir: './tests',
+  workers: 1,
+  reporter: [['line']],
+  globalSetup: './tests/setup/global.setup.ts',
+  globalTeardown: './tests/setup/global.teardown.ts',
+  use: { baseURL },
+  webServer: {
+    command: 'pnpm dev:e2e',
+    url: baseURL,
+    reuseExistingServer: !process.env.CI,
+    stdout: 'pipe',
+    env: {
+      VITE_NODE_ENV: 'test',
+      PORT: String(PORT),
+    },
+  },
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+  ],
+})

e2e/solid-start/dev-ssr-styles/src/components/CodeSplitStyledBox.tsx

@@ -0,0 +1,9 @@
+import styles from '../styles/code-split-route.module.css'
+
+export function CodeSplitStyledBox() {
+  return (
+    <div class={styles.styledBox} data-testid="styled-box">
+      This box is styled by a code-split route component.
+    </div>
+  )
+}

e2e/solid-start/dev-ssr-styles/src/router.tsx

@@ -0,0 +1,10 @@
+import { createRouter } from '@tanstack/solid-router'
+import { routeTree } from './routeTree.gen'
+
+export function getRouter() {
+  return createRouter({
+    routeTree,
+    scrollRestoration: true,
+    defaultPreload: false,
+  })
+}

e2e/solid-start/dev-ssr-styles/src/routes/__root.tsx

@@ -0,0 +1,27 @@
+import {
+  HeadContent,
+  Outlet,
+  Scripts,
+  createRootRoute,
+} from '@tanstack/solid-router'
+import { HydrationScript } from 'solid-js/web'
+import '~/styles/app.css'
+
+export const Route = createRootRoute({
+  component: RootComponent,
+})
+
+function RootComponent() {
+  return (
+    <html>
+      <head>
+        <HydrationScript />
+        <HeadContent />
+      </head>
+      <body>
+        <Outlet />
+        <Scripts />
+      </body>
+    </html>
+  )
+}

e2e/solid-start/dev-ssr-styles/src/routes/index.tsx

@@ -0,0 +1,15 @@
+import { createFileRoute } from '@tanstack/solid-router'
+import { CodeSplitStyledBox } from '../components/CodeSplitStyledBox'
+
+export const Route = createFileRoute('/')({
+  component: Home,
+})
+
+function Home() {
+  return (
+    <main>
+      <h1 data-testid="home-heading">Solid Dev SSR Styles Test</h1>
+      <CodeSplitStyledBox />
+    </main>
+  )
+}

e2e/solid-start/dev-ssr-styles/src/styles/app.css

@@ -0,0 +1,5 @@
+body {
+  font-family: sans-serif;
+  margin: 0;
+  padding: 20px;
+}

e2e/solid-start/dev-ssr-styles/src/styles/code-split-route.module.css

@@ -0,0 +1,6 @@
+.styledBox {
+  --solid-code-split-style-marker: present;
+  background-color: #3b82f6;
+  color: white;
+  padding: 24px;
+}