StyleX: Meta's Build-Time CSS-in-JS System for Large-Scale UIs

What StyleX Does and Who It Is For

StyleX is a styling system for React applications that processes style definitions at build time. Instead of injecting styles into the DOM at runtime, a Babel transform compiles `stylex.create()` calls into atomic CSS class name references and writes the corresponding CSS to a separate file during the build.

The primary motivation, as described in the documentation linked from the README, is performance at scale. When many components share the same style values, atomic CSS reuses the same class for the same property-value pair across components. The total CSS output grows slowly as a codebase grows, rather than proportionally with the number of styled components.

The library was developed inside Meta for facebook.com and instagram.com before being open-sourced. The README describes it as a library for ambitious user interfaces, targeting engineers who build large, long-lived React applications. Engineers who build small sites or who want utility-class authoring in HTML without a build step will find it a poor fit.

How StyleX Compiles Styles at Build Time

The core pattern uses `stylex.create()` to define a map of named styles, then `stylex.props()` to apply them to an element:

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

const styles = stylex.create({
  root: {
    padding: 10,
  },
  element: {
    backgroundColor: 'red',
  },
});

const styleProps = stylex.props(styles.root, styles.element);

At build time, the Babel plugin in `@stylexjs/babel-plugin` rewrites each `stylex.create()` call. Each property-value pair becomes an atomic CSS class. The `stylex.props()` call resolves to an object with a `className` property containing the final set of class names and potentially a `style` property for dynamic values.

Because the transform runs at build time, style merging conflicts are resolved deterministically. When `stylex.props(styles.a, styles.b)` is called and both define `padding`, the last one wins, and the output contains only one padding class name.

Installing StyleX and Setting Up a Build

The core package is `@stylexjs/stylex`. The README points to its dedicated README in `packages/@stylexjs/stylex` for installation and API documentation. The monorepo manages packages via Yarn workspaces.

To use StyleX in a project, install the runtime package and the build tool integration. For Babel:

yarn install
yarn build

The monorepo uses `yarn workspace <package-name> build` to build individual packages. The `examples/` directory contains working configurations for Bun, esbuild, Next.js, React Router, Rollup, Rspack, Storybook, SvelteKit, Vite, Waku, and Webpack. Each example is a self-contained project demonstrating the integration.

The unplugin at `@stylexjs/unplugin` provides a framework-agnostic build tool integration that works with Vite, Rollup, and Webpack through a single package.

The Monorepo Layout and Available Packages

The repository is a Yarn monorepo. The `packages/` directory contains the public packages: `@stylexjs/stylex` (the runtime), `@stylexjs/babel-plugin` (the transform), `@stylexjs/cli` (a command-line tool), `@stylexjs/eslint-plugin` (lint rules for StyleX patterns), `@stylexjs/postcss-plugin`, `@stylexjs/rollup-plugin`, `@stylexjs/unplugin`, and a `style-value-parser` package.

The `examples/` directory is the fastest way to see a working integration. The `examples/example-nextjs/` directory shows a Next.js configuration. `examples/example-vite-react/` shows a Vite configuration. Each example directory has its own package.json and build script.

The Flow type checker is used alongside TypeScript in the repository. The `flow-typed/` directory and the `.flowconfig` file show that Meta's internal use of Flow is present in the open-source repository. Teams that only use TypeScript will need to rely on the TypeScript definitions rather than the Flow types.

Limitations and Trade-offs

StyleX requires a build step. It is not usable as a pure runtime library where you pass a style object to a component without a Babel or bundler transform. The README states that the goals and architectural principles are documented at `stylexjs.com/docs/learn/thinking-in-stylex/` and recommends reading them before proposing API changes.

Dynamic styles based on arbitrary runtime values are limited. Styles must be definable statically at build time. Patterns like constructing a color value from a runtime variable that is not a CSS custom property require a different approach than libraries such as styled-components or Emotion, which accept any JavaScript expression as a style value.

The ESLint plugin is provided to catch misuse patterns at development time, but using it requires adding `@stylexjs/eslint-plugin` to your ESLint configuration. Without it, mistakes in style definitions produce build errors rather than friendly editor feedback.

Tailwind CSS as an Alternative

Tailwind CSS is the most frequently compared alternative in search data for StyleX. Both produce atomic CSS, but the authoring model differs. Tailwind uses utility class names written directly in HTML or JSX templates: `className="p-4 bg-red-500"`. StyleX uses JavaScript object syntax in a `stylex.create()` call. Tailwind does not require a custom Babel transform; it scans files for class names and generates a CSS file. The tradeoff is that Tailwind class names are not type-checked, while StyleX style objects can be validated by the TypeScript types.

For projects already committed to a JavaScript-first authoring model where styles are co-located with components in TypeScript files, StyleX provides better type safety than Tailwind. For projects that prefer utility-first HTML authoring, Tailwind is simpler to set up.

Editorial conclusion

StyleX fits teams building large React applications where CSS specificity conflicts and runtime style injection costs are real problems. The build-time compilation model means no style injection at runtime and predictable, mergeable class names. It does not fit projects that need dynamic styles computed at runtime from arbitrary JavaScript values, or teams that want utility-class HTML authoring without a build step. Before adopting StyleX, verify that your build tool is supported in the examples directory: integrations exist for Babel, Webpack, Rollup, Vite, Next.js, Rspack, Waku, and SvelteKit, but each integration is a separate package with its own configuration.

Frequently asked questions

Official sources

1. facebook/stylex on GitHub
2. License: MIT
3. Project website
4. README
5. Releases