[eslint-plugin] Add transform-media-query rule and soft validation config #1301

Prakshal-Jain · 2025-10-27T18:54:37Z

What changed / motivation?

Introducing a new ESLint rule stylex-validate-media-queries that validates media query syntax in StyleX declarations. The motivation is to provide early feedback to developers about invalid media queries during development and flag when media query order cannot be enforced.

Key Changes:

Added stylex-validate-media-queries rule that checks media query syntax in stylex.create() and stylex.createTheme() calls
Implemented a softValidation option in the babel plugin that allows media query validation to be handled by ESLint instead of failing at build time
The rule validates:
- Media query syntax and structure
- Valid media types (screen, print, all, etc.)
- Valid media features (width, height, orientation, etc.)
- Proper use of logical operators (and, or, not)
- Range syntax and value formats
Developer Experience: Provides clear, actionable error messages with specific guidance on what's wrong and how to fix it

Linked PR/Issues

Fixes #1200

Tests

Added test suite covering valid and invalid media query patterns
Tests include edge cases like nested conditions, range syntax, and various media features
All existing tests continue to pass

Configuration

The ESLint rule can be enabled in .eslintrc:

{
  "rules": {
    "@stylexjs/stylex-validate-media-queries": "error"
  }
}

The babel plugin's soft validation mode can be enabled via:

{
  plugins: [
    ['@stylexjs/babel-plugin', { 
      softValidation: ['mediaQueries'] 
    }]
  ]
}

Breaking Changes

None - this is an opt-in feature that doesn't affect existing functionality.

Pre-flight checklist

I have read the contributing guidelines
Contribution Guidelines
Performed a self-review of my code

Prakshal-Jain · 2025-10-27T18:55:49Z

packages/@stylexjs/eslint-plugin/src/stylex-validate-media-queries.js

