How can we safely migrate a very large CSS Modules codebase to StyleX?

[mjames-c]

I work at a company, Canva, which has a very large CSS modules code base (10k+ CSS Modules files containing 46k+ rule selectors). We are investigating moving from CSS Modules to StyleX. One thing that is currently unclear to me is how we can safely migrate from CSS Modules to StyleX (as a "big bang" migration isn't feasible given the size of the code base).

One idea we've had is updating our build pipeline to have the CSS Modules styles built into a lower priority CSS layer. This would effectively ensure that StyleX styles take precedence ahead of CSS Module styles and would allow us to safely perform a top down migration where we can safely migrate React components which do NOT have a className (or equivalent) prop. The downside to this approach is that React components that do have a className prop couldn't be safely migrated to StyleX as StyleX styles would take precedence over the passed in parent className styles.

If Meta or others are willing to share how they migrated from their old CSS system to StyleX we'd love to hear it

[nmn]

Meta used something very similar to CSS modules before StyleX and we were able to create a script/codemod that was able to automatically convert ~80% of cases.

I think something like that is likely the most effective path forward. I'll try to explain the details I think of, but feel free to ask any follow-up questions.

CSS Layers is a good starting point.

If you configure your tooling to wrap all your existing styles in a CSS layer, and allow stylex styles to "win", that is a good start to have determinism during the migration.

Migrate "large chunks" of files at a time

Generally speaking if an HTML element is all StyleX or all CSS modules, there should be no style conflict. And so you can start doing codemods one feature or part of the app at a time.

Bail out on any complex selectors

You likely have some usage of descendent and sibling selectors in your CSS files. Configure your codemod to bail out of transformation for any such class. Although stylex.when can be used to recreate the same behaviours, it is likely not easy to codemod.

Hopefully the vast majority of your styles do not rely on such complex selectors and should work fine.

Consider using deprecated APIs to bridge the gap

Dealing with non-stylex classNames

If you run into many issues with an automatic codemod, you can consider using some deprecated patterns:

You can choose to use className={stylex.props(...).className} so that you can still combine this with className props where strings are passed in.

OR

You can create a helper function to convert arbitrary classNames into something that stylex.props with accept:

const toStyleXStyles = (classes: string) => ({
  [classes]: classes,
  $$css: true
} as any as stylex.StaticStyles);

Dealing with StyleX styles being passed to components that don't expect them

One of the core issues with incremental migration is that there may be cases where you start passing stylex styles (which are objects) to a component that still expects strings passed in as className.

You can work around this issue with a small helper as well:

const stringy = (styles: stylex.StyleXStyles): stylex.StyleXStyles & string => {
  Object.defineProperty(styles, 'toString', {
    value: () => stylex.props(styles).className,
    writable: false,
    enumerable: false,
    configurable: false,
  });
  return styles;
}

Now, you can do something like <CustomComponent className={stringy(styles.foo)} /> and the styles should work correctly whether or not CustomComponent expect stylex styles. If it happens to treat the prop like a string, the toString() method would be called and the styles would be converted to a class string anyway.

Legacy Media and pseduos

StyleX API expects "conditions" like media queries and pseudo classes (like :hover) to be inside a style value:

color: {
  default: 'black',
  ':hover': 'red',
}

This is more similar to inline CSS than how CSS is often written. So, if you find that you're hitting too many style regressions during the automatic migration, you can use the legacy pattern. StyleX will compile it but give you an ESlint error.

color: 'black'
// DEPRECATED PATTERN
':hover': {
  color: 'red',
}

This pattern may help bridge over situations where you have many classes being passed into components where styles for different viewport sizes are not co-located.

---

The basic pattern for the codemod script would be to

• read each file
• resolve any CSS imports
• read the CSS file and convert it to StyleX
• drop the StyleX code at the bottom of your JS file
• use the original classNames as the namespace names within stylex.create
• Update all the className props to the style references
  • Spread stylex.props on primitive HTML elements
  • pass the style props as is to Custom Components (shown above)

[nmn]

Meta didn't need all these workarounds and was also migrating when some of the legacy APIs weren't legacy yet. But a fairly simple codemod was very successful.

[mjames-c]

@nmn thank you for the detailed response! Very useful (and great to hear you were able to achieve 80% migration codemods!)

If you configure your tooling to wrap all your existing styles in a CSS layer, and allow stylex styles to "win", that is a good start to have determinism during the migration.

For safety we were actually thinking of doing the reverse now, putting all StyleX styles in a layer so that CSS module styles "win". That way parent component passed classNames will take precedence over StyleX styles in the child (if they're applied to the same HTML element).

[mjames-c]

The basic pattern for the codemod script

If possible, it would be great if you could share the codemod (or parts of it) as I'm sure others interested in migrating to StyleX would find it useful. No worries if not, perhaps it's something we'll be able to share out if/when we build our own.

[mellyeliu]

@mjames-c We would be happy to share some generalized utilities that resemble the codemod in functionality, especially the utilities around complex selector detection and CSS rules parsing. The actual codemod itself may have too much noise to be useful because it has logic specific to the legacy system we were migrating from. Let me know what specific parts from the approach @nmn outlined that would be useful.

One idea we've had is updating our build pipeline to have the CSS Modules styles built into a lower priority CSS layer. This would effectively ensure that StyleX styles take precedence ahead of CSS Module styles and would allow us to safely perform a top down migration where we can safely migrate React components which do NOT have a className (or equivalent) prop.

If you want StyleX to win over your CSS modules, you can instead set the useLayers config to false to avoid modifying your build layer to wrap the rest of your CSS in layers. The layers polyfill we use as a fallback bumps StyleX specificity above your other styles as a side effect. Of course, if you want the inverse, useLayers=true will make StyleX be overridden by all non-layered CSS modules code you may have.

[nmn]

I don’t currently have the bandwidth, but I’m considering the possibility of creating codemods to migrate from various setups to StyleX.