Using RSD for web-only apps

[necolas]

React Strict DOM (RSD) was conceived to natively run components and hooks that teams at Meta created for React web apps like Facebook and Instagram. Most of the engineering behind RSD needs to take place in React Native, and in the user-space polyfills of features that we hope will eventually make their way into native as the RSD target API approaches completion. The web side of RSD is far simpler and essentially complete; it can be thought of as a forward-looking integration of React DOM with StyleX.

React on the web at Meta

The teams at Meta have found great success in using StyleX alongside using modern React APIs. The historical challenges that engineers and apps at Meta faced with prior styling solutions (essentially an internal version of CSS Modules) were documented by @vjeux in his influential presentation React: CSS in JS, which described the thought process behind the development of what would become React Native's StyleSheet API. StyleX is the spiritual successor to StyleSheet and it resolved all those issues our team's faced on the web, while delivering enormous performance wins to users.

Most of the React-based product engineering at Meta uses component libraries - a higher-level abstraction than React DOM components. For those engineers, styling components on the web is relatively simple and terse. Here's a representative example:

import stylex from 'stylex';

const styles = stylex.create({
  root: { ... },
  button: { ... }
});

export function ProductComponent(props) {
  return (
    <ProductItem style={styles.root}>
      <DesignSystemButton style={styles.button} />
    </ProductItem>
  );
}

The engineers that spend the most time working with components like div and APIs like stylex.props are the ones working on the company-wide design systems and product-level component libraries that products use. In this scenario, styling components is a bit more verbose, for example:

import stylex from 'stylex';

const styles = stylex.create({
  button: { ... },
  text: { ... }
});

export function DesignSystemButton(props) {
  return (
    <button {...stylex.props(styles.button, props.style)} type="button">
      <span {...stylex.props(styles.text)}>{props.children}</span>
    </button>
  );
}

Introducing code transforms to allow engineers to write <span style={styles.text}> or perhaps <span css={styles.text}> is fraught with difficulties, as the expectation when using React DOM's magic global components is that they conform to the React DOM API. And we still have some files that use legacy StyleX APIs as well as legacy non-StyleX styling solutions.

RSD on the web at Meta

Instead of magic global components, RSD components are imported as html from a package (aliased to h in the example below). The introduction of RSD had to be done in a way that allowed safe, incremental adoption within web design systems and apps. Converting an existing React component to support running on native has to come with near zero chance that a regression on web can occur. Especially because the design system components using RSD are most heavily used by web-only apps that are not experimenting with running on native platforms. We even wanted to allow engineers to partially convert components, so they could transition code as slowly or quickly as they needed to. Therefore, an attempt at widespread repurposing of existing React DOM components was a non-starter. Instead, our UI infra team wrote a codemod that allows teams to convert specific components to use RSD and html.* elements.

RSD was an opportunity to introduce some DX improvements around using StyleX, and revisit some legacy patterns that existing in React DOM. StyleX styles are passed to the style prop, as we require no direct use of className or dynamic styles defined outside of StyleX. This allows us to simplify the authoring experience for UI infra engineers, and unifies how styles are passed as props to "primitives" (e.g., html.div) and custom components - everything uses the style prop. Doing this also allows us to better polyfill StyleX on native, where some styling APIs are implemented as component props.

import stylex from 'stylex';
import { html as h } from 'react-strict-dom';

const styles = stylex.create({
  button: { ... },
  text: { ... }
});

export function DesignSystemButton(props) {
  return (
    <h.button style={[styles.button, props.style]}>
      <h.span style={styles.text}>{props.children}</h.span>
    </h.button>
  );
}

We want engineers working on web-only experiences to want to use RSD too, as it's the best way to ensure that products have the option of being run natively on native platforms in the future. The RSD API is a surface that we can use to improve the style authoring experience for our teams on web, as well as experiment with introducing other small changes to props that make native compatibility easier, but can also help us to modernize web code without the risk and cost of making changes to React DOM itself (e.g., disallow or replace legacy React prop names and deprecated W3C props).

Trying RSD in your web app

Meta has 1000s of internal web components that import stylex, and for compatibility we simply re-export the css export from RSD to stylex for native. RSD works with StyleX styles defined using stylex.create, so simply following the official StyleX instructions for web apps is sufficient. However, RSD unifies styling (css) and components (html) in its own API, and you can use this approach in web-only apps too by following the README instructions for how to configure StyleX to map its API to the css import.

import { css, html as h } from 'react-strict-dom';

const styles = css.create({
  button: { ... },
  text: { ... }
});

export function DesignSystemButton(props) {
  return (
    <h.button style={[styles.button, props.style]}>
      <h.span style={styles.text}>{props.children}</h.span>
    </h.button>
  );
}

This is a concise way to try out StyleX and get a taste of what it feels like to have a first-class, integrated styling solution for React on the web (previously only available to React Native users.)