+
+ )
+}
diff --git a/e2e/react-start/css-modules/src/styles/app.scss b/e2e/react-start/css-modules/src/styles/app.scss
new file mode 100644
index 0000000000..2c2fde6cb2
--- /dev/null
+++ b/e2e/react-start/css-modules/src/styles/app.scss
@@ -0,0 +1,4 @@
+// Import the mixin, which should make them available to future imports
+@import './center-mixin.scss';
+
+@import './mixin-consumer.scss';
diff --git a/e2e/react-start/css-modules/src/styles/center-mixin.scss b/e2e/react-start/css-modules/src/styles/center-mixin.scss
new file mode 100644
index 0000000000..7eeb174b6e
--- /dev/null
+++ b/e2e/react-start/css-modules/src/styles/center-mixin.scss
@@ -0,0 +1,5 @@
+@mixin center-mixin {
+ display: flex;
+ justify-content: center;
+ align-items: center;
+}
diff --git a/e2e/react-start/css-modules/src/styles/mixin-consumer.scss b/e2e/react-start/css-modules/src/styles/mixin-consumer.scss
new file mode 100644
index 0000000000..52715c90b0
--- /dev/null
+++ b/e2e/react-start/css-modules/src/styles/mixin-consumer.scss
@@ -0,0 +1,10 @@
+.mixin-container {
+ // Use the center mixin, which is included in app.scss
+ // This works for the client build, but not for the dev server styles.css build
+ @include center-mixin;
+ background-color: #a855f7; /* purple-500 */
+ padding: 24px;
+ border-radius: 12px;
+ color: white;
+ min-height: 100px;
+}
diff --git a/e2e/react-start/css-modules/tests/css.spec.ts b/e2e/react-start/css-modules/tests/css.spec.ts
index bdfd2308a4..ba876cc2ae 100644
--- a/e2e/react-start/css-modules/tests/css.spec.ts
+++ b/e2e/react-start/css-modules/tests/css.spec.ts
@@ -113,6 +113,44 @@ test.describe('CSS styles in SSR (dev mode)', () => {
const className = await element.getAttribute('class')
expect(className).toBe('global-container')
})
+
+ test('Sass mixin styles are applied on initial page load', async ({
+ page,
+ baseURL,
+ }) => {
+ await page.goto(buildUrl(baseURL!, '/sass-mixin'))
+
+ const element = page.getByTestId('mixin-styled')
+ await expect(element).toBeVisible()
+
+ // Verify the mixin is applied (display: flex from center-mixin)
+ const display = await element.evaluate(
+ (el) => getComputedStyle(el).display,
+ )
+ expect(display).toBe('flex')
+
+ const justifyContent = await element.evaluate(
+ (el) => getComputedStyle(el).justifyContent,
+ )
+ expect(justifyContent).toBe('center')
+
+ const alignItems = await element.evaluate(
+ (el) => getComputedStyle(el).alignItems,
+ )
+ expect(alignItems).toBe('center')
+
+ // Verify other styles from mixin-consumer.scss
+ // #a855f7 (purple-500) in RGB is rgb(168, 85, 247)
+ const backgroundColor = await element.evaluate(
+ (el) => getComputedStyle(el).backgroundColor,
+ )
+ expect(backgroundColor).toBe('rgb(168, 85, 247)')
+
+ const padding = await element.evaluate(
+ (el) => getComputedStyle(el).padding,
+ )
+ expect(padding).toBe('24px')
+ })
})
test('styles persist after hydration', async ({ page, baseURL }) => {
diff --git a/e2e/react-start/css-modules/vite.config.ts b/e2e/react-start/css-modules/vite.config.ts
index 6027af4bfa..9dacdf984a 100644
--- a/e2e/react-start/css-modules/vite.config.ts
+++ b/e2e/react-start/css-modules/vite.config.ts
@@ -22,9 +22,11 @@ export default defineConfig(async () => {
tsConfigPaths({
projects: ['./tsconfig.json'],
}),
+ // Nitro is placed BEFORE tanstackStart to test that our CSS middleware
+ // works regardless of plugin order (nitro has a catch-all middleware)
+ ...nitroPlugin,
tanstackStart(),
viteReact(),
- ...nitroPlugin,
],
}
})
diff --git a/e2e/solid-start/css-modules/package.json b/e2e/solid-start/css-modules/package.json
index 4acefb88ae..934c4ffa62 100644
--- a/e2e/solid-start/css-modules/package.json
+++ b/e2e/solid-start/css-modules/package.json
@@ -22,6 +22,7 @@
"@playwright/test": "^1.50.1",
"@tanstack/router-e2e-utils": "workspace:*",
"@types/node": "^22.10.2",
+ "sass": "^1.97.2",
"srvx": "^0.10.0",
"typescript": "^5.7.2",
"vite": "^7.1.7",
diff --git a/e2e/solid-start/css-modules/src/routes/__root.tsx b/e2e/solid-start/css-modules/src/routes/__root.tsx
index 304d76fb33..9ee18b1a5a 100644
--- a/e2e/solid-start/css-modules/src/routes/__root.tsx
+++ b/e2e/solid-start/css-modules/src/routes/__root.tsx
@@ -50,6 +50,13 @@ function RootComponent() {
>
CSS Modules
+
+ Sass Mixin
+
CSS Collection Test - Sass Mixin
++ This page tests that Sass mixins imported in a parent file are available + to subsequent imports during dev mode SSR. +
+ +
+
+ Sass Mixin Applied - Should be centered with purple background
+
+
+
+
+ )
+}
diff --git a/e2e/solid-start/css-modules/src/styles/app.scss b/e2e/solid-start/css-modules/src/styles/app.scss
new file mode 100644
index 0000000000..2c2fde6cb2
--- /dev/null
+++ b/e2e/solid-start/css-modules/src/styles/app.scss
@@ -0,0 +1,4 @@
+// Import the mixin, which should make them available to future imports
+@import './center-mixin.scss';
+
+@import './mixin-consumer.scss';
diff --git a/e2e/solid-start/css-modules/src/styles/center-mixin.scss b/e2e/solid-start/css-modules/src/styles/center-mixin.scss
new file mode 100644
index 0000000000..7eeb174b6e
--- /dev/null
+++ b/e2e/solid-start/css-modules/src/styles/center-mixin.scss
@@ -0,0 +1,5 @@
+@mixin center-mixin {
+ display: flex;
+ justify-content: center;
+ align-items: center;
+}
diff --git a/e2e/solid-start/css-modules/src/styles/mixin-consumer.scss b/e2e/solid-start/css-modules/src/styles/mixin-consumer.scss
new file mode 100644
index 0000000000..52715c90b0
--- /dev/null
+++ b/e2e/solid-start/css-modules/src/styles/mixin-consumer.scss
@@ -0,0 +1,10 @@
+.mixin-container {
+ // Use the center mixin, which is included in app.scss
+ // This works for the client build, but not for the dev server styles.css build
+ @include center-mixin;
+ background-color: #a855f7; /* purple-500 */
+ padding: 24px;
+ border-radius: 12px;
+ color: white;
+ min-height: 100px;
+}
diff --git a/e2e/solid-start/css-modules/tests/css.spec.ts b/e2e/solid-start/css-modules/tests/css.spec.ts
index bdfd2308a4..ba876cc2ae 100644
--- a/e2e/solid-start/css-modules/tests/css.spec.ts
+++ b/e2e/solid-start/css-modules/tests/css.spec.ts
@@ -113,6 +113,44 @@ test.describe('CSS styles in SSR (dev mode)', () => {
const className = await element.getAttribute('class')
expect(className).toBe('global-container')
})
+
+ test('Sass mixin styles are applied on initial page load', async ({
+ page,
+ baseURL,
+ }) => {
+ await page.goto(buildUrl(baseURL!, '/sass-mixin'))
+
+ const element = page.getByTestId('mixin-styled')
+ await expect(element).toBeVisible()
+
+ // Verify the mixin is applied (display: flex from center-mixin)
+ const display = await element.evaluate(
+ (el) => getComputedStyle(el).display,
+ )
+ expect(display).toBe('flex')
+
+ const justifyContent = await element.evaluate(
+ (el) => getComputedStyle(el).justifyContent,
+ )
+ expect(justifyContent).toBe('center')
+
+ const alignItems = await element.evaluate(
+ (el) => getComputedStyle(el).alignItems,
+ )
+ expect(alignItems).toBe('center')
+
+ // Verify other styles from mixin-consumer.scss
+ // #a855f7 (purple-500) in RGB is rgb(168, 85, 247)
+ const backgroundColor = await element.evaluate(
+ (el) => getComputedStyle(el).backgroundColor,
+ )
+ expect(backgroundColor).toBe('rgb(168, 85, 247)')
+
+ const padding = await element.evaluate(
+ (el) => getComputedStyle(el).padding,
+ )
+ expect(padding).toBe('24px')
+ })
})
test('styles persist after hydration', async ({ page, baseURL }) => {
diff --git a/e2e/vue-start/css-modules/package.json b/e2e/vue-start/css-modules/package.json
index 353301906e..513d7caa34 100644
--- a/e2e/vue-start/css-modules/package.json
+++ b/e2e/vue-start/css-modules/package.json
@@ -23,6 +23,7 @@
"@tanstack/router-e2e-utils": "workspace:*",
"@types/node": "^22.10.2",
"@vitejs/plugin-vue-jsx": "^4.1.2",
+ "sass": "^1.97.2",
"srvx": "^0.10.0",
"typescript": "^5.7.2",
"vite": "^7.1.7",
diff --git a/e2e/vue-start/css-modules/src/routes/__root.tsx b/e2e/vue-start/css-modules/src/routes/__root.tsx
index 39c0110bee..9e292654bc 100644
--- a/e2e/vue-start/css-modules/src/routes/__root.tsx
+++ b/e2e/vue-start/css-modules/src/routes/__root.tsx
@@ -50,6 +50,13 @@ function RootComponent() {
>
CSS Modules
+
+ Sass Mixin
+
CSS Collection Test - Sass Mixin
++ This page tests that Sass mixins imported in a parent file are available + to subsequent imports during dev mode SSR. +
+ +
+
+ Sass Mixin Applied - Should be centered with purple background
+
+
+
+
+ )
+}
diff --git a/e2e/vue-start/css-modules/src/styles/app.scss b/e2e/vue-start/css-modules/src/styles/app.scss
new file mode 100644
index 0000000000..2c2fde6cb2
--- /dev/null
+++ b/e2e/vue-start/css-modules/src/styles/app.scss
@@ -0,0 +1,4 @@
+// Import the mixin, which should make them available to future imports
+@import './center-mixin.scss';
+
+@import './mixin-consumer.scss';
diff --git a/e2e/vue-start/css-modules/src/styles/center-mixin.scss b/e2e/vue-start/css-modules/src/styles/center-mixin.scss
new file mode 100644
index 0000000000..7eeb174b6e
--- /dev/null
+++ b/e2e/vue-start/css-modules/src/styles/center-mixin.scss
@@ -0,0 +1,5 @@
+@mixin center-mixin {
+ display: flex;
+ justify-content: center;
+ align-items: center;
+}
diff --git a/e2e/vue-start/css-modules/src/styles/mixin-consumer.scss b/e2e/vue-start/css-modules/src/styles/mixin-consumer.scss
new file mode 100644
index 0000000000..52715c90b0
--- /dev/null
+++ b/e2e/vue-start/css-modules/src/styles/mixin-consumer.scss
@@ -0,0 +1,10 @@
+.mixin-container {
+ // Use the center mixin, which is included in app.scss
+ // This works for the client build, but not for the dev server styles.css build
+ @include center-mixin;
+ background-color: #a855f7; /* purple-500 */
+ padding: 24px;
+ border-radius: 12px;
+ color: white;
+ min-height: 100px;
+}
diff --git a/e2e/vue-start/css-modules/tests/css.spec.ts b/e2e/vue-start/css-modules/tests/css.spec.ts
index 1ed0a4ee3a..f15b4196c6 100644
--- a/e2e/vue-start/css-modules/tests/css.spec.ts
+++ b/e2e/vue-start/css-modules/tests/css.spec.ts
@@ -115,6 +115,44 @@ test.describe('CSS styles in SSR (dev mode)', () => {
const className = await element.getAttribute('class')
expect(className).toBe('global-container')
})
+
+ test('Sass mixin styles are applied on initial page load', async ({
+ page,
+ baseURL,
+ }) => {
+ await page.goto(buildUrl(baseURL!, '/sass-mixin'))
+
+ const element = page.getByTestId('mixin-styled')
+ await expect(element).toBeVisible()
+
+ // Verify the mixin is applied (display: flex from center-mixin)
+ const display = await element.evaluate(
+ (el) => getComputedStyle(el).display,
+ )
+ expect(display).toBe('flex')
+
+ const justifyContent = await element.evaluate(
+ (el) => getComputedStyle(el).justifyContent,
+ )
+ expect(justifyContent).toBe('center')
+
+ const alignItems = await element.evaluate(
+ (el) => getComputedStyle(el).alignItems,
+ )
+ expect(alignItems).toBe('center')
+
+ // Verify other styles from mixin-consumer.scss
+ // #a855f7 (purple-500) in RGB is rgb(168, 85, 247)
+ const backgroundColor = await element.evaluate(
+ (el) => getComputedStyle(el).backgroundColor,
+ )
+ expect(backgroundColor).toBe('rgb(168, 85, 247)')
+
+ const padding = await element.evaluate(
+ (el) => getComputedStyle(el).padding,
+ )
+ expect(padding).toBe('24px')
+ })
})
test('styles persist after hydration', async ({ page, baseURL }) => {
diff --git a/packages/start-plugin-core/src/dev-server-plugin/dev-styles.ts b/packages/start-plugin-core/src/dev-server-plugin/dev-styles.ts
index 39bf7e6608..e3d0943915 100644
--- a/packages/start-plugin-core/src/dev-server-plugin/dev-styles.ts
+++ b/packages/start-plugin-core/src/dev-server-plugin/dev-styles.ts
@@ -2,18 +2,37 @@
* CSS collection for dev mode.
* Crawls the Vite module graph to collect CSS from the router entry and all its dependencies.
*/
+import path from 'node:path'
import type { ModuleNode, ViteDevServer } from 'vite'
// CSS file extensions supported by Vite
const CSS_FILE_REGEX =
/\.(css|less|sass|scss|styl|stylus|pcss|postcss|sss)(?:$|\?)/
+// CSS modules file pattern - exported for use in plugin hook filters
+// Note: allow query/hash suffix since Vite ids often include them.
+export const CSS_MODULES_REGEX =
+ /\.module\.(css|less|sass|scss|styl|stylus)(?:$|[?#])/i
+
+export function normalizeCssModuleCacheKey(idOrFile: string): string {
+ const baseId = idOrFile.split('?')[0]!.split('#')[0]!
+ return baseId.replace(/\\/g, '/')
+}
// URL params that indicate CSS should not be injected (e.g., ?url, ?inline)
const CSS_SIDE_EFFECT_FREE_PARAMS = ['url', 'inline', 'raw', 'inline-css']
+const VITE_CSS_REGEX = /const\s+__vite__css\s*=\s*["'`]([\s\S]*?)["'`]/
+
+const ESCAPE_CSS_COMMENT_START_REGEX = /\/\*/g
+const ESCAPE_CSS_COMMENT_END_REGEX = /\*\//g
+
function isCssFile(file: string): boolean {
return CSS_FILE_REGEX.test(file)
}
+export function isCssModulesFile(file: string): boolean {
+ return CSS_MODULES_REGEX.test(file)
+}
+
function hasCssSideEffectFreeParam(url: string): boolean {
const queryString = url.split('?')[1]
if (!queryString) return false
@@ -27,9 +46,31 @@ function hasCssSideEffectFreeParam(url: string): boolean {
)
}
+/**
+ * Resolve a file path to a Vite dev server URL.
+ * Files within the root directory use relative paths, files outside use /@fs prefix.
+ */
+function resolveDevUrl(rootDirectory: string, filePath: string): string {
+ const normalizedPath = filePath.replace(/\\/g, '/')
+ const relativePath = path.posix.relative(
+ rootDirectory.replace(/\\/g, '/'),
+ normalizedPath,
+ )
+ const isWithinRoot =
+ !relativePath.startsWith('..') && !path.isAbsolute(relativePath)
+
+ if (isWithinRoot) {
+ return path.posix.join('/', relativePath)
+ }
+ // Files outside root need /@fs prefix
+ return path.posix.join('/@fs', normalizedPath)
+}
+
export interface CollectDevStylesOptions {
viteDevServer: ViteDevServer
entries: ArrayCSS Collection Test - Sass Mixin
++ This page tests that Sass mixins imported in a parent file are available + to subsequent imports during dev mode SSR. +
+ +
+
+ Sass Mixin Applied - Should be centered with purple background
+
+
+