DEV Community: sal lancaster

StyleX + ESLint: When Best Practices Fight Each Other

sal lancaster — Thu, 01 Jan 2026 22:51:42 +0000

or... "How the @stylexjs/sort-keys rule silently breaks responsive styles"

The Setup: Following All the Rules

After solving the StyleX + Vite "Invalid empty selector" mystery, I thought I had StyleX figured out. I was following every documented best practice:

Vite config - using enableMediaQueryOrder: true as recommended in v0.15.0:

// vite.config.js
styleXUnplugin.vite({
  enableMediaQueryOrder: true,
})

ESLint config - using the recommended StyleX plugin rules:

// eslint.config.mjs
rules: {
  "@stylexjs/valid-styles": "error",
  "@stylexjs/sort-keys": "warn",  // Keep styles organized!
}

Responsive styles - using inline strings (learned that lesson) with correct cascade order:

const styles = stylex.create({
  container: {
    padding: {
      default: "2rem",
      "@media (max-width: 768px)": "1.5rem",  // tablet
      "@media (max-width: 640px)": "1rem",    // mobile
    },
  },
});

Everything looked correct. The order was right—larger breakpoints first so smaller ones can override them in the CSS cascade.

The Problem: A Helpful ESLint Warning

Then I ran npm run lint and saw:

warning  StyleX property key "@media (max-width: 640px)"
         should be above "@media (max-width: 768px)"

Being a good developer who trusts their linter, I ran npm run lint -- --fix. ESLint helpfully "fixed" my code:

padding: {
  default: "2rem",
  "@media (max-width: 640px)": "1rem",    // Now first (640 < 768 alphabetically)
  "@media (max-width: 768px)": "1.5rem",  // Now last
},

The Breakage: Mobile Gets Tablet Styles

Here's what happens on a 500px mobile screen:

Both max-width: 640px and max-width: 768px match (500 < 640 < 768)
With enableMediaQueryOrder: true, StyleX makes "later source order wins"
After ESLint sorting, 768px is later in source
Result: Mobile devices get 1.5rem instead of 1rem

The responsive design is now broken, and ESLint told me to do it.

Why This Happens

The @stylexjs/sort-keys rule sorts all object keys alphabetically. For most properties, this is fine—it keeps your styles organized and consistent.

But media query strings sort by their numeric values as strings:

"@media (max-width: 640px)" → "640" comes first
"@media (max-width: 768px)" → "768" comes second

For max-width queries, this is exactly backwards. CSS cascade requires:

Larger breakpoints first (768px)
Smaller breakpoints last (640px) to override

The ESLint rule doesn't understand CSS cascade semantics—it just sorts alphabetically.

The Irony

The StyleX team added enableMediaQueryOrder specifically to handle media query ordering:

"You can now write overlapping media queries in the order you desire, and the compiler will rewrite them so that later queries take precedence over earlier ones."
— StyleX v0.15.0 Release Notes

This feature relies on source order. But the StyleX ESLint plugin's sort-keys rule destroys that source order. The left hand doesn't know what the right hand is doing.

The Workaround

Until this is fixed upstream, you need ESLint disable blocks around responsive properties:

const styles = stylex.create({
  container: {
    /* eslint-disable @stylexjs/sort-keys -- max-width cascade: larger breakpoints first */
    padding: {
      default: "2rem",
      "@media (max-width: 768px)": "1.5rem",
      "@media (max-width: 640px)": "1rem",
    },
    /* eslint-enable @stylexjs/sort-keys */
  },
});

The disable/enable block pattern works because:

// eslint-disable-next-line only affects the next line
The warning is reported on the nested keys, not the property line
Block comments cover everything between them

Key Takeaways

Don't blindly trust --fix — Auto-fixes can break semantic ordering that linters don't understand
Test responsive styles after linting — If you run eslint --fix, verify your breakpoints still work
Document your exceptions — The -- max-width cascade: larger breakpoints first comment explains WHY the rule is disabled
File upstream issues — I've filed an issue requesting the sort-keys rule be media-query-aware

