Tailwind To Stylex

Migrate Tailwind to StyleX

Convert Tailwind utility classes into StyleX styles: replace className="..." strings with entries in a stylex.create({...}) call, and apply them with stylex.props(...).

This is a behavior-preserving refactor, not a redesign. The rendered pixels should not change. Don't drop styles you can't cleanly convert — flag them (see Step 6) so the user can decide, rather than silently changing the design.

The core mechanic: resolve, then reshape

The reliable way to convert a class string is the same one the tw-to-stylex codemod uses under the hood: resolve each class to the CSS it actually produces, then reshape that CSS into a StyleX object. Don't pattern-match class names to guesses — think in the computed CSS, because that's what has to stay identical.

"px-4 py-2 text-sm font-medium hover:bg-blue-600"
        │
        ▼   resolve to CSS (mind the project's Tailwind version + config)
padding-inline: 1rem; padding-block: .5rem;
font-size: .875rem; line-height: 1.25rem; font-weight: 500;
:hover { background-color: #2563eb }
        │
        ▼   reshape to StyleX (camelCase, conditions as values)
{
  paddingInline: '1rem',
  paddingBlock: '0.5rem',
  fontSize: '0.875rem',
  lineHeight: '1.25rem',
  fontWeight: 500,
  backgroundColor: { default: null, ':hover': '#2563eb' },
}

If a class uses arbitrary values (w-[37px]), the project's custom theme, or a plugin, resolving-to-CSS still works — you read the value straight out of the class or the config. When unsure what a class computes to (custom config, unfamiliar plugin), check the project's tailwind.config / CSS @theme, or resolve it rather than guessing.

Two things that trip up conversions

1. StyleX conditions are values, not rules. Tailwind spreads state and responsive variants across separate rules (hover:, md:, dark:). StyleX instead nests the condition inside the property value, and the default key is required whenever a property has any condition (use null when there's no base value). This is the single biggest shape difference — get it wrong and styles silently don't apply.

// md:flex hover:opacity-80  ->  conditions live on each property
display: { default: 'block', '@media (min-width: 768px)': 'flex' },
opacity: { default: 1, ':hover': 0.8 },

2. Some Tailwind utilities compile to selectors StyleX can't express on one element. space-x-*, divide-*, group/group-hover:*, peer/peer-*:*, and typography's prose all rely on descendant, sibling, or ancestor-state selectors. StyleX styles a single element, so these don't map 1:1. Don't fake them — restructure (e.g. space-x → gap on the flex parent; group-hover → lift state into React or a CSS variable) and tell the user. See references/mapping.md for each case.

Workflow

Work one component (file) at a time so each stays reviewable.

Step 1: Confirm StyleX is set up

StyleX needs its compiler plugin wired into the bundler (Babel/Vite/Next/Webpack/rspack) and @stylexjs/stylex installed — otherwise stylex.props returns nothing at runtime and the migration looks broken. Check package.json and the bundler config. If it isn't set up, read references/stylex-rules.md → "Project setup" and either configure it or tell the user what's missing before converting. Note whether the target is React DOM or react-strict-dom (React Native) — it changes how styles are applied (see the react-strict-dom note in references/stylex-rules.md → "Project setup").

Step 2: Find the Tailwind usage

Locate every className/class in the file, including dynamic ones: cn(...), clsx(...), twMerge(...), template literals, and ternaries. You need the complete set of classes that can apply to each element, and under which conditions, to convert faithfully.

Step 3: Build the stylex.create object

Create one named entry per distinct element/variant (base, label, iconActive…) — descriptive names beat $1, $2. For each, resolve its classes to CSS and reshape (the core mechanic). Apply the StyleX authoring rules that differ from raw CSS:

• camelCase every property (border-radius → borderRadius).
• Longhand + single-value shorthands only. StyleX warns on multi-value shorthands because they cause merge conflicts. Split them: border: '1px solid red' → borderWidth: 1, borderStyle: 'solid', borderColor: 'red'; a two-value padding → paddingBlock / paddingInline. A single-value shorthand (padding: 16) is fine.
• Numbers are px. width: 24 means 24px. Keep other units as strings ('1.5rem', '50%', '100vh').
• Conditions as values with a required default (see gotcha 1). Mobile-first: the unprefixed class is default; sm/md/lg/xl/2xl become @media (min-width: …) keys.
• Full modifier → condition table (states, dark mode, first/last, before/after, arbitrary values, gradients, animations) lives in references/mapping.md — read it whenever you hit anything past plain utilities.