New @stylexjs/unplugin package​

Stylex 0.17 comes with a new @stylexjs/unplugin package that use the excellent unplugin library to create a near-universal bundler plugin that works with Vite, Rollup, Webpack, Rspack, Esbuild, and more. In supported project setups, this new package should offer the best developer experience and performance for StyleX integration. We've introduced new examples for Webpack, RSPack, and various Vite setups (RSCs, React-Router, Waky and RedwoodSDK) with testing for both production builds and HMR in development builds when applicable. For frameworks that are not yet supported by our unplugin package, we continue to maintain the @stylexjs/postcss-plugin and and @stylexjs/cli packages for maximum compatibitiy.

We look forward to expanding this set of examples with more common frameworks and bundler setups.

Custom Markers for stylex.when.* APIs​

StyleX 0.16 introduced new set of APIs to observe the state of other elements:

• stylex.when.ancestor(pseudo, marker?)
• stylex.when.descendant(pseudo, marker?)
• stylex.when.siblingBefore(pseudo, marker?)
• stylex.when.siblingAfter(pseudo, marker?)
• stylex.when.anySibling(pseudo, marker?)
• stylex.defaultMarker()

StyleX 0.17 introduces one new API to create custom named markers, stylex.defineMarker().

Using these APIs, a typical CSS selector such as .parent:hover .child can be implemented as:

// markers.stylex.ts
import * as stylex from '@stylexjs/stylex';

export const cardMarker = stylex.defineMarker();
export const btn = stylex.defineMarker();

// Card.tsx
import * as stylex from '@stylexjs/stylex';
import { cardMarker, btnMarker } from './markers.stylex';
import {tokens} from './tokens.stylex';

export function Card() {
  return (
    <article {...stylex.props(styles.card, cardMarker)}>
      <p>Markers let siblings and ancestors opt into the same state.</p>
      <button {...stylex.props(btnMarker, styles.cta)}>
        Action
        <ArrowIcon style={styles.icon} />
      </button>
    </article>
  );
}

const styles = stylex.create({
  card: {
    borderWidth: 1,
    borderStyle: 'solid',
    borderColor: tokens.borderColor,
  },
  cta: {
    backgroundColor: {
      default: 'black',
      [stylex.when.ancestor(':hover', cardMarker)]: tokens.accent,
    },
    color: 'white',
  },
  icon: {
    opacity: {
      default: 0,
      [stylex.when.ancestor(':hover', cardMarker)]: 1,
    },
    transform: {
      default: 'translateX(0)',
      [stylex.when.ancestor(':hover', btnMarker)]: 'translateX(4px)',
    }
  }
});

Icon in the button appears when card is hovered, but it moves to the right when the button itself is hovered.

Updating default configuration options​

We are updating some of the default StyleX configuration options to help make the builds more consistent across development and production and improve the developer experience in many scenarios.

enableDebugClassNames is now disabled by default​

Enabling this option will emit classNames that reference the CSS property being applied, and CSS variable names that are prefixed with the name used in source. However, generating incompatible CSS in development and production can cause caching-related bugs in some setups and so we are disabling this option by default.

data-style-src prop now shows full file paths​

The data-style-src prop is injected in addition to className and style during development to help identify the list of style objects applied to to the element in order or application. Previously, it showed only the last two segments of the file path which can be confusing.

Now, the it will include the full path relative to the nearest package.json file. For third-party package, we will also include the package name itself.

enableDevClassNames will now be enabled when dev is enabled​

The dev option inserts additional classNames that help identify where various classNames are coming from.

enableMediaQueryOrder is now enabled by default​

This config ensures that authored media query order is respected, with later queries taking precedence over earlier ones.

Other Improvements​

• Added support for handling defineConsts correctly when runtime injection is enabled.
• Fixed a bug sometimes that caused invalid CSS output when media queries use screen and conditionals
• Dependency updates, including Jest, to pick up the latest fixes. (Thanks @vincentriemer, @jcperez-ch!)
• Specificity improvements when using stylex.when.* selectors alongside regular pseudo-classes.
• Expand how often stylex.props is precompiled to improve performance.
• Various improvements to Flow and Typescript types. (Thanks @j-malt, @henryqdineen!)
• Various improvements and fixes to the ESlint plugin, including support for defineConsts in enforce-extension, and improvements to sort-key ordering. (Thanks @hiteshshetty-dev, @yjoer, @dwei-figma!)

Descendant and sibling selectors​

We’re adding a new suite of APIs under stylex.when with support for descendant and sibling selectors: ancestor, descendant, anySibling, siblingBefore, and siblingAfter.

• Ancestor/descendant (stylex.when.ancestor and stylex.when.descendant) selectors let you style an element based on the state of ancestors or descendants in the DOM tree.
• Sibling selectors (stylex.when.anySibling, stylex.when.siblingBefore and stylex.when.siblingAfter) let you style an element based on the state of adjacent siblings.

To use descendant and sibling selectors, you'll need to mark the element being observed by passing the stylex.defaultMarker class name. Support for custom markers will be added in a future release.

import * as stylex from '@stylexjs/stylex';

const styles = stylex.create({
    foo: {
      backgroundColor: {
        default: 'blue',
        [stylex.when.ancestor(':hover')]: 'red',
      },
    },
});