The Fix We Need

The @stylexjs/sort-keys rule should either:

Skip sorting inside media query objects — Detect @media keys and preserve author order
Sort by specificity — Understand that max-width needs descending order, min-width needs ascending
Provide configuration — Let users opt-out for specific patterns

Until then, keep those ESLint disable comments handy.

Related Posts:

Debugging StyleX + Vite: The Mystery of "Invalid empty selector"

GitHub Issue:

#1416 - @stylexjs/sort-keys breaks max-width media query cascade

Debugging StyleX + Vite: The Mystery of "Invalid Empty Selector"

sal lancaster — Thu, 01 Jan 2026 21:36:06 +0000

A methodical journey through debugging a CSS-in-JS race condition when the error message tells you nothing

TL;DR: If you're getting Invalid empty selector errors from StyleX with Vite, and you're using imported constants as computed property keys like [breakpoints.tablet]: '1rem', that's the problem. Replace them with inline strings like "@media (max-width: 768px)": '1rem'. Read on for why this happens and how we figured it out.

Common Error Messages (For Searchability)

If you landed here from a search, you might have seen one of these errors:

Error: Invalid empty selector

Invalid empty selector
unknown file:528:1
    at lightningTransform (node_modules/@stylexjs/unplugin/lib/es/index.mjs)

LightningCSS error: Invalid empty selector

@stylexjs/unplugin: Invalid empty selector

vite stylex Invalid empty selector

Or you might see @media var(--xxx) in your generated CSS, which is the actual cause of the error.

The Error That Told Us Nothing

It started with an error that gave us almost zero useful information:

Error: Invalid empty selector
unknown file:528:1
    at lightningTransform (node_modules/@stylexjs/unplugin/lib/es/index.mjs)
    at processCollectedRulesToCSS (node_modules/@stylexjs/unplugin/lib/es/index.mjs)
    at collectCss (node_modules/@stylexjs/unplugin/lib/es/index.mjs)

No source file. No line in our code. No indication of which style was broken. Just "unknown file" and a line number in generated CSS that we couldn't see.

This is the story of how we tracked down the root cause — and more importantly, the debugging methodology that got us there.

Why This Pattern Should Work

Before diving into debugging, it's important to understand: we weren't doing anything wrong according to StyleX documentation.

StyleX provides stylex.defineConsts() specifically for defining reusable constants like media queries. The official documentation shows this exact pattern:

// This is the documented, recommended approach
import * as stylex from '@stylexjs/stylex';

export const breakpoints = stylex.defineConsts({
  tablet: "@media (max-width: 768px)",
  mobile: "@media (max-width: 640px)",
});

And using these constants as computed property keys is standard JavaScript:

import { breakpoints } from './breakpoints.stylex';

const styles = stylex.create({
  container: {
    padding: {
      default: '2rem',
      [breakpoints.tablet]: '1rem',  // Standard JS computed property
    },
  },
});

This pattern works perfectly in:

Production builds
Webpack dev server
Next.js

But it breaks in Vite dev mode. The question was: why?

The Debugging Journey

Step 1: The Obvious First Attempts

Like any developer, we started with the classics:

# Clear all caches
rm -rf node_modules/.vite
rm -rf node_modules/.cache

# Restart everything
npm run dev

Still broken.

# Nuclear option - reinstall everything
rm -rf node_modules
npm install
npm run dev

Still broken.

At this point, we knew caching wasn't the issue. Time to actually investigate.

Step 2: Understanding the Error Source

The stack trace pointed to lightningTransform in @stylexjs/unplugin. LightningCSS is the CSS parser/transformer that StyleX uses. The error "Invalid empty selector" meant LightningCSS was receiving malformed CSS.

Key insight: The error wasn't in our code — it was in the generated CSS. But we couldn't see what CSS was being generated.

Step 3: Instrumenting the Build Pipeline

Since we couldn't see the generated CSS, we needed to capture it. We added debug instrumentation directly to node_modules/@stylexjs/unplugin/lib/es/index.mjs:

