@stylexjs/eslint-plugin

The ESLint rule is a standalone ESLint plugin that mostly maintains an allowlist for valid styles and their valid values.

Installation

npm install --save-dev @stylexjs/eslint-plugin

Enable Flow Types

If you need to import this package in an environment where you need the Flow type definitions shipped with this package to work, please add the following options to your .flowconfig file:

module.system.node.resolve_dirname=flow_modules
module.system.node.resolve_dirname=node_modules

This will fix the missing types for eslint and estree.

Enabling the plugin and rules

Once you've installed the npm package you can enable the plugin and rules by opening your ESLint configuration file and adding the plugin and rules.

{
  "rules": {
    "@stylexjs/valid-styles": "error",
    "@stylexjs/sort-keys": "warn"
  },
  "plugins": ["@stylexjs"]
}

All the rules

@stylexjs/valid-styles

StyleX requires styles that are statically analyzable. This rule will detect invalid styles that StyleX cannot handle and provides basic type checking for style values.

Disallowed CSS properties and suggested fixes

Listed are common CSS properties that are not allowed in StyleX, along with their suggested replacements.

@stylexjs/sort-keys

This rule helps to sort the StyleX property keys according to property priorities.

stylex/stylex-valid-shorthands

This ESLint rule enforces the use of individual longhand CSS properties in place of multivalue shorthands when using stylex.create for reasons of consistency and performance. The rule provides an autofix to replace the shorthand with the equivalent longhand properties.

Disallowed: margin, padding with multiple values

Using multivalue shorthands that StyleX cannot safely split into equivalent longhands:

• margin: '8px 16px'
• padding: '8px 16px 8px 16px'

Fix: Replace with equivalent longhands. Note: this is autofixable.

Disallowed: font

Why: font is a shorthand that overrides multiple font settings at once.

Fix: Replace with individual font properties. Note: this is autofixable.

• fontSize
• fontFamily
• fontStyle
• fontWeight

Disallowed: border, borderTop, borderRight, borderBottom, borderLeft

Fix: Replace with individual sub-properties. Note: this is autofixable.

• borderWidth
• borderStyle
• borderColor

Config options

This rule has a few custom config options that can be set.

{
  allowImportant: false,                       // Whether `!important` is allowed
  preferInline: false                          // Whether the expansion uses logical direction properties over physical
}

@stylexjs/stylex-enforce-extension

This rule ensures consistent naming for StyleX theme files that export variables using stylex.defineVars().

Not allowed

• Exporting stylex.defineVars() in a file not ending in .stylex.js or .stylex.ts
• Using the .stylex.js / .stylex.ts extension without exporting stylex.defineVars()
• Mixing stylex.defineVars() with other exports in the same file

Instead...

• Use .stylex.js or .stylex.ts for files that only export stylex.defineVars()
• Export only theme vars from these files

Config options

{
  "themeFileExtension": ".stylex.js" // default, can be customized
}

stylex-no-unused

This rule flags unused styles created with stylex.create(...). If a style key is defined but never used, the rule auto-strips them from the create call.

stylex-no-legacy-contextual-styles

This rule flags usages of the original media query/pseudo class syntax that wraps multiple property values within a single @-rule or pseudo class like this:

const styles = stylex.create({
  root: {
    width: '100%',
    '@media (min-width: 600px)': {
      width: '50%',
    },
  },
});

This syntax is deprecated and should be replaced with the new syntax specified here

const styles = stylex.create({
  root: {
    width: {
      default: '100%',
      '@media (min-width: 600px)': '50%',
    },
  },
});

Changelog

0.13.1 (May 21, 2025)

Fixes

• Export additional Types.

0.13.0 (May 19, 2025)

New features

• Add positionTry API for creating @property-try declarations.
• Add defineConsts API for inlining constant values.
• Re-write of the runtime style injection module to be more reliable.

Breaking changes

• The runtimeInjection compiler option is now disabled by default when dev is true.
• The ESLint rule no-legacy-conditional-styles is renamed to no-legacy-contextual-styles.
• The useRemForFontSize compiler option is renamed to enableFontSizePxToRem. It is disabled by default and should not be used directly.
• The genConditionalClasses compiler option is renamed to enableInlinedConditionalMerge. It is enabled by default and should not be used directly.
• The attrs API is removed due to low usage and redundancy with the props API.

Fixes

• Fix the TypeScript types for themes and types functions.
• Fix the creation of duplicate classNames when defining nested pseudo-classes.
• Fix that allows the ESLint plugin to support use of importSources object syntax in validImports.
• Fix incorrect compiler error messages.
• Fix a bug that incorrectly wrapped CSS variables in quotes when used in the content property.
• Fix a bug in the firstThatWorks API when the last value was a variable.
• Allow importSources to be configured in the PostCSS plugin for React Strict DOM compatibility.

Deprecations

• Deprecate @stylexjs/shared package.

0.12.0 (Apr 10, 2025)

New features

• Hash keys in compiled style objects to reduce generated code size.
• New eslint rule to flag use of legacy Media Query and pseudo-class syntax.

Fixes

• Fix pseudo-elements bug in dynamic styles.
• Performance improvements to createTheme compilation by caching object evaluation.
• Disallow spreading in create calls.

Deprecations

• Deprecate @stylexjs/dev-runtime package.
• Deprecate @stylexjs/esbuild-plugin package.
• Deprecate @stylexjs/nextjs-plugin package.
• Deprecate @stylexjs/open-props package.
• Deprecate @stylexjs/webpack-plugin package.

0.11.1 (Mar 3, 2025)

Fixes

• Fix create compilation regression for string and number keys.
• Fix babel path resolution within monorepos.

0.11.0 (Feb 27, 2025)