<div {...stylex.props(stylex.defaultMarker())}>
  <div {...stylex.props(styles.foo)}> Some Content </div>
</div>

Note: Lookahead selectors like stylex.when.siblingAfter, stylex.when.anySibling, and stylex.when.descendant rely on the CSS has() selector, which does not yet have widespread browser support.

defineConsts improvements​

We’ve added support for overriding defineConsts constants that reference CSS variables (var(--*)) when set to variables and variable fallbacks. Constants now behave like passthroughs, with overrides applying to the original CSS variable. This allows you to re-define them within create calls as you would for defineVars.

export const colors = stylex.defineConsts({
  bg: "var(--background-color)",
  accent: "var(--accent, lightblue)",
});

import {colors} from "./colors.stylex.js";
const styles = stylex.create({
  root: {
    [colors.bg]: "red",
    [colors.accent]: "darkblue",
  },
});

We've also added support for defineConsts in dynamic styles. You can now use defineConsts to declare media queries within dynamic styles as you would in regular StyleX namespaces.

const style = stylex.create({
  main: (height) => ({
    color: {
      default: colors.red,
      [breakpoints.sm]: colors.blue,
      [breakpoints.md]: colors.yellow,
    },
    height: height - 10,
  }),
});

Linter improvements​

We made several improvements and lint fixes to the valid-styles rule. The valid-styles rule now has support for locally resolved constants.

const HEIGHT = 5;

const styles = stylex.create({
  default: {
    scrollMarginTop: HEIGHT + 5,
    scrollMarginBottom: HEIGHT * 5,
  },
});

We added linter support for setting CSS custom properties within create calls. (Thanks @dwei-figma!)

const styles = stylex.create({
  default: {
    --background-color: 'red',
  },
});

We also added support for positionTry styles (Thanks @abhakat!), better validation for pseudo-elements (Thanks @dwrth!), migrated object type validation to Flow (Thanks @jcperez-ch!), and of 0 values as strings ('0') for length properties.

Bug fixes​

• Fixed class name construction for dynamic contextual styles.
• Reduced chances of dynamic variable name collisions. (Thanks @necolas!)

Miscellaneous​

• A webpack example was added to our suite of StyleX example integrations! (Thanks @RavenColEvol!)
• Support to hoist stylex.create and nested objects within functions.
• Optimized precomputed props calls in JSX. (Thanks @necolas!)
• More efficient handling of null/undefined in dynamic styles.

Media query ordering​

Previously, media queries within a style property were applied in a predetermined sorting order. This often meant that the order you authored the queries did not match how they were applied, so we recommended manually ensuring your media queries didn’t overlap to prevent unexpected overrides in behavior.

We've integrated our in-house media query parser and transformer to handle this automatically. You can now write overlapping media queries in a contextual style in the order you desire, and the compiler will rewrite them so that later queries take precedence over earlier ones.

The compiler now also validates media query syntax and simplifies complex queries when possible, opening the door to later optimizations.

As an example, take this create call:

const styles = stylex.create({
  foo: {
    gridColumn: {
      default: '1 / 2',
      '@media (max-width: 1440px)': '1 / 4',
      '@media (max-width: 1024px)': '1 / 3',
      '@media (max-width: 768px)': '1 / -1',
    },
  },
});

This is now transformed at compile time to:

const styles = stylex.create({
  foo: {
    gridColumn: {
      default: '1 / 2',
      '@media (max-width: 1440px) and (min-width: 1024.01px)': '1 / 4',
      '@media (min-width: 768.01px) and (max-width: 1024px)': '1 / 3',
      '@media (max-width: 768px)': '1 / -1',
    },
  },
});

This new feature is gated behind the config option enableMediaQueryOrder.

Dynamic styles improvements​

Dynamic styles should now work more consistently when given the same values as static styles. Improvements have been made to how we handle null and undefined values.

We've also made optimizations in how we process dynamic styles to improve performance and minimize the amount of generated Javascript. We do this by using heuristics to detect values that can never be nullable.

Fixes​

• Fixed TypeScript types for stylex.types.* functions (Thanks @nmn!)
• Resolved opaque type issues for InlineStyles. (Thanks @pawelblaszczyk5!)
• Fixed ESLint utility functions for number and math call validation and added style validation for length properties.

Documentation​

• Added documentation around manual CSS variables generated with defineVars. (Thanks @necolas!)
• Updated outdated theming docs to align with current createTheme behaviour (Thanks @nmn!)
• Fixed ESLint rule severity syntax in the installation guide examples and cleaned up docs for descendent styles. (Thanks @sonsu95 and @mtpetros!)

New features​

Compiler: viewTransitionClass​

The viewTransitionClass API allows you to use StyleX to customize your CSS View Transitions. This API works nicely with React’s new <ViewTransition /> component:

import {unstable_ViewTransition as ViewTransition} from 'react';
import * as stylex from '@stylexjs/stylex';

const transitionClass = stylex.viewTransitionClass({
  old: {
    animationName: stylex.keyframes({ to: { opacity: 0 } }),
    animationTimingFunction: 'ease-out',
    animationDuration: '300ms',
  },
  new: {
    animationName: stylex.keyframes({ from: { opacity: 0 } }),
    animationTimingFunction: 'ease-out',
    animationDuration: '300ms',
  },
});