function processCollectedRulesToCSS(rules, options) {
  if (!rules || rules.length === 0) return '';

  const collectedCSS = stylexBabelPlugin.processStylexRules(rules, {
    useCSSLayers: options.useCSSLayers ?? false,
    classNamePrefix: options.classNamePrefix ?? 'x'
  });

  // DEBUG: Always write the CSS so we can see what's being generated
  const fs = require('fs');
  const lines = collectedCSS.split('\n');
  console.log('[StyleX DEBUG] CSS lines:', lines.length);
  fs.writeFileSync(`stylex-debug-${lines.length}.css`, collectedCSS);

  let code;
  try {
    const result = lightningTransform({
      filename: 'styles.css',
      code: Buffer.from(collectedCSS),
      minify: options.minify ?? false,
    });
    code = result.code;
  } catch (error) {
    // CRITICAL: Capture the CSS that caused the failure
    fs.writeFileSync('stylex-debug-FAILED.css', collectedCSS);
    console.log('[StyleX DEBUG] FAILED - check stylex-debug-FAILED.css');
    throw error;
  }

  return code.toString();
}

Why this matters: When debugging build tools, you often can't see the intermediate artifacts. Adding instrumentation to capture them is essential.

Step 4: The First Clue

Running the dev server now produced stylex-debug-FAILED.css. Opening it revealed something strange:

@media var(--xgageza) {
  .x1abc123 {
    padding-left: 1rem;
  }
}

Wait — @media var(--xgageza)? That's a CSS variable reference, not a media query!

The CSS should have been:

@media (max-width: 768px) {
  .x1abc123 {
    padding-left: 1rem;
  }
}

The smoking gun: Something was generating var(--xgageza) where @media (max-width: 768px) should be.

Step 5: The Wrong Hypothesis

Our first hypothesis: "Maybe stylex.defineConsts() is broken. Let's try plain JavaScript objects instead."

// Changed from stylex.defineConsts() to plain object
export const breakpoints = {
  tablet: "@media (max-width: 768px)",
  mobile: "@media (max-width: 640px)",
};

We cleared caches, restarted... still broken.

This was confusing. We had removed stylex.defineConsts() entirely, but the same var(--xxx) pattern was still appearing in the CSS. Why?

Step 6: Following the Evidence