+let lastMediaQueryWinsTransform = null;
+try {
+  // $FlowFixMe Dynamic import for style-value-parser since it might not be available in all environments
+  const styleValueParser = require('style-value-parser');


@mellyeliu Not sure if the import statement is safe here?

hmm why cjs here? let's use esm import instead

github-actions · 2025-10-27T18:58:48Z

workflow: benchmarks/perf

Comparison of performance test results, measured in operations per second. Larger is better.

benchmarks@0.16.2 compare
node ./compare.js /tmp/tmp.lUTBpjgZaP /tmp/tmp.GOin9WNhhx

Results	Base	Patch	Ratio

babel-plugin: stylex.create
· basic create	636	645	1.01	+
· complex create	201	193	0.96	-

babel-plugin: stylex.createTheme
· basic themes	460	454	0.99	-
· complex themes	43	43	1.00

github-actions · 2025-10-27T18:59:00Z

workflow: benchmarks/size

Comparison of minified (terser) and compressed (brotli) size results, measured in bytes. Smaller is better.

benchmarks@0.16.2 compare
node ./compare.js /tmp/tmp.8nDJGbZudP /tmp/tmp.X5kQPrbHWz

Results	Base	Patch	Ratio

@stylexjs/stylex/lib/cjs/stylex.js
· compressed	1,282	1,282	1.00
· minified	4,025	4,025	1.00

@stylexjs/stylex/lib/cjs/inject.js
· compressed	1,223	1,223	1.00
· minified	3,216	3,216	1.00

benchmarks/size/.build/bundle.js
· compressed	496,650	496,650	1.00
· minified	4,847,840	4,847,840	1.00

benchmarks/size/.build/stylex.css
· compressed	99,853	99,853	1.00
· minified	747,541	747,541	1.00

mellyeliu

Looks good overall. Couple of nits and suggestions to start out

mellyeliu · 2025-10-27T19:18:00Z

packages/@stylexjs/eslint-plugin/src/stylex-validate-media-queries.js

+    type: 'problem',
+    docs: {
+      description:
+        'Warn when media query syntax may not be correctly ordered due to parser limitations',


Suggested change

'Warn when media query syntax may not be correctly ordered due to parser limitations',

'Warn when media query syntax order is not properly enforced due to invalid media query syntax or parser limitations',

mellyeliu · 2025-10-27T19:19:15Z

packages/@stylexjs/eslint-plugin/src/stylex-transform-media-queries.js

+        }
+
+        if (prop.computed) {
+          continue;


this is fine for now, we'll eventually need to think of how to handle defineConsts computed keys here though

mellyeliu · 2025-10-27T19:22:08Z

packages/@stylexjs/babel-plugin/src/shared/preprocess-rules/flatten-raw-style-obj.js

+        `StyleX: ${messages.INVALID_MEDIA_QUERY_SYNTAX}\n` +
+          'Media query order will not be respected. ' +
+          'This could be due to invalid media query syntax or unsupported edge cases in style-value-parser.\n' +
+          `Error: ${error.message || error}`,


can we validate that this error message contains the erroring media query?

mellyeliu · 2025-10-27T19:22:51Z

packages/@stylexjs/babel-plugin/src/shared/preprocess-rules/flatten-raw-style-obj.js

-    throw new Error(messages.INVALID_MEDIA_QUERY_SYNTAX);
+    if (options.softMediaQueryValidation) {
+      console.warn(
+        `StyleX: ${messages.INVALID_MEDIA_QUERY_SYNTAX}\n` +


probably don't need to "StyleX: " prefix here

mellyeliu · 2025-10-27T19:23:03Z

packages/@stylexjs/babel-plugin/src/utils/state-manager.js

+      z.logAndDefault(
+        z.boolean(),
+        options.softMediaQueryValidation ?? false,
+        false,


let's make this true for now

mellyeliu · 2025-10-27T19:25:00Z

packages/@stylexjs/eslint-plugin/__tests__/stylex-transform-media-queries-test.js

+      const styles = stylex.create({
+        main: {
+          color: {
+            '@media (min-width: 768px)': 'blue',


we require a default with every contextual style:

Suggested change

'@media (min-width: 768px)': 'blue',

default: 'yellow',

'@media (min-width: 768px)': 'blue',

mellyeliu · 2025-10-27T19:26:40Z

packages/@stylexjs/eslint-plugin/__tests__/stylex-validate-media-queries-test.js

+    `,
+      errors: [
+        {
+          message: /Media query order may not be respected/,


Curious why the rest of the error is not showing up here? Seems out of sync with the rule file itself

mellyeliu · 2025-10-27T19:27:43Z

packages/@stylexjs/eslint-plugin/src/index.js

 import sortKeys from './stylex-sort-keys';
 import validShorthands from './stylex-valid-shorthands';
 import validStyles from './stylex-valid-styles';
+import validateMediaQueries from './stylex-validate-media-queries';


Let's call this transform-media-queries or something similar

mellyeliu · 2025-10-27T19:39:23Z

packages/@stylexjs/eslint-plugin/package.json

    "micromatch": "^4.0.5",
-    "postcss-value-parser": "^4.2.0"
+    "postcss-value-parser": "^4.2.0",
+    "style-value-parser": "*"


I believe style-value-parser is already added to workspaces at the root level so it's inlined instead, as it's a private package, see: https://github.com/facebook/stylex/blob/main/package.json#L20

… issue

Add media queries validation eslint rule with soft validation support

698e908

Prakshal-Jain requested review from Jta26, ezzak, mellyeliu, necolas, nmn and vincentriemer as code owners October 27, 2025 18:54

meta-cla bot added the CLA Signed This label is managed by the Facebook bot. Authors need to sign the CLA before a PR can be reviewed. label Oct 27, 2025

Prakshal-Jain commented Oct 27, 2025

View reviewed changes

Remove FlowFixMe and use static import for style-value-parser

3abe112

vercel bot deployed to Preview October 27, 2025 19:01 View deployment

Fix Flow type errors by removing unnecessary null checks

004f228

vercel bot deployed to Preview October 27, 2025 19:07 View deployment

mellyeliu reviewed Oct 27, 2025

View reviewed changes

mellyeliu changed the title ~~Add media queries validation eslint rule with soft validation support~~ [eslint-plugin] Add transform-media-query rule and soft validation config Oct 27, 2025

fixed the stylex-transform-media-queries-test and npm run lint:report…

2b1ecd3

… issue

vercel bot deployed to Preview November 4, 2025 00:33 View deployment

	'Warn when media query syntax may not be correctly ordered due to parser limitations',
	'Warn when media query syntax order is not properly enforced due to invalid media query syntax or parser limitations',

	'@media (min-width: 768px)': 'blue',
	default: 'yellow',
	'@media (min-width: 768px)': 'blue',

[eslint-plugin] Add transform-media-query rule and soft validation config #1301

Are you sure you want to change the base?

[eslint-plugin] Add transform-media-query rule and soft validation config #1301

Uh oh!

Conversation

Prakshal-Jain commented Oct 27, 2025 • edited by mellyeliu Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What changed / motivation?

Key Changes:

Linked PR/Issues

Tests

Configuration

Breaking Changes

Pre-flight checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Oct 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

workflow: benchmarks/perf

Uh oh!

github-actions bot commented Oct 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

workflow: benchmarks/size

Uh oh!

mellyeliu left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Prakshal-Jain commented Oct 27, 2025 •

edited by mellyeliu

Loading

github-actions bot commented Oct 27, 2025 •

edited

Loading

github-actions bot commented Oct 27, 2025 •

edited

Loading