// in a component definition

<ViewTransition default={transitionClass}>
  <Content />
</ViewTransition>

Linter: validImports​

The @stylexjs/eslint-plugin package now supports the validImports option for all rules, allowing you to configure where the linter expects StyleX to be imported from. This is equivalent to the importSources option for the compiler. Thanks to @javascripter for this improvement.

{
  // Default: ['stylex', '@stylexjs/stylex']
  validImports: Array<string | { from: string, as: string }>,
}

Breaking changes​

Style resolution​

StyleX will now use property-specificity instead of application-order as the default value for the styleResolution option (the strategy used to merge styles). The difference between these 2 strategies is as follows:

• application-order
  • The last style wins, i.e., margin wins over marginTop if it appears last in the order of styles.
  • Larger generated JavaScript objects.
• property-specificity
  • The more specific style wins, i.e., marginTop wins over margin irrespective of the order of styles.
  • Disallows more shorthands, e.g., background, border.
  • Smaller generated JavaScript objects.

If you experience visual regressions, set styleResolution to application-order. However, the performance metrics we track are all significantly improved or neutral when using property-specificity, therefore, we strongly encourage migration.

Fixes​

• [babel-plugin] Fix theming in dev/debug mode.
• [eslint-plugin] Add autofix support for all remaining nonstandard CSS properties to the valid-styles rule.
• [stylex] Fix the TypeScript types. Thanks to @pawelblaszczyk5 for this improvement.

New APIs​

defineConsts​

We've added a new defineConsts API to allow for declaration and use of constant values. Unlike defineVars, these are inlined at build-time and do not generate CSS variables. This is a long requested feature that allows for shareable media queries.

export const breakpoints = stylex.defineConsts({
  small: '@media (max-width: 600px)',
  medium: '@media (min-width: 601px) and (max-width: 1024px)',
  large: '@media (min-width: 1025px)',
});

export const colors = stylex.defineConsts({
  brand: '#0055FF',
  surface: '#FFFFFF',
  text: '#111111',
});

You can then import and use these constants in any create call:

import * as stylex from '@stylexjs/stylex';
import { breakpoints, colors } from './constants.stylex.js';

const styles = stylex.create({
  container: {
    padding: {
      default: '4px'
      [breakpoints.small]: '8px',
      [breakpoints.medium]: '16px',
      [breakpoints.large]: '24px',
    },
  },
  label: {
    color: colors.text,
  },
});

positionTry​

positionTry enables graceful fallback positioning via the @property-try at-rule. This makes it easier to handle layout edge cases across varying browser support and runtime constraints. (Thanks nmn!)

const fallback = stylex.positionTry({
  positionAnchor: '--anchor',
  top: '0',
  left: '0',
  width: '100px',
  height: '100px',
});

const styles = stylex.create({
  box: {
    positionTryFallbacks: fallback,
  },
});

Breaking changes​

• The attrs API is removed due to low usage and redundant functionality; non-React users can replace it with a wrapper around props as documented here.
• The runtimeInjection compiler option is now disabled by default in development mode (dev:true) to better match production behavior.
• ESLint rule no-legacy-conditional-styles is renamed to no-legacy-contextual-styles.
• The config option useRemForFontSize is renamed to enableFontSizePxToRem; now disabled by default and not intended for external use.
• The config option genConditionalClasses is renamed to enableInlinedConditionalMerge; now enabled by default and not intended for external use.

Fixes​

• Fixed duplicate classNames in styles with nested pseudo-classes (Thanks jeongminsang!)
• ESLint plugin now correctly supports importSources object syntax in validImports (Thanks javascripter!)
• Fixed a bug where CSS variables would be wrapped in quotes when used with the content property.
• Fixed evaluation bug in firstThatWorks when the final value was a CSS variable.
• Fixed TypeScript types for themes and types functions.

Miscellaneous​

• Rewrote the runtime style injection system to be more robust in dev. This resolves issues with hot reloading and duplicate style tags.
• Added Flow types for anchor positioning. (Thanks Jta26!)
• Added support for custom importSources in the PostCSS plugin for React Strict DOM compatibility. (Thanks javascripter!)
• Improved compiler error messages.

Deprecations​

We’ve deprecated the @stylexjs/shared package on npm.

Performance​

Object key minification​

The keys of compiled style objects are now minified to reduce overall code size.

Faster theme compilation​

Compiling createTheme calls is now several orders of magnitude faster. This was achieved by caching evaluated theme objects.

ESLint improvements​

New no-legacy-contextual-styles rule​

A new rule has been added to the StyleX ESLint plugin to flag uses of the deprecated media query and pseudo-class syntax. This rule flags usage of the legacy media query and pseudo-class syntax that wraps multiple property values inside a single @-rule or pseudo-class block. This pattern is deprecated and should be replaced with the updated syntax here. (Thanks vincentriemer!)

Bug fixes​

Styling pseudo-elements in dynamic styles​

Dynamic styles can now be used to style pseudo-elements. Previously, the generated CSS variables could not be inherited by pseudo-elements.

Disallow object spreads in create​

Object spreading in create calls is now disallowed by the compiler, as this breaks runtime caching of style merging.

Deprecations​

The following bundler integration packages have been deprecated. We're focusing development on the core StyleX toolchain, and providing consistent tools for use across different bundlers. We recommend using the @stylexjs/postcss-plugin.

• @stylexjs/esbuild-plugin
• @stylexjs/nextjs-plugin
• @stylexjs/webpack-plugin

The @stylexjs/rollup-plugin remains, but may be generalized into an unplugin package to extend this option to other bundlers.

The following other packages have also been deprecated.

• @stylexjs/dev-runtime
• @stylexjs/open-props (replacement available at stylextras/open-props)

StyleX v0.11.0 is now available, with significant improvements in debugging, CLI caching, and documentation!

Debugging Improvements​

Improved Runtime Debugging​

We've made some big improvements to the information available in debug mode. We now include sourceMap information to indicate the file and line of the create call responsible for providing styles on a given element. This information is contained in the data-style-src prop in the DOM. To use, set debug to true in the StyleX config. (Thanks necolas)

CLI Cache Improvements​

The StyleX CLI now includes better cache invalidation and expanded support:

• Cache now invalidates when config options change in the StyleX and .babelrc configurations
• Added support for relative file paths
• Now supports Deno applications

Documentation Updates​

New theming recipes​

We've added new documentation that provides improved guidance on theming, including best practices for resetting and merging themes, as well as dynamic color-scheme management using built-in functions. (Thanks nmn)

API enhancements​

We've added documentation about the new PostCSS plugin and updated the docs to reflect the latest debug information. (Thanks necolas)

Miscellaneous​

• We've added exported return types for stylex.types.* functions such as stylex.Color and stylex.Length. Now, expressions like stylex.types.color("red") are explicitly typed as stylex.Color<string> (Thanks nmn)
• We've added an autofix to the valid-styles rule to provide autofix suggestions for border styles
• We've made a fix to how we process multivalue shorthands with slashes (Thanks yasuhiro-yamamoto)
• Small typo fixes (Thanks mattstyles and necolas)

• Fixed a bug where variables with camelCase names were incorrectly converted to kebab-case (Thanks yasuhiro-yamamoto)
• Fixed a bug in the eslint valid-styles rule where it would incorrectly flag when importing a file with an extension (Thanks beaumontjonathan)
• Added support for .js resolved file extension imports from .ts files (Thanks beaumontjonathan)
• Replaced crypto with murmurhash for CLI caching
• Fixed a bug where the import resolve function would not respect the Windows system (Thanks nonzzz)
• Fixed a bug where the initial-value in @Property was invalid

Easier adoption with the all-new PostCSS plugin​

StyleX now ships with an all-new PostCSS plugin. This plugin allows you to use StyleX with any PostCSS-compatible toolchain, to better integrate with existing projects. The PostCSS plugin is now our recommended approach for using StyleX in a Next.js or Vite project. The example Next.js app in this repository has been updated to reflect this change. The existing @stylexjs/nextjs-plugin will be deprecated in the next release.

A huge thanks to javascripter for contributing this plugin.

Better debugging​

StyleX has a new debug option to enable more readable classNames and variable names during development. With this option turned on, classNames will be prefixed with the affected CSS property and variables will be prefixed with their key name in your source code. (Thanks mellyeliu)

Additionally, the error messages of the StyleX Babel plugin have been improved to be more granular and correctly highlight the location of the source code causing the error.

ESLint improvements​

All new no-unused rule​

The StyleX ESLint plugin now ships with a new no-unused rule that detects unused styles. (Thanks Samantha-Zhan)

Other improvements​

The valid-styles rule now offers more auto-fixes, and a small bug was fixed in the valid-shorthands rule. (Thanks mellyeliu)

Theming now works without manually configuring rootDir​

StyleX previously required manual configuration of unstable_moduleResolution.rootDir for enabling the theming APIs. This is no longer the case. Additionally, compilation should be more reliable and cache-friendly, especially when using package managers like pnpm.

Performance improvements for Dynamic styles​

StyleX uses CSS custom properties (aka CSS variables) as inline styles for dynamic values for styles. In v0.10.0 StyleX now generates @property declarations marking these variables as non-inheritable. This improves the style resolution performance of the browser's styling engine, which in some cases can be quite significant. We have also updated our benchmarks to track the code size impact of this change. (Thanks Samantha-Zhan)

CLI improvements​

Caching​

The StyleX CLI now uses a cache by default which ensures that only changed files are recompiled. This cache is stored in the nearest node_modules folder and works even without using watch mode. (Thanks mellyeliu)

Better interoperability​

The CLI now supports configuring additional Babel presets and plugins that can run before the StyleX plugin to let you use custom syntax transformations. The StyleX Babel plugin was also updated to make this use-case more reliable.

Windows support​

A bug with file paths was fixed and the CLI should now work correctly on Windows.

Documentation​

We have introduced a new Recipes section in the documentation to showcase some useful patterns when using StyleX.

Miscellaneous​

• The StyleX Rollup plugin now supports generating filename hashes. (Thanks nonzzz)
• We now use the @dual-bundle/import-meta-resolve package to replace esm-resolve which should making theming APIs more reliable. (Thanks p0nch000)
• Removed unnecessary quotes around 'content' values in CSS files. (Thanks nikeee)
• Added support for view-transition-name in ESLint's valid-styles rule.
• Added support for interpolate-size in ESLint's valid-styles rule.

Improvements to Theming APIs​

There are some big improvements to the predictability and reliability of our theming APIs — defineVars and createTheme.

Breaking Change: Themes are now exclusive​

When you create a VarGroup with defineVars, you are able to theme any subset of the variables within using the createTheme API. These themes can then be applied like any other StyleX styles using props (or attrs). If you try to apply multiple themes for the same VarGroup, on the same element, the last applied theme wins, just as you might expect.

However, previously, if you instead applied one theme on a parent element, and another theme on a child element, the themes would end up being merged.

// tokens.stylex.ts
import * as stylex from '@stylexjs/stylex';

export const varGroup = stylex.defineVars({
  primary: 'black',
  secondary: 'grey',
});

import * as stylex from '@stylexjs/stylex';
import {varGroup} from './tokens.stylex.ts';

const red = stylex.createTheme(varGroup, {
  primary: 'red',
});

const blue = stylex.createTheme(varGroup, {
  secondary: 'blue',
});

const styles = stylex.create({
  primary: {color: varGroup.primary},
  secondary: {color: varGroup.secondary},
});

function App() {
  return (
    <div {...stylex.props(red)}>
      <div {...stylex.props(blue)}>
        <span {...stylex.props(styles.primary)}>Hello </span>
        <span {...stylex.props(styles.secondary)}>World!</span>
      </div>
    </div>
  );
}

Previously this would have resulted in the text "Hello World!" being styled with a red primary color and a blue secondary color. Now, the text will be styled with a black primary color and a blue secondary color.

You can think of themes conceptually as re-applying the default values for any variables that are not explicitly overridden by the theme. This change simplifies the mental model for how themes work, and has the added benefit of making it easy to create "reset" themes:

const reset = stylex.createTheme(varGroup, {});

rootDir is now optional!​

Previously, when configuring the StyleX Babel plugin, you had to explicitly specify a rootDir value. Internally, this path was used to generate a canonical file path for every .stylex.js file in your project.

However, this was not only cumbersome, but it also resulted in errors when importing VarGroups from node_modules. Different package managers deal with packages differently, and this can be particularly consequential for mono-repos.

Now, the rootDir option is optional, and StyleX will use the nearest package.json file to determine the canonical path, automatically. This should make theming APIs work more reliably.

More reliable ESM resolution​

The StyleX Babel plugin now uses the esm-resolve package to resolve ESM imports. This should fix most situations where the compiler would fail to resolve VarGroup imports in result in the compilation of create to fail.

Thanks hipstersmoothie!

Dynamic style improvements​

Dynamic Styles within StyleX have been improved to be more reliable and efficient. Previously, if the dynamic value of a style resolved to null at runtime, StyleX would represent that with the revert keyword in CSS. This did not always work as expected, ran into certain browser bugs and resulted in styles that were unnecessarily bloated.

In v0.9.3, null values for Dynamic styles work exactly the same as using null as a static value within create. This means any previously applied value for the given property will be removed and no className will be applied for that property.

@stylexjs/dev-runtime overhaul​

The @stylexjs/dev-runtime package is a development-only package that lets you use a much slower version of StyleX that runs entirely at runtime. Previously, it worked by patching the main @stylexjs/stylex package at runtime. However, this did not always work reliably.

Breaking Change: The @stylexjs/dev-runtime package now returns the StyleX API.

import makeStyleX from '@stylexjs/dev-runtime';

const stylex = makeStyleX({
  // configuration options
  classNamePrefix: 'x',
  dev: true,
  test: false,
});

const styles = stylex.create({
  color: 'red',
});

Improved handling of nested pseudo-elements and pseudo-classes​

Fixed a bug where using Pseudo Classes (such as :hover) within Pseudo Elements (such as ::before) (or vice-versa) would sometimes result in surprising behavior. StyleX now handles such cases, with an arbitrary level of nesting, correctly.

Miscellaneous​

• Added support for additional Pseudo Elements and Pseudo Classes to our ESLint rule and type definitions.
  • Thanks aspizu and nikeee!
• Slightly better compiler error messages.
  • Thanks EvanBacon!

Linting Enhancements​

We've been making a lot of improvements to our ESLint plugin. We've both improved our existing rules and added new ones. Thanks to Melissa Liu!

Here are some of the highlights:

New valid-shorthands rule​

This rule enforces our opinions on when and how you should use CSS shorthand properties. It disallows the use of multi-value shorthands for shorthands, and disallows certain properties altogether.

const styles = stylex({
  invalidShorthands: {
    // border shorthands are entirely disallowed
    // Use `borderWidth`, `borderStyle`, and `borderColor` instead
    border: '1px solid black',
    // Multiple values for different sides within the same shorthand are disallowed
    borderWidth: '1px 2px 3px 4px',
    margin: '10px 20px 30px',
    padding: '10px 20px',
  },
  validShorthands: {
    borderBottomWidth: 3,
    borderColor: 'black',
    borderInlineEndWidth: 2,
    borderInlineStartWidth: 4,
    borderStyle: 'solid',
    borderTopWidth: 1,
    marginBottom: 30,
    marginInline: 20,
    marginTop: 10,
    paddingBlock: 10,
    paddingInline: 20,
  },
});

These opinions guide you towards the most consistent and most re-usable CSS.

New enforce-extension rule​

This new rule enforces the rules when defining variables._createMdxContent It enforces that usages of defineVars are named exports within a file with a .stylex.js (or '.ts' or '.jsx' or '.tsx') extension, and that such a file does not have any other exports.

Other Lint fixes​

We've updated the ESLint rule to include additional missing properties and values. Notably, the valid-styles rule should now understand:

• fieldSizing as a valid prop
• @starting-style as a valid at-rule.

Using lightningcss for post-processing​

StyleX's compilation process is conceptually a three step process:

1. Transform JavaScript source files to replace usages of create etc. with the resulting classNames and collect the generated CSS.
2. De-duplicate and sort all the collected CSS.
3. Write the CSS to a file.

However, often it's useful to post-process the CSS before writing it to a file. This post-processing can include minification, prefixing, or other transformations. After much discussion we have decided to standardize on lightningcss for this post-processing.

As a first step, we're add lightningcss by default for our Rollup Plugin. We will be rolling out support for our other bundler plugins next.

Thanks Prakshal Jain for his work on this!

Theming Improvements​

We've made two small but important improvements for theming in StyleX.

Use stylex.firstThatWorks to define fallback values for CSS variables.​

StyleX has a firstThatWorks function that can be used to define fallback values for CSS property. This is akin to using the same property multiple times with different values in CSS.

/* Represent this */
.my-class {
  background-color: #808080;
  background-color: oklab(0.5 0.5 0.5);
}

const styles = stylex.create({
  myClass: {
    // as:
    backgroundColor: stylex.firstThatWorks(
      'oklab(0.5 0.5 0.5)',
      '#808080',
    ),
  },
});

Now, the same API will also work for CSS variables.

/* Represent this */
.my-class {
  background-color: var(--bg-color, #808080);
}

const styles = stylex.create({
  myClass: {
    // as:
    backgroundColor: stylex.firstThatWorks(
      'var(--bg-color)',
      '#808080',
    ),
  },
});

Themes have higher specificity than default var values​

The CSS rule created with createTheme now has higher specificity than the rule created with defineVars.

This should not have been issue in the vast majority of cases already, as we always sorted the rules in the correct order. However, in extreme edge-cases where you may be loading multiple StyleX CSS files on the same page, this fix will ensure consistency.

Other fixes​

We've made some other fixes in various parts of StyleX:

• fix: Logical values for textAlign are no longer converted to left and right.
• fix: [CLI] Handle errors while deleting files gracefully (#695)
• feat: Expand configuration options to CLI (#638)
• fix: Don't add 'px' units for number values used for variables (#694)
  • fix: Don't add 'px' units for additional properties that accept raw numbers as values (#705)

Documentation Improvements​

We've added documentation for options of our various bundler plugin and added additional projects to our ecosystem page.

We've also updated the search on our website to be much more comprehensive and accurate. (Powered by Algolia)

CLI​

StyleX relies on a compiler that transforms your JavaScript code and generates a static CSS file. However, integrating this compiler with with your bundler can be tricky. So, while we continue to work on improving the quality of our bundler integrations, we are introducing a new CLI as an alternative!

The CLI transforms an entire folder. It generates an output folder where StyleX has already been compiled away and a static CSS file has been generated. Further, the CLI inserts an import statement for the generated CSS file into each file that uses StyleX.

We are excited to offer this alternative to the bundler-based setup and are choosing to release the CLI in an experimental state. We would love to hear your feedback on how it works for you and what improvements you would like to see.

Special thanks to Joel Austin for his work on the CLI.

Literal names for CSS variables​

When using, defineVars, StyleX abstracts away the actual CSS variable name, and lets you use it as a JavaScript reference. Behind the scenes, unique variable names are generated for each variable.

However, there are scenarios where it is useful to know the exact variable name. For example, when you may want to use the variable in a standalone CSS file.

To address such use-cases, we have updated the defineVars API to use literals that start with -- as is. Other than the keys passed to defineVars, the API is unchanged.

const vars = stylex.defineVars({
  '--primary-color': 'red',
  '--secondary-color': 'blue',
});

Bug Fixes and improvements​

Additionally bug fixes to types, eslint rules and the bundler plugins has been made.

Improvements for variables​

We've added some new features and improvements for working with variables and themes in StyleX.

Fallback values for variables​

You can now provide a fallback value for variables defined with the defineVars API. This new capability does not introduce any new API. Instead, the existing firstThatWorks API now supports variables as arguments.

import * as stylex from '@stylexjs/stylex';
import {colors} from './tokens.stylex';

const styles = stylex.create({
  container: {
    color: stylex.firstThatWorks(colors.primary, 'black'),
  },
});

Using a list of fallbacks variables is supported.

Typed variables​

StyleX introduces a brand new set of APIs for defining <syntax> types for CSS variables. This results in @property rules in the generated CSS output which can be used to animate CSS variables as well as other special use-cases.

The new types.* functions can be used when defining variables to define them with a particular type.

import * as stylex from '@stylexjs/stylex';

const typedTokens = stylex.defineVars({
  bgColor: stylex.types.color<string>({
    default: 'cyan',
    [DARK]: 'navy',
  }),
  cornerRadius: stylex.types.length<string | number>({
    default: '4px',
    '@media (max-width: 600px)': 0,
  }),
  translucent: stylex.types.number<number>(0.5),
  angle: stylex.types.angle<string>('0deg'),
  shortAnimation: stylex.types.time<string>('0.5s'),
});

Once variables have been defined with types, they can be animated with keyframes just like any other CSS property.

import * as stylex from '@stylexjs/stylex';
import {typedTokens} from './tokens.stylex';

const rotate = stylex.keyframes({
  from: { [typedTokens.angle]: '0deg' },
  to: { [typedTokens.angle]: '360deg' },
});

const styles = stylex.create({
  gradient: {
    backgroundImage: `conic-gradient(from ${tokens.angle}, ...colors)`,
    animationName: rotate,
    animationDuration: '10s',
    animationTimingFunction: 'linear',
    animationIterationCount: 'infinite',
  },
})

This can be used achieve some interesting effects, such as animating the angle of a conic-gradient:

This new capability is primarily about CSS types, but the new API also makes the TypeScript (or Flow) types for the variables more powerful.

As can be seen in the example, generic type arguments can be used to constrain the values the variable can take when creating themes with createTheme.

ESlint plugin​

New sort-keys rule​

We've added a new sort-keys rule to the StyleX ESlint plugin. This rule is a stylistic rule to enforce a consistent order for keys for your StyleX styles.

Thanks nedjulius

Improvements to propLimits for valid-styles rule.​

The valid-styles rule has been improved to allow more expressive "prop limits".

Miscellaneous​

• ESlint 'valid-styles' rule now allows using variables created with defineVars as keys within dynamic styles.
• Bug-fixes to the experimental include API
• Fixed debug className generation for createTheme
• Units are no longer removed from 0 values
• Compilation bug-fixes

Our Ecosystem page continues to grow with community projects. Including a Prettier plugin for sorting StyleX styles.

New attrs function​

The props function returns an object with a className string and a style object. Some frameworks may expect class instead of className and a string value for style.

We are introducing a new attrs function so StyleX works well in more places. attrs returns an object with a class string and a style string.

New sort-keys rule for the Eslint plugin​

A new @stylexjs/sort-keys plugin has been introduced which will sort styles alphabetically and by priority. This will make media query order more predictable.

Thanks @nedjulius!

New aliases option for the StyleX Babel plugin​

A new aliases field can be used to configure StyleX to resolve custom aliases that may be set up in your tsconfig file. NOTE: StyleX currently needs to be configured with absolute paths for your aliases.

Thanks @rayan1810!

New Esbuild plugin​

A new official plugin for Esbuild has been introduced as @stylexjs/esbuild-plugin.

Thanks @nedjulius!

Other Enhancements​

• Configuration options passed to the StyleX Babel plugin will now be validated.
• The @stylexjs/stylex now has ESM exports alongside the commonJS exports.
• The ESLint valid-styles rule will catch when using empty strings as string values.

Bug Fixes​

• Some CSS properties which previously caused type and lint errors will now be accepted.
• Using variables for opacity will no longer cause type errors.
• Using keyframes within defineVars will now work correctly
• runtimeInjection will correctly be handled
• Setting the value of variables from defineVars as dynamic styles will now work correctly.
• Usage of 0px within CSS functions will no longer be simplified to a unit-less 0 as this doesn't work in certain cases.
• Spaces around CSS operators will be maintained.

In addition to these, we've added an "Ecosystem" page to our website to highlight various community projects around StyleX.

Enhancements​

• The amount of JavaScript generated after compilation has been further reduced.
• Added support for some previously missing CSS properties to the ESLint plugin.
• Added support for using variables in keyframes.
• Removed the code for style injection from the production runtime, reducing the size of the runtime by over 50%.
• Added Flow and TypeScript types for the Rollup Plugin.
• Added the option to use CSS Layers in all bundler plugins.
• TypeScript will now auto-complete style property names.
• Bundler plugins will now skip files that don't contain StyleX, resulting in faster build times.

Bug Fixes​

• Fixed a bug where the ESLint plugin was sometimes unable to resolve local constants used for Media Queries and Pseudo Classes.
• Resolved a bug where the runtime injection of styles in dev mode would sometimes fail.
• Addressed a bug where styles injected at runtime during development would sometimes suffer from specificity conflicts.
• The TypeScript types for Theme will now correctly throw an error when applying a theme for the wrong VarGroup.

In addition to these, we've made other improvements to the types and documentation. I want to extend my gratitude to all the contributors for their pull requests. ♥️

Happy New Year!

What is StyleX?​

StyleX takes the developer experience of CSS-in-JS libraries and uses compile-time tooling to bridge it with the performance and scalability of static CSS. However, StyleX is not just another compiler-based CSS-in-JS library. StyleX has been carefully designed to meet the requirements of large applications, reusable component libraries, and statically typed codebases.

1. StyleX supports an expressive subset of CSS. It avoids complex selectors and guarantees no specificity conflicts in the generated CSS.
2. StyleX transforms, organizes, and optimizes styles into "atomic" CSS class names. There's no need to learn or manage a separate library of utility class names.
3. StyleX allows styles to be merged across file and component boundaries, making it ideal for component libraries that allow user customization.
4. StyleX is fully typed and provides type utilities to allow fine-grained control over what properties and values can be accepted by a component.

What are the advantages of StyleX?​

Fast​

StyleX is designed to be fast at both compile-time and runtime. The Babel transforms do not significantly slow down builds.

At runtime, StyleX entirely avoids the costs associated with using JavaScript to insert styles at runtime, and does little more than efficiently combine class name strings when necessary. And the generated CSS is optimized for size, ensuring that the styles for even the largest websites can be quickly parsed by browsers.

Scalable​

StyleX is designed to scale to extremely large codebases, like the ones we have at Meta. The Babel plugin can handle processing styles in many thousands of components at compile-time by leveraging atomic builds and file-level caching. And because StyleX is designed to encapsulate styles, it allows new components to be developed in isolation with the expectation that they will render predictably once used within other components.

By generating atomic CSS class names, StyleX helps minimize the size of the CSS bundle. As the number of components in an application grows, the size of the CSS bundle starts to plateau. This frees developers from having to manually optimize or lazy-load CSS files.

Predictable​

StyleX automatically manages the specificity of CSS selectors to guarantee that there are no collisions between the generated rules. StyleX gives developers a system that reliably applies styles, and ensures that "the last style applied always wins"

Composable​

StyleX styles are easy to compose. Not only can multiple local styles be applied conditionally, styles can also be passed across files and components. Styles always merge with predictable results.

Type-Safe​

You can constrain the styles a component accepts by using TypeScript or Flow types. Every style property and variable is fully typed.

Colocation​

StyleX allows and encourages authoring styles in the same file as the component that uses them. This co-location helps make styles more readable and maintainable in the long run. StyleX is able to use static analysis and build-time tools to de-duplicate styles across components and to remove unused styles.

Testable​

StyleX can be configured to output debug class names instead of functional atomic class names. This can be used to generate snapshots that don't change as often in response to minor design changes.

How does StyleX work?​

StyleX is a collection of tools that work together.

• A Babel plugin
• A small runtime library
• An ESlint plugin
• A growing collection of integrations with bundlers and frameworks.

The most important part of StyleX is the Babel plugin. It finds and extracts all the styles defined within your source code and converts them to atomic class names at compile time. A helper function deduplicates, sorts, and writes the collected styles to a CSS file. These tools are used to implement bundler plugins.

To make using StyleX feel as natural as possible, StyleX supports various static patterns to define your styles by using local constants and expressions. Additionally, in order to give you the best performance possible, the Babel plugin also pre-computes the final class names when possible to remove any runtime cost — even merging class names — from a given file. If a component is defining and using styles within the same file statically, the runtime cost will be ZERO.

When using more powerful patterns such as style composition, a tiny runtime merges objects of class names dynamically. This runtime has been optimized to be extremely fast and the results are then memoized.

The origins of StyleX​

The previous Facebook website used something akin to CSS modules and suffered from various problems that inspired the initial idea for CSS-in-JS. The average visitor to facebook.com would download tens of megabytes of CSS. Much of it unused. In order to optimize the initial load, we would lazy load our CSS which would, in turn, lead to slow update (or "Interaction to Next Paint") times. Usage of complex selectors would lead to conflicts or "specificity wars". Engineers would often resort to using !important or more complex selectors to solve their problems, making the entire system progressively worse.

A few years ago, when we were rebuilding facebook.com from the ground up using React, we knew we needed something better and built StyleX.

StyleX was designed to scale, and the design has proven itself in our years of experience using it. We've added new features to StyleX without regressing on performance or scalability while making StyleX more of a joy to use.

Using StyleX has been a massive improvement in both scalability and expressivity for us at Meta. On facebook.com we were able to bring down our CSS bundle from tens of megabytes of lazy-loaded CSS to a single bundle of a couple hundred kilobytes.

We created StyleX not only to meet the styling needs of React developers on the web, but to unify styling for React across web and native.

How does Meta use StyleX?​

StyleX has become the preferred way to style components for every web surface within Meta. StyleX is used to style React components for every major external and internal product at Meta including Facebook, WhatsApp, Instagram, Workplace, and Threads. It has changed the way we author components, and resolved the issues our teams previously had with not being able to encapsulate and scale their styled components.

We expanded the original capabilities of StyleX so that engineers at Meta can use StyleX to author both static and dynamic styles. Our teams are using StyleX theming APIs to develop "universal" components that are themed to take on the appearance of different design systems used within different Meta products. And we're gradually expanding support for cross-platform styling, thanks to StyleX being aligned with the principles of encapsulation introduced by React Native's styling system.

Open Source​

What we're open sourcing is what we use internally. We develop on Github first and sync it back to Meta. Although StyleX was originally created at Meta for Meta, it is not specific to Meta.

That said, this is still just the beginning. We look forward to working with the community to introduce further optimizations and more integrations.

We hope you love using StyleX as much as we do. ❤️