We went back to the failed CSS file and searched for all instances of var(--. There were many, and they all followed a pattern — they appeared where media query strings should be.

Then we looked at how these values were being used, not just how they were defined:

// In roles.stylex.js
const styles = stylex.create({
  heading: {
    paddingBlock: {
      default: '1.5rem',
      [breakpoints.tablet]: '1.25rem',  // <-- Computed property key!
    },
  },
});

The realization: The problem wasn't stylex.defineConsts(). It was using any imported constant as a computed property key ([expression]) in StyleX styles.

Step 7: Confirming the Hypothesis

To confirm, we ran a simple test. We replaced one computed key with an inline string:

// Before (broken)
[breakpoints.tablet]: '1.25rem',

// After (works)
"@media (max-width: 768px)": '1.25rem',

Cleared cache, restarted — that specific style worked.

We replaced another. Worked. Another. Worked.

The pattern was confirmed: inline strings work, imported constants as computed keys don't — but only in Vite dev mode.

Step 8: Understanding Why

Now we understood what was happening, but not why. Here's the race condition:

Vite starts the dev server and begins processing files
StyleX plugin runs and starts collecting CSS from all modules
First CSS collection pass: Some modules are processed before their imports are resolved
The breakpoints module hasn't been fully evaluated yet when styles that import it are being processed
Result: breakpoints.tablet is not the string "@media (max-width: 768px)" — it's an unresolved reference that StyleX converts to a CSS variable placeholder var(--xgageza)
LightningCSS crashes: It receives @media var(--xgageza) which is syntactically invalid

This is a module evaluation order issue specific to Vite's dev server, which uses native ES modules and on-demand compilation. In production builds (bundled) or with Webpack (different module loading), all imports resolve before CSS collection.

The Fix (And Why It's Unsatisfying)

The workaround is to use inline string literals instead of imported constants:

// ❌ Broken in Vite dev mode
const styles = stylex.create({
  container: {
    padding: {
      default: '2rem',
      [breakpoints.tablet]: '1rem',
    },
  },
});

// ✅ Works everywhere
const styles = stylex.create({
  container: {
    padding: {
      default: '2rem',
      "@media (max-width: 768px)": '1rem',
    },
  },
});

This required replacing 54 occurrences across 11 files in our codebase.

Why it's unsatisfying: We're essentially giving up on DRY (Don't Repeat Yourself) for breakpoints. If we ever want to change a breakpoint value, we have to find-and-replace across the entire codebase. This is exactly what constants are supposed to prevent.

Methodology Takeaways

The real value of this experience isn't the specific fix — it's the debugging approach:

1. When the Error Tells You Nothing, Capture Intermediate State

The error message gave us nothing useful. By adding instrumentation to capture the generated CSS, we could finally see what was being produced.

Technique: Add fs.writeFileSync() calls to capture intermediate artifacts in build pipelines.

2. Verify Your Hypothesis Before Acting On It

Our first hypothesis (stylex.defineConsts() is broken) was wrong. If we had rewritten all our breakpoint definitions without testing, we would have wasted time.

Technique: Make one small change, test, observe. Don't batch changes when debugging.

3. Follow the Data, Not Your Assumptions

We assumed the problem was in how values were defined. The actual problem was how they were used. The CSS output told us this — we just had to look at it carefully.

Technique: When your fix doesn't work, question your understanding of the problem, not just try more fixes.

4. Understand the "Works in X, Fails in Y" Pattern

The code worked in production but failed in dev mode. This immediately pointed to a timing/ordering issue, not a logic bug.

Technique: If something works in one environment but not another, focus on what's different about those environments.

5. Document As You Go

We documented our debugging journey, the root cause, and the workaround. Six months from now, when someone (probably us) introduces a [breakpoints.xxx] pattern and sees the same error, the documentation will save hours.

What Should Be Fixed

This is a bug in the Vite + StyleX integration, not in StyleX itself. The pattern we used is documented and works correctly in other environments.

Ideal fixes (any of these would solve it):

StyleX unplugin: Ensure all constant imports are resolved before CSS collection
StyleX unplugin: Detect unresolved var(--xxx) in media query positions and throw a helpful error
StyleX unplugin: Add debug options to capture CSS without patching node_modules
Vite plugin API: Provide hooks for plugins to wait for import resolution

We've filed an issue with the StyleX team including our debugging approach and reproduction case.

Technical Details

Stack: Vite 5.x, StyleX 0.10.x, LightningCSS (via @stylexjs/unplugin)
Environment: Vite dev mode only (production builds work fine)
Root cause: Module evaluation order during CSS collection
Pattern that fails: [importedConstant]: value as computed property keys in stylex.create()

Conclusion

The most frustrating bugs are those where you're doing everything "right" according to the documentation, but something still breaks. These are often environment-specific timing issues that only surface in certain build configurations.

The key to solving them isn't trying random fixes — it's methodically capturing intermediate state until you can see what's actually happening. Once you can see the problem, the solution often becomes obvious.

In our case, @media var(--xgageza) told us exactly what was wrong. We just had to put ourselves in a position to see it.

Have you encountered similar CSS-in-JS race conditions? What's your approach to debugging build tool issues? Share your stories in the comments.

Tags: stylex, vite, css-in-js, debugging, javascript, react, build-tools, lightningcss

Keywords (For Search Engines)

StyleX Invalid empty selector, StyleX Vite error, @stylexjs/unplugin error, LightningCSS Invalid empty selector, stylex.create media query error, StyleX breakpoints not working, StyleX defineConsts Vite, StyleX computed property key, Vite CSS-in-JS race condition, StyleX var(--) in media query, @media var css error, StyleX unplugin lightningTransform error, StyleX Vite dev mode crash, processCollectedRulesToCSS error