react-email 6.3.2 → 6.4.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # react-email
 
+## 6.4.0
+
+### Minor Changes
+
+- ba99365: resolve and strip unresolved `--tw-*` CSS variables in non-inlinable rules so Tailwind media query utilities no longer break Gmail
+
+## 6.3.3
+
 ## 6.3.2
 
 ### Patch Changes

package/dist/cli/index.mjs

@@ -6523,7 +6523,7 @@ const getEmailsDirectoryMetadata = async (absolutePathToEmailsDirectory, keepFil
 //#region package.json
 var package_default = {
 	name: "react-email",
-	version: "6.3.2",
+	version: "6.4.0",
 	description: "A live preview of your emails right in your browser.",
 	bin: { "email": "./dist/cli/index.mjs" },
 	type: "module",

package/dist/index.cjs

@@ -37771,6 +37771,55 @@ function getReactProperty(prop) {
 	return fromDashCaseToCamelCase(modifiedProp);
 }
 //#endregion
+//#region src/components/tailwind/utils/css/strip-empty-tailwind-vars.ts
+/**
+* Tailwind v4 emits variant-stacking idioms like
+*   font-variant-numeric: var(--tw-ordinal,) var(--tw-slashed-zero,) tabular-nums var(--tw-numeric-fraction,)
+*   filter: var(--tw-blur,) var(--tw-brightness,) var(--tw-invert,) ...
+* where each var() has an empty fallback so missing variants collapse to nothing.
+* Tailwind deliberately leaves these variant vars undefined until used, so they
+* stay in the output here and produce unresolvable custom properties in email HTML
+* (no email client supports CSS custom properties reliably). Per the CSS spec
+* (https://www.w3.org/TR/css-variables-1/#using-variables) an empty fallback means
+* "use empty string if the variable is undefined", which is exactly what we want.
+*
+* Scoped to the `--tw-` prefix so any user-authored empty-fallback var() refs
+* are left untouched.
+*
+* Uses post-order traversal so an outer var(--tw-X, var(--tw-Y,)) collapses
+* correctly after the inner var() has been removed.
+*/
+function stripEmptyTailwindVars(node) {
+	walk(node, {
+		visit: "Function",
+		leave(func, funcItem, funcList) {
+			if (func.name !== "var") return;
+			let variableName;
+			walk(func, {
+				visit: "Identifier",
+				enter(identifier) {
+					variableName = identifier.name;
+					return this.break;
+				}
+			});
+			if (!variableName?.startsWith("--tw-")) return;
+			let sawComma = false;
+			let hasFallbackContent = false;
+			func.children.forEach((child) => {
+				if (!sawComma) {
+					if (child.type === "Operator" && child.value === ",") sawComma = true;
+					return;
+				}
+				let childValue = generate(child).trim();
+				if (child.type === "Raw") childValue = childValue.replaceAll(/var\(--tw-[^,()]+,\s*\)/g, "").trim();
+				if (childValue.length > 0) hasFallbackContent = true;
+			});
+			if (!sawComma || hasFallbackContent) return;
+			funcList.remove(funcItem);
+		}
+	});
+}
+//#endregion
 //#region src/components/tailwind/utils/css/unwrap-value.ts
 function unwrapValue(value) {
 	if (value.type === "Value" && value.children.size === 1) return value.children.first ?? value;
@@ -37815,34 +37864,7 @@ function makeInlineStylesFor(inlinableRules, customProperties) {
 			visit: "Declaration",
 			enter(declaration) {
 				if (declaration.property.startsWith("--")) return;
-				walk(declaration.value, {
-					visit: "Function",
-					leave(func, funcItem, funcList) {
-						if (func.name !== "var") return;
-						let variableName;
-						walk(func, {
-							visit: "Identifier",
-							enter(identifier) {
-								variableName = identifier.name;
-								return this.break;
-							}
-						});
-						if (!variableName?.startsWith("--tw-")) return;
-						let sawComma = false;
-						let hasFallbackContent = false;
-						func.children.forEach((child) => {
-							if (!sawComma) {
-								if (child.type === "Operator" && child.value === ",") sawComma = true;
-								return;
-							}
-							let childValue = generate(child).trim();
-							if (child.type === "Raw") childValue = childValue.replaceAll(/var\(--tw-[^,()]+,\s*\)/g, "").trim();
-							if (childValue.length > 0) hasFallbackContent = true;
-						});
-						if (!sawComma || hasFallbackContent) return;
-						funcList.remove(funcItem);
-					}
-				});
+				stripEmptyTailwindVars(declaration.value);
 				styles[getReactProperty(declaration.property)] = generate(declaration.value).trim() + (declaration.important ? "!important" : "");
 			}
 		});
@@ -37933,6 +37955,11 @@ function resolveAllCssVariables(node) {
 				hasReplaced = true;
 				break;
 			}
+			if (use.path[0]?.type === "Block" && use.path[1]?.type === "Atrule" && use.path[2]?.type === "Block" && use.path[3]?.type === "Rule" && definition.path[0]?.type === "Block" && definition.path[1]?.type === "Atrule" && definition.path[2]?.type === "Block" && definition.path[3]?.type === "Rule" && use.path[1].name === definition.path[1].name && (use.path[1].prelude ? definition.path[1].prelude ? generate(use.path[1].prelude) === generate(definition.path[1].prelude) : false : definition.path[1].prelude === null) && doSelectorsIntersect(use.path[3].prelude, definition.path[3].prelude)) {
+				use.declaration.value = parse(generate(use.declaration.value).replaceAll(use.raw, definition.definition), { context: "value" });
+				hasReplaced = true;
+				break;
+			}
 		}
 		if (!hasReplaced && use.fallback) use.declaration.value = parse(generate(use.declaration.value).replaceAll(use.raw, use.fallback), { context: "value" });
 	}
@@ -38498,6 +38525,12 @@ function sanitizeClassName(className) {
 * What it does:
 * 1. Converts all declarations in all rules into important ones
 * 2. Sanitizes class selectors of all non-inlinable rules
+* 3. Removes --tw-* custom property declarations — by this point all CSS
+*    variables have been resolved, so these are dead weight in email HTML.
+* 4. Strips empty-fallback var(--tw-*,) refs that Tailwind v4 emits for
+*    variant-stacking idioms (filter, font-variant-numeric, etc.) — email
+*    clients can't resolve CSS custom properties reliably, so any --tw-*
+*    left as a bare empty-fallback ref would reach the client broken.
 */
 function sanitizeNonInlinableRules(node) {
 	walk(node, {
@@ -38509,8 +38542,13 @@ function sanitizeNonInlinableRules(node) {
 				});
 				walk(rule, {
 					visit: "Declaration",
-					enter(declaration) {
+					enter(declaration, item, list) {
+						if (declaration.property.startsWith("--tw-")) {
+							list.remove(item);
+							return;
+						}
 						declaration.important = true;
+						stripEmptyTailwindVars(declaration.value);
 					}
 				});
 			}

package/dist/index.mjs

@@ -37750,6 +37750,55 @@ function getReactProperty(prop) {
 	return fromDashCaseToCamelCase(modifiedProp);
 }
 //#endregion
+//#region src/components/tailwind/utils/css/strip-empty-tailwind-vars.ts
+/**
+* Tailwind v4 emits variant-stacking idioms like
+*   font-variant-numeric: var(--tw-ordinal,) var(--tw-slashed-zero,) tabular-nums var(--tw-numeric-fraction,)
+*   filter: var(--tw-blur,) var(--tw-brightness,) var(--tw-invert,) ...
+* where each var() has an empty fallback so missing variants collapse to nothing.
+* Tailwind deliberately leaves these variant vars undefined until used, so they
+* stay in the output here and produce unresolvable custom properties in email HTML
+* (no email client supports CSS custom properties reliably). Per the CSS spec
+* (https://www.w3.org/TR/css-variables-1/#using-variables) an empty fallback means
+* "use empty string if the variable is undefined", which is exactly what we want.
+*
+* Scoped to the `--tw-` prefix so any user-authored empty-fallback var() refs
+* are left untouched.
+*
+* Uses post-order traversal so an outer var(--tw-X, var(--tw-Y,)) collapses
+* correctly after the inner var() has been removed.
+*/
+function stripEmptyTailwindVars(node) {
+	walk(node, {
+		visit: "Function",
+		leave(func, funcItem, funcList) {
+			if (func.name !== "var") return;
+			let variableName;
+			walk(func, {
+				visit: "Identifier",
+				enter(identifier) {
+					variableName = identifier.name;
+					return this.break;
+				}
+			});
+			if (!variableName?.startsWith("--tw-")) return;
+			let sawComma = false;
+			let hasFallbackContent = false;
+			func.children.forEach((child) => {
+				if (!sawComma) {
+					if (child.type === "Operator" && child.value === ",") sawComma = true;
+					return;
+				}
+				let childValue = generate(child).trim();
+				if (child.type === "Raw") childValue = childValue.replaceAll(/var\(--tw-[^,()]+,\s*\)/g, "").trim();
+				if (childValue.length > 0) hasFallbackContent = true;
+			});
+			if (!sawComma || hasFallbackContent) return;
+			funcList.remove(funcItem);
+		}
+	});
+}
+//#endregion
 //#region src/components/tailwind/utils/css/unwrap-value.ts
 function unwrapValue(value) {
 	if (value.type === "Value" && value.children.size === 1) return value.children.first ?? value;
@@ -37794,34 +37843,7 @@ function makeInlineStylesFor(inlinableRules, customProperties) {
 			visit: "Declaration",
 			enter(declaration) {
 				if (declaration.property.startsWith("--")) return;
-				walk(declaration.value, {
-					visit: "Function",
-					leave(func, funcItem, funcList) {
-						if (func.name !== "var") return;
-						let variableName;
-						walk(func, {
-							visit: "Identifier",
-							enter(identifier) {
-								variableName = identifier.name;
-								return this.break;
-							}
-						});
-						if (!variableName?.startsWith("--tw-")) return;
-						let sawComma = false;
-						let hasFallbackContent = false;
-						func.children.forEach((child) => {
-							if (!sawComma) {
-								if (child.type === "Operator" && child.value === ",") sawComma = true;
-								return;
-							}
-							let childValue = generate(child).trim();
-							if (child.type === "Raw") childValue = childValue.replaceAll(/var\(--tw-[^,()]+,\s*\)/g, "").trim();
-							if (childValue.length > 0) hasFallbackContent = true;
-						});
-						if (!sawComma || hasFallbackContent) return;
-						funcList.remove(funcItem);
-					}
-				});
+				stripEmptyTailwindVars(declaration.value);
 				styles[getReactProperty(declaration.property)] = generate(declaration.value).trim() + (declaration.important ? "!important" : "");
 			}
 		});
@@ -37912,6 +37934,11 @@ function resolveAllCssVariables(node) {
 				hasReplaced = true;
 				break;
 			}
+			if (use.path[0]?.type === "Block" && use.path[1]?.type === "Atrule" && use.path[2]?.type === "Block" && use.path[3]?.type === "Rule" && definition.path[0]?.type === "Block" && definition.path[1]?.type === "Atrule" && definition.path[2]?.type === "Block" && definition.path[3]?.type === "Rule" && use.path[1].name === definition.path[1].name && (use.path[1].prelude ? definition.path[1].prelude ? generate(use.path[1].prelude) === generate(definition.path[1].prelude) : false : definition.path[1].prelude === null) && doSelectorsIntersect(use.path[3].prelude, definition.path[3].prelude)) {
+				use.declaration.value = parse(generate(use.declaration.value).replaceAll(use.raw, definition.definition), { context: "value" });
+				hasReplaced = true;
+				break;
+			}
 		}
 		if (!hasReplaced && use.fallback) use.declaration.value = parse(generate(use.declaration.value).replaceAll(use.raw, use.fallback), { context: "value" });
 	}
@@ -38477,6 +38504,12 @@ function sanitizeClassName(className) {
 * What it does:
 * 1. Converts all declarations in all rules into important ones
 * 2. Sanitizes class selectors of all non-inlinable rules
+* 3. Removes --tw-* custom property declarations — by this point all CSS
+*    variables have been resolved, so these are dead weight in email HTML.
+* 4. Strips empty-fallback var(--tw-*,) refs that Tailwind v4 emits for
+*    variant-stacking idioms (filter, font-variant-numeric, etc.) — email
+*    clients can't resolve CSS custom properties reliably, so any --tw-*
+*    left as a bare empty-fallback ref would reach the client broken.
 */
 function sanitizeNonInlinableRules(node) {
 	walk(node, {
@@ -38488,8 +38521,13 @@ function sanitizeNonInlinableRules(node) {
 				});
 				walk(rule, {
 					visit: "Declaration",
-					enter(declaration) {
+					enter(declaration, item, list) {
+						if (declaration.property.startsWith("--tw-")) {
+							list.remove(item);
+							return;
+						}
 						declaration.important = true;
+						stripEmptyTailwindVars(declaration.value);
 					}
 				});
 			}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-email",
-  "version": "6.3.2",
+  "version": "6.4.0",
   "description": "A live preview of your emails right in your browser.",
   "bin": {
     "email": "./dist/cli/index.mjs"

package/src/components/tailwind/utils/css/make-inline-styles-for.ts

@@ -1,6 +1,7 @@
 import { type CssNode, type Declaration, generate, walk } from 'css-tree';
 import { getReactProperty } from '../compatibility/get-react-property.js';
 import type { CustomProperties } from './get-custom-properties.js';
+import { stripEmptyTailwindVars } from './strip-empty-tailwind-vars.js';
 import { unwrapValue } from './unwrap-value.js';
 
 export function makeInlineStylesFor(
@@ -59,68 +60,7 @@ export function makeInlineStylesFor(
         if (declaration.property.startsWith('--')) {
           return;
         }
-        // Tailwind v4 emits variant-stacking idioms like
-        //   font-variant-numeric: var(--tw-ordinal,) var(--tw-slashed-zero,) tabular-nums var(--tw-numeric-fraction,)
-        // where each var() has an empty fallback so missing variants collapse to nothing.
-        // The walker above replaces var() calls with an initialValue when one is defined,
-        // but Tailwind deliberately leaves these variant vars undefined until used, so they
-        // stay in the output here and produce unresolvable custom properties in email HTML
-        // (no email client supports CSS custom properties reliably). Per the CSS spec
-        // (https://www.w3.org/TR/css-variables-1/#using-variables) an empty fallback means
-        // "use empty string if the variable is undefined", which is exactly what we want at
-        // inline-style time.
-        //
-        // Scoped to the `--tw-` prefix so any user-authored empty-fallback var() refs
-        // (even ones used inside tailwind utilities) are left untouched.
-        walk(declaration.value, {
-          visit: 'Function',
-          leave(func, funcItem, funcList) {
-            if (func.name !== 'var') {
-              return;
-            }
-
-            let variableName: string | undefined;
-            walk(func, {
-              visit: 'Identifier',
-              enter(identifier) {
-                variableName = identifier.name;
-                return this.break;
-              },
-            });
-            if (!variableName?.startsWith('--tw-')) {
-              return;
-            }
-
-            let sawComma = false;
-            let hasFallbackContent = false;
-            func.children.forEach((child) => {
-              if (!sawComma) {
-                if (child.type === 'Operator' && child.value === ',') {
-                  sawComma = true;
-                }
-                return;
-              }
-
-              let childValue = generate(child).trim();
-              if (child.type === 'Raw') {
-                const emptyTailwindVarPattern = /var\(--tw-[^,()]+,\s*\)/g;
-                childValue = childValue
-                  .replaceAll(emptyTailwindVarPattern, '')
-                  .trim();
-              }
-
-              if (childValue.length > 0) {
-                hasFallbackContent = true;
-              }
-            });
-
-            if (!sawComma || hasFallbackContent) {
-              return;
-            }
-
-            funcList.remove(funcItem);
-          },
-        });
+        stripEmptyTailwindVars(declaration.value);
 
         styles[getReactProperty(declaration.property)] =
           generate(declaration.value).trim() +

package/src/components/tailwind/utils/css/resolve-all-css-variables.spec.ts

@@ -237,6 +237,22 @@ describe('resolveAllCSSVariables', () => {
     );
   });
 
+  it('does not leak variables across sibling nested at-rules within the same rule', () => {
+    const root = parse(`.print_invert {
+  @media print {
+    --tw-invert: invert(100%);
+    filter: var(--tw-invert, none);
+  }
+  @media screen {
+    filter: var(--tw-invert, none);
+  }
+}`);
+    resolveAllCssVariables(root);
+    expect(generate(root)).toMatchInlineSnapshot(
+      `".print_invert{@media print{--tw-invert: invert(100%);filter:invert(100%)}@media screen{filter:none}}"`,
+    );
+  });
+
   it('handles selectors with asterisks in attribute selectors and pseudo-functions', () => {
     const root = parse(`* {
   --global-color: red;

package/src/components/tailwind/utils/css/resolve-all-css-variables.ts

@@ -187,6 +187,43 @@ export function resolveAllCssVariables(node: CssNode) {
         hasReplaced = true;
         break;
       }
+
+      // Both use and definition live inside the same nested @media (or other
+      // at-rule) block of the same rule — e.g. Tailwind v4's
+      //   .print_invert { @media print { --tw-invert: invert(100%); filter: var(--tw-invert,) ... } }
+      // The previous two checks only cover a Rule directly containing the
+      // declaration; this one covers Rule → Block → Atrule → Block → Declaration
+      // on both sides.
+      if (
+        use.path[0]?.type === 'Block' &&
+        use.path[1]?.type === 'Atrule' &&
+        use.path[2]?.type === 'Block' &&
+        use.path[3]?.type === 'Rule' &&
+        definition.path[0]?.type === 'Block' &&
+        definition.path[1]?.type === 'Atrule' &&
+        definition.path[2]?.type === 'Block' &&
+        definition.path[3]?.type === 'Rule' &&
+        use.path[1].name === definition.path[1].name &&
+        (use.path[1].prelude
+          ? definition.path[1].prelude
+            ? generate(use.path[1].prelude) ===
+              generate(definition.path[1].prelude)
+            : false
+          : definition.path[1].prelude === null) &&
+        doSelectorsIntersect(use.path[3].prelude, definition.path[3].prelude)
+      ) {
+        use.declaration.value = parse(
+          generate(use.declaration.value).replaceAll(
+            use.raw,
+            definition.definition,
+          ),
+          {
+            context: 'value',
+          },
+        ) as Raw | Value;
+        hasReplaced = true;
+        break;
+      }
     }
 
     if (!hasReplaced && use.fallback) {

package/src/components/tailwind/utils/css/sanitize-non-inlinable-rules.spec.ts

@@ -1,4 +1,5 @@
 import { generate } from 'css-tree';
+import { sanitizeStyleSheet } from '../../sanitize-stylesheet.js';
 import { setupTailwind } from '../tailwindcss/setup-tailwind.js';
 import { sanitizeNonInlinableRules } from './sanitize-non-inlinable-rules.js';
 
@@ -27,7 +28,27 @@ describe('sanitizeNonInlinableRules()', () => {
 
     sanitizeNonInlinableRules(stylesheet);
     expect(generate(stylesheet)).toMatchInlineSnapshot(
-      `"/*! tailwindcss v4.1.18 | MIT License | https://tailwindcss.com */@layer theme,base,components,utilities;@layer theme{:root,:host{--color-sky-600: oklch(58.8% 0.158 241.966)!important;--color-gray-100: oklch(96.7% 0.003 264.542)!important}}@layer utilities{.hover_text-sky-600{&:hover{@media (hover:hover){color:var(--color-sky-600)!important}}}.sm_focus_outline-none{@media (width>=40rem){&:focus{--tw-outline-style: none!important;outline-style:none!important}}}.md_hover_bg-gray-100{@media (width>=48rem){&:hover{@media (hover:hover){background-color:var(--color-gray-100)!important}}}}.lg_focus_underline{@media (width>=64rem){&:focus{text-decoration-line:underline!important}}}}"`,
+      `"/*! tailwindcss v4.1.18 | MIT License | https://tailwindcss.com */@layer theme,base,components,utilities;@layer theme{:root,:host{--color-sky-600: oklch(58.8% 0.158 241.966)!important;--color-gray-100: oklch(96.7% 0.003 264.542)!important}}@layer utilities{.hover_text-sky-600{&:hover{@media (hover:hover){color:var(--color-sky-600)!important}}}.sm_focus_outline-none{@media (width>=40rem){&:focus{outline-style:none!important}}}.md_hover_bg-gray-100{@media (width>=48rem){&:hover{@media (hover:hover){background-color:var(--color-gray-100)!important}}}}.lg_focus_underline{@media (width>=64rem){&:focus{text-decoration-line:underline!important}}}}"`,
+    );
+  });
+
+  it('strips Tailwind v4 variant-stacking var() refs with empty fallbacks inside print: media queries', async () => {
+    // Mirrors the inline-style behavior asserted in make-inline-styles-for.spec.ts.
+    // `print:invert` compiles to a filter value that is a chain of var(--tw-...,)
+    // with empty fallbacks. After resolveAllCssVariables the filter is concrete;
+    // sanitizeNonInlinableRules then drops the leftover --tw-* declarations and
+    // any remaining empty-fallback var() refs.
+    const tailwind = await setupTailwind({});
+    tailwind.addUtilities(['md:block', 'print:invert']);
+    const stylesheet = tailwind.getStyleSheet();
+
+    sanitizeStyleSheet(stylesheet);
+    sanitizeNonInlinableRules(stylesheet);
+    const result = generate(stylesheet);
+
+    expect(result).not.toMatch(/var\(--tw-[^,()]+,\s*\)/);
+    expect(result).toMatchInlineSnapshot(
+      `"/*! tailwindcss v4.1.18 | MIT License | https://tailwindcss.com */@layer theme,base,components,utilities;@layer utilities{.md_block{@media (width>=48rem){display:block!important}}.print_invert{@media print{filter:invert(100%)!important}}}@property --tw-blur{syntax:"*";inherits:false}@property --tw-brightness{syntax:"*";inherits:false}@property --tw-contrast{syntax:"*";inherits:false}@property --tw-grayscale{syntax:"*";inherits:false}@property --tw-hue-rotate{syntax:"*";inherits:false}@property --tw-invert{syntax:"*";inherits:false}@property --tw-opacity{syntax:"*";inherits:false}@property --tw-saturate{syntax:"*";inherits:false}@property --tw-sepia{syntax:"*";inherits:false}@property --tw-drop-shadow{syntax:"*";inherits:false}@property --tw-drop-shadow-color{syntax:"*";inherits:false}@property --tw-drop-shadow-alpha{syntax:"<percentage>";inherits:false;initial-value:100%}@property --tw-drop-shadow-size{syntax:"*";inherits:false}"`,
     );
   });
 

package/src/components/tailwind/utils/css/sanitize-non-inlinable-rules.ts

@@ -1,6 +1,7 @@
 import { type CssNode, string, walk } from 'css-tree';
 import { sanitizeClassName } from '../compatibility/sanitize-class-name.js';
 import { isRuleInlinable } from './is-rule-inlinable.js';
+import { stripEmptyTailwindVars } from './strip-empty-tailwind-vars.js';
 
 /**
  * This function goes through a few steps to ensure the best email client support and
@@ -10,6 +11,12 @@ import { isRuleInlinable } from './is-rule-inlinable.js';
  * What it does:
  * 1. Converts all declarations in all rules into important ones
  * 2. Sanitizes class selectors of all non-inlinable rules
+ * 3. Removes --tw-* custom property declarations — by this point all CSS
+ *    variables have been resolved, so these are dead weight in email HTML.
+ * 4. Strips empty-fallback var(--tw-*,) refs that Tailwind v4 emits for
+ *    variant-stacking idioms (filter, font-variant-numeric, etc.) — email
+ *    clients can't resolve CSS custom properties reliably, so any --tw-*
+ *    left as a bare empty-fallback ref would reach the client broken.
  */
 export function sanitizeNonInlinableRules(node: CssNode) {
   walk(node, {
@@ -25,8 +32,14 @@ export function sanitizeNonInlinableRules(node: CssNode) {
 
         walk(rule, {
           visit: 'Declaration',
-          enter(declaration) {
+          enter(declaration, item, list) {
+            if (declaration.property.startsWith('--tw-')) {
+              list.remove(item);
+              return;
+            }
+
             declaration.important = true;
+            stripEmptyTailwindVars(declaration.value);
           },
         });
       }

package/src/components/tailwind/utils/css/strip-empty-tailwind-vars.spec.ts

@@ -0,0 +1,128 @@
+import {
+  type Atrule,
+  type Declaration,
+  generate,
+  parse,
+  type Rule,
+  type StyleSheet,
+  walk,
+} from 'css-tree';
+import { sanitizeStyleSheet } from '../../sanitize-stylesheet.js';
+import { setupTailwind } from '../tailwindcss/setup-tailwind.js';
+import { isRuleInlinable } from './is-rule-inlinable.js';
+import { sanitizeNonInlinableRules } from './sanitize-non-inlinable-rules.js';
+import { stripEmptyTailwindVars } from './strip-empty-tailwind-vars.js';
+
+describe('stripEmptyTailwindVars()', () => {
+  it('removes empty-fallback var(--tw-*,) refs from declaration values', () => {
+    const stylesheet = parse(`
+      .tabular-nums {
+        font-variant-numeric: var(--tw-ordinal,) var(--tw-slashed-zero,) tabular-nums var(--tw-numeric-fraction,);
+      }
+    `) as StyleSheet;
+
+    const rule = stylesheet.children.first as Rule;
+    const declaration = rule.block.children.first as Declaration;
+    stripEmptyTailwindVars(declaration.value);
+
+    expect(generate(declaration.value)).toBe('tabular-nums');
+  });
+
+  it('does not remove var() refs with non-empty fallbacks or non --tw- names', () => {
+    const stylesheet = parse(`
+      .thing {
+        line-height: var(--tw-leading, var(--text-lg--line-height));
+        color: var(--my-color,);
+      }
+    `) as StyleSheet;
+
+    const rule = stylesheet.children.first as Rule;
+    const leading = rule.block.children.first as Declaration;
+    const color = rule.block.children.last as Declaration;
+
+    stripEmptyTailwindVars(leading.value);
+    stripEmptyTailwindVars(color.value);
+
+    expect(generate(leading.value)).toBe(
+      'var(--tw-leading, var(--text-lg--line-height))',
+    );
+    expect(generate(color.value)).toBe('var(--my-color,)');
+  });
+
+  it('does not remove --tw-* custom property declarations (only var() usages in values)', () => {
+    const stylesheet = parse(`
+      .print_border-solid {
+        @media print {
+          --tw-border-style: solid;
+          border-style: var(--tw-border-style,);
+        }
+      }
+    `) as StyleSheet;
+
+    const rule = stylesheet.children.first as Rule;
+    const atrule = rule.block.children.first as Atrule;
+    const twDeclaration = atrule.block!.children.first as Declaration;
+    const borderDeclaration = atrule.block!.children.last as Declaration;
+
+    stripEmptyTailwindVars(borderDeclaration.value);
+
+    expect(twDeclaration.property).toBe('--tw-border-style');
+    expect(generate(twDeclaration.value).trim()).toBe('solid');
+    expect(generate(borderDeclaration.value)).toBe('');
+    expect(generate(stylesheet)).toContain('--tw-border-style: solid');
+  });
+});
+
+describe('stripEmptyTailwindVars() with non-inlinable print: rules', () => {
+  it('print:border-solid still leaves --tw-* declarations if only stripEmptyTailwindVars runs', async () => {
+    const tailwind = await setupTailwind({});
+    tailwind.addUtilities(['print:border-solid']);
+    const stylesheet = tailwind.getStyleSheet();
+
+    sanitizeStyleSheet(stylesheet);
+
+    walkDeclarationsInNonInlinableRules(stylesheet, (declaration) => {
+      stripEmptyTailwindVars(declaration.value);
+    });
+
+    const result = generate(stylesheet);
+
+    expect(result).not.toMatch(/var\(--tw-[^,()]+,\s*\)/);
+    expect(result).toMatch(/--tw-[^:]+:/);
+  });
+
+  it('print:border-solid is clean after sanitizeNonInlinableRules removes resolved --tw-* declarations', async () => {
+    const tailwind = await setupTailwind({});
+    tailwind.addUtilities(['print:border-solid']);
+    const stylesheet = tailwind.getStyleSheet();
+
+    sanitizeStyleSheet(stylesheet);
+    sanitizeNonInlinableRules(stylesheet);
+    const result = generate(stylesheet);
+
+    expect(result).not.toMatch(/var\(--tw-[^,()]+,\s*\)/);
+    expect(result).not.toMatch(/--tw-[^:]+:/);
+    expect(result).toMatchInlineSnapshot(
+      `"/*! tailwindcss v4.1.18 | MIT License | https://tailwindcss.com */@layer theme,base,components,utilities;@layer utilities{.print_border-solid{@media print{border-style:solid!important}}}"`,
+    );
+  });
+});
+
+function walkDeclarationsInNonInlinableRules(
+  node: StyleSheet,
+  onDeclaration: (declaration: Declaration) => void,
+) {
+  walk(node, {
+    visit: 'Rule',
+    enter(rule) {
+      if (!isRuleInlinable(rule)) {
+        walk(rule, {
+          visit: 'Declaration',
+          enter(declaration) {
+            onDeclaration(declaration);
+          },
+        });
+      }
+    },
+  });
+}

package/src/components/tailwind/utils/css/strip-empty-tailwind-vars.ts

@@ -0,0 +1,70 @@
+import { type CssNode, generate, walk } from 'css-tree';
+
+/**
+ * Tailwind v4 emits variant-stacking idioms like
+ *   font-variant-numeric: var(--tw-ordinal,) var(--tw-slashed-zero,) tabular-nums var(--tw-numeric-fraction,)
+ *   filter: var(--tw-blur,) var(--tw-brightness,) var(--tw-invert,) ...
+ * where each var() has an empty fallback so missing variants collapse to nothing.
+ * Tailwind deliberately leaves these variant vars undefined until used, so they
+ * stay in the output here and produce unresolvable custom properties in email HTML
+ * (no email client supports CSS custom properties reliably). Per the CSS spec
+ * (https://www.w3.org/TR/css-variables-1/#using-variables) an empty fallback means
+ * "use empty string if the variable is undefined", which is exactly what we want.
+ *
+ * Scoped to the `--tw-` prefix so any user-authored empty-fallback var() refs
+ * are left untouched.
+ *
+ * Uses post-order traversal so an outer var(--tw-X, var(--tw-Y,)) collapses
+ * correctly after the inner var() has been removed.
+ */
+export function stripEmptyTailwindVars(node: CssNode) {
+  walk(node, {
+    visit: 'Function',
+    leave(func, funcItem, funcList) {
+      if (func.name !== 'var') {
+        return;
+      }
+
+      let variableName: string | undefined;
+      walk(func, {
+        visit: 'Identifier',
+        enter(identifier) {
+          variableName = identifier.name;
+          return this.break;
+        },
+      });
+      if (!variableName?.startsWith('--tw-')) {
+        return;
+      }
+
+      let sawComma = false;
+      let hasFallbackContent = false;
+      func.children.forEach((child) => {
+        if (!sawComma) {
+          if (child.type === 'Operator' && child.value === ',') {
+            sawComma = true;
+          }
+          return;
+        }
+
+        let childValue = generate(child).trim();
+        if (child.type === 'Raw') {
+          const emptyTailwindVarPattern = /var\(--tw-[^,()]+,\s*\)/g;
+          childValue = childValue
+            .replaceAll(emptyTailwindVarPattern, '')
+            .trim();
+        }
+
+        if (childValue.length > 0) {
+          hasFallbackContent = true;
+        }
+      });
+
+      if (!sawComma || hasFallbackContent) {
+        return;
+      }
+
+      funcList.remove(funcItem);
+    },
+  });
+}

package/tsconfig.json

@@ -35,5 +35,10 @@
     "outDir": "dist"
   },
   "include": ["src/**/*.ts", "src/**/*.tsx"],
-  "exclude": ["dist", "node_modules"]
+  "exclude": [
+    "dist",
+    "node_modules",
+    "src/cli/utils/preview/hot-reloading/test",
+    "src/components/tailwind/e2e"
+  ]
 }