fix(react-email): extract media-query variants with tailwindcss 4.3.3+ by dielduarte · Pull Request #3674 · resend/react-email

dielduarte · 2026-07-21T12:50:21Z

Problem

With tailwindcss@4.3.3+, <Tailwind> stops extracting media-query variants (e.g. dark:) into the <head> <style> block. Instead, the conditional value is inlined as the base style and the @media rule is dropped entirely — so dark: colors apply unconditionally and dark-mode switching never happens.

Root cause

Tailwind changed the shape of the CSS it generates for variant utilities between 4.3.2 and 4.3.3.

≤4.3.2 nests the @media inside the class rule:

.dark\:bg-black { @media (prefers-color-scheme: dark) { background-color: #000 } }

≥4.3.3 inverts it — the @media wraps the class rule:

@media (prefers-color-scheme: dark) { .dark\:bg-black { background-color: #000 } }

extractRulesPerClass walks each Rule node in isolation. With the new shape, the inner .dark\:bg-black rule looks like a plain class with a single declaration — no @media, no pseudo — so isRuleInlinable() returns true, the value gets inlined, and the @media wrapper is never emitted.

Fix

Track the chain of enclosing @media/@supports at-rules while walking. When a rule is found inside one, treat it as non-inlinable and normalize it back to the older nested-at-rule shape, so the rest of the pipeline (downlevelForEmailClients, etc.) behaves identically across Tailwind versions. This keeps compatibility going forward rather than capping the supported Tailwind range.

Tests

Added two companion tests to extract-rules-per-class.spec.ts that assert both CSS shapes produce identical classification:

treats @media-nested rules (Tailwind <=4.3.2) as non-inlinable
treats @media-wrapped rules (Tailwind >=4.3.3) as non-inlinable

Both are parsed directly (version-independent) since the repo is pinned to tailwindcss@4.1.18, which only emits the old shape. Full tailwind suite passes (139), typecheck and lint clean.

Summary by cubic

Fixes dropping dark: and other media-query variants with tailwindcss@4.3.3+. Conditional styles are now extracted into the again so dark mode and other media-based variants work as expected.

Bug Fixes
- Track enclosing @media/@supports at-rules while walking CSS and treat inner class rules as non-inlinable.
- Re-nest wrapped rules back to the older nested shape for consistent downstream processing.
- Added tests to ensure both wrapped (≥4.3.3) and nested (≤4.3.2) shapes produce identical extraction.
Refactors
- Centralized NON_INLINABLE_ATRULES in constants.ts and shared it between the extractor and downlevel passes to keep behavior aligned.
- Comments reference issue #3662 for context.

^{Written for commit 8475301. Summary will update on new commits.}

Tailwind 4.3.3 inverted the CSS it generates for variant utilities like `dark:`: instead of nesting the `@media` inside the class rule, it now wraps the class rule with the `@media`. The extractor walked each rule in isolation, so the wrapped rule looked like a plain inlinable class — its conditional value was inlined as the base style and the `@media` rule was never emitted into the <head>. Track the enclosing @media/@supports at-rules while walking and normalize the wrapped shape back to the nested shape the rest of the pipeline expects, so extraction behaves identically across Tailwind versions.

changeset-bot · 2026-07-21T12:50:26Z

🦋 Changeset detected

Latest commit: 8475301

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
react-email	Patch
@react-email/editor	Patch
@react-email/ui	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

vercel · 2026-07-21T12:50:28Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
react-email	Ready	Preview, Comment	Jul 21, 2026 5:54pm
react-email-demo	Ready	Preview, Comment	Jul 21, 2026 5:54pm

pkg-pr-new · 2026-07-21T12:51:57Z

Open in StackBlitz

npm i https://pkg.pr.new/react-email@3674

commit: 8475301

cubic-dev-ai

0 issues found across 2 files (changes from recent commits).

_{Auto-approved: Fix for Tailwind 4.3.3+ CSS shape change in variant extraction; adds normalization and tests.

Re-trigger cubic}

cubic-dev-ai

1 issue found and verified against the latest diff

Confidence score: 3/5

In packages/react-email/src/components/tailwind/utils/css/extract-rules-per-class.ts, stacked conditional variants are still emitted with nested @media/@supports inside a selector instead of fully downleveled CSS, so some email clients that don’t support nesting may drop those styles entirely and render incorrect layouts — flatten nested at-rules during extraction (or add a post-process pass/test for stacked variants) before merging.

Prompt for AI agents (unresolved issues)


Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/react-email/src/components/tailwind/utils/css/extract-rules-per-class.ts">

<violation number="1" location="packages/react-email/src/components/tailwind/utils/css/extract-rules-per-class.ts:115">
P2: Stacked conditional variants still emit CSS nesting instead of fully downleveled email CSS. After the outer wrapper is moved, the inner `@media`/`@supports` remains inside the selector, so clients without CSS nesting support can drop combinations such as responsive dark/supports utilities; make unnesting recursive or repeat it until no nested conditional at-rules remain.</violation>
</file>

_{Reply with feedback, questions, or to request a fix.

Re-trigger cubic}

cubic-dev-ai · 2026-07-21T13:12:19Z

+    // declarations only apply in that condition, so treat the whole thing as
+    // non-inlinable after normalizing it to the nested-at-rule shape.
+    if (enclosingAtRules.length > 0) {
+      const nonInlinablePart = nestAtRulesInsideRule(rule, enclosingAtRules);


P2: Stacked conditional variants still emit CSS nesting instead of fully downleveled email CSS. After the outer wrapper is moved, the inner @media/@supports remains inside the selector, so clients without CSS nesting support can drop combinations such as responsive dark/supports utilities; make unnesting recursive or repeat it until no nested conditional at-rules remain.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/react-email/src/components/tailwind/utils/css/extract-rules-per-class.ts, line 115: <comment>Stacked conditional variants still emit CSS nesting instead of fully downleveled email CSS. After the outer wrapper is moved, the inner `@media`/`@supports` remains inside the selector, so clients without CSS nesting support can drop combinations such as responsive dark/supports utilities; make unnesting recursive or repeat it until no nested conditional at-rules remain.</comment> <file context> @@ -23,52 +77,90 @@ export function extractRulesPerClass(root: CssNode, classes: string[]) { + // declarations only apply in that condition, so treat the whole thing as + // non-inlinable after normalizing it to the nested-at-rule shape. + if (enclosingAtRules.length > 0) { + const nonInlinablePart = nestAtRulesInsideRule(rule, enclosingAtRules); + for (const className of selectorClasses) { + if (classSet.has(className)) { </file context>

unsure if we should fix this in this PR @gabrielmfern it was already an existing behavior, I'm leaning towards not doing it here. thoughts?

yeah it looks like a separate concern, also not sure it makes sense either

if I understand correctly, cubic is just saying that we don't inline non inlinable styles? I mean, there's no way to inline them haha

Dismissed because Cubic found issues in a newer review.

…eries

cubic-dev-ai

0 issues found across 1 file (changes from recent commits).

_{Requires human review: Auto-approval blocked by 1 unresolved issue from previous reviews.

Re-trigger cubic}

Replace the sync-by-comment with a single source of truth in constants.ts, imported by both extract-rules-per-class.ts and downlevel-for-email-clients.ts, so the two passes can't drift out of sync.

cubic-dev-ai

0 issues found across 3 files (changes from recent commits).

_{Requires human review: Auto-approval blocked by 1 unresolved issue from previous reviews.

Re-trigger cubic}

cubic-dev-ai

0 issues found across 2 files (changes from recent commits).

_{Auto-approved: Fixes a bounded bug where Tailwind 4.3.3+ drops media-query variants by normalizing the new wrapped @media shape to the old nested shape; covered by new tests.

Re-trigger cubic}

gabrielmfern · 2026-07-21T17:44:25Z

    `);
  });

+  // Tailwind >=4.3.3 changed the shape of variant utilities: instead of nesting


how about we just mention the issue's url here instead? like a

// see https://...

agree! I am hating all these comments, but trying to keep ones explaining why code exists the code itself it not enough

cubic-dev-ai

0 issues found across 1 file (changes from recent commits).

_{Auto-approved: Fixes a Tailwind version compatibility bug by re-nesting wrapped @media rules, restoring correct dark mode extraction. Bounded, clearly beneficial fix with tests.

Re-trigger cubic}

vercel Bot deployed to Preview – react-email July 21, 2026 12:51 View deployment

vercel Bot deployed to Preview – react-email-demo July 21, 2026 12:52 View deployment

chore: fix biome import order and formatting

56e7022

vercel Bot deployed to Preview – react-email July 21, 2026 12:55 View deployment

vercel Bot deployed to Preview – react-email-demo July 21, 2026 12:55 View deployment

cubic-dev-ai Bot previously approved these changes Jul 21, 2026

View reviewed changes

cubic-dev-ai Bot reviewed Jul 21, 2026

View reviewed changes

docs: note NON_INLINABLE_ATRULES must stay in sync with unnestMediaQu…

1b86be8

…eries

vercel Bot deployed to Preview – react-email July 21, 2026 13:16 View deployment

vercel Bot deployed to Preview – react-email-demo July 21, 2026 13:17 View deployment

cubic-dev-ai Bot reviewed Jul 21, 2026

View reviewed changes

refactor: share NON_INLINABLE_ATRULES between extractor and downlevel

68b6126

Replace the sync-by-comment with a single source of truth in constants.ts, imported by both extract-rules-per-class.ts and downlevel-for-email-clients.ts, so the two passes can't drift out of sync.

vercel Bot deployed to Preview – react-email July 21, 2026 13:24 View deployment

vercel Bot deployed to Preview – react-email-demo July 21, 2026 13:24 View deployment

cubic-dev-ai Bot reviewed Jul 21, 2026

View reviewed changes

docs: trim comments to rationale only

435594f

vercel Bot deployed to Preview – react-email July 21, 2026 17:15 View deployment

vercel Bot deployed to Preview – react-email-demo July 21, 2026 17:15 View deployment

cubic-dev-ai Bot approved these changes Jul 21, 2026

View reviewed changes

dielduarte marked this pull request as ready for review July 21, 2026 17:35

gabrielmfern reviewed Jul 21, 2026

View reviewed changes

Comment thread packages/react-email/src/components/tailwind/utils/css/constants.ts

gabrielmfern reviewed Jul 21, 2026

View reviewed changes

Comment thread packages/react-email/src/components/tailwind/utils/css/downlevel-for-email-clients.ts

gabrielmfern reviewed Jul 21, 2026

View reviewed changes

dielduarte added 2 commits July 21, 2026 14:49

docs: reference issue #3662 instead of inline shape explanation

4a16777

docs: reference issue #3662 in remaining shape-change comments

8475301

vercel Bot deployed to Preview – react-email July 21, 2026 17:53 View deployment

vercel Bot deployed to Preview – react-email-demo July 21, 2026 17:54 View deployment

cubic-dev-ai Bot approved these changes Jul 21, 2026

View reviewed changes

felipefreitag approved these changes Jul 21, 2026

View reviewed changes

Uh oh!

Conversation

dielduarte commented Jul 21, 2026 • edited by cubic-dev-ai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

Root cause

Fix

Tests

Summary by cubic

Uh oh!

changeset-bot Bot commented Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel Bot commented Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pkg-pr-new Bot commented Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cubic-dev-ai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai Bot Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

dielduarte Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gabrielmfern Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

gabrielmfern Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

dielduarte Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

dielduarte commented Jul 21, 2026 •

edited by cubic-dev-ai Bot

Loading

changeset-bot Bot commented Jul 21, 2026 •

edited

Loading

vercel Bot commented Jul 21, 2026 •

edited

Loading

pkg-pr-new Bot commented Jul 21, 2026 •

edited

Loading

dielduarte Jul 21, 2026 •

edited

Loading