Production readiness and adoption advice.

[axyz]

Hi, I am evaluating different options for a component library that would target react native first, while having web as a mid/long term stretch goal.

Given the commitment and closeness of this project to React Native itself, it seems it could be a good choice.

On the other hand my understanding is that production readiness may not be there yet (especially when it comes to completeness and stability of web API)? It seems this project is to an extent already used internally, but still in a phase of requests for contributions and advocacy for gradual adoptions?

With all this in mind I have some doubts you may help clarifying.

1. Is it safe to assume this library can be used for production RN applications, but maybe not yet for web? Or are there also possible issues/limitations to currently account for that apply to RN apps as well and tradeoffs compared to plain RN or other frameworks?
2. Is gradual/mixed adoption a viable approach? Can html components be mixed with RN primitives? Can stylex Styles be mixed with RN style objects?

Sorry if I missed something from the docs. I think compat could help in reusing RN components (e.g. to use Flash/Flat Lists?).

In any case looking more for a high level recommendation considering I'm in a position where sub optimal web output is acceptable while sub optimal RN output is not, and maybe it could be a good opportunity to adopt and eventually contribute to this project?

Thanks.

[necolas]

React Strict DOM was developed specifically to avoid regressions / rewrites on web at Meta. It enables us to take existing web code, make minor automated changes, and have it render correctly on native for the most part. (See caveats related to limited layout support on native).

Is the API complete and stable on web?

Yes. If you wanted, you could use RSD to build web-only apps, no problem. See the CSS and HTML compatibility tables. Note the line saying "All the APIs listed below are considered supported on Web."

Is the API production ready?

Yes. React Strict DOM is already used in production at Meta to render web components using React Native on VR for Facebook and Instagram. Hundreds of web components were converted to use React Strict DOM, and they continue to render in web apps like facebook.com too.

What are the limitations for React Native?

In many ways, the RSD API is a superset of the capabilities built-in to React Native. Although it is not a total replacement for existing React Native JS APIs, as anything without a web equivalent is by nature not included in a web-centric API. However, we are continuing to add more features to React Native that follow web specs - styles, events, etc. - so the direction of travel is towards the web.

As is the case for any component library built over React Native, there is some runtime overhead. We've done extensive profiling and performance work to minimize this, but some overhead is inherent when you're adding features missing in React Native core. Over time, more of the code in RSD will move into native code within RN core, and performance will improve further. This has already been happening, with no change needed to the public API or effort on the part of product engineers.

How to gradually adopt?

RSD can be gradually adopted by using platform-specific files, as is already common in React Native and Expo development. You can import react-native in files with .native.js extensions, and use RSD in everything else that doesn't have RN dependencies. Or you can import react-strict-dom in files with .web.js extensions, and use RN in everything else that doesn't have web dependencies. Up to you.

There's also a <compat.native> component that can be used to create components with a web-compatible props API that is then translated into RN props to pass directly to RN components. This way you can fork components for native but the users of those components can still pass in web props and styles.

Mixing RSD and RN elements in the same file is not recommended. Don't mix RSD styles with RN styles either - it won't work properly at all if they are both being passed to the same element. Instead, use the compat.native API as documented, where you can do something like this:

import { compat } from 'react-strict-dom';
import { StyleSheet, Text } from 'react-native';

const styles = StyleSheet.create({
  text: { /* styles /* }
});

export component Foo(...props: FooProps) {
  return (
    <compat.native
      {...props}
      aria-label="label"
      as="text"
    >
      {(nativeProps: React.PropsOf<Text>)) => (
        <Text {...nativeProps} style={[nativeProps.style, styles.text]} />
      )}
    </compat.native>
  )
}

Hopefully this explains how to create proper boundaries between RSD and RN, which will ensure UI renders correctly and reduce developer confusion.

[necolas]

Yes using separate files for styles is fine. Using separate files is a broad tool that can be used for many different use cases. You can separate designs, styles, elements for different platforms. Or use it to build your own utilities that replicate things like RN's Platform API, which allows for DCE during builds.

I would say that the pattern of forking within files is probably the worst option, as you have to be careful to author in a way that doesn't interfere with compiler expectations. And testing is more complicated. If you do go that route, I'd build a utility with better ergonomics, like env.web/native, rather than the isWeb() API we've ended up with internally.

The only times you should explicitly define styles in separate files is if you're using some RN-only styles that don't exist on the web and would result in invalid CSS being generated

Let's not push this suggestion. File forks for RN or RSD are not only for compartmentalizing code that is only valid for one platform. It's a more general purpose tool. And people should feel free to develop their own patterns around it

[axyz]

@necolas so if I got it right all these patterns are fine as long as the object passed to css.create is static, or dependent on function arguments. and one can find the abstraction that most make sense for their use cases.

// valid
const styles = css.create({
  web: { display: "inline-flex" }
  native: { display: "flex", alignSelf: "flex-start" }
});

<h.div style={isWeb() ? styles.web : styles.native} />

// valid
const styles = css.create({
  base: (isWeb) => { 
    if (isWeb) return { display:  "inline-flex" };
    return { display: "flex", alignSelf: "flex-start" };
});

<h.div style={styles.base(isWeb())} />

// invalid
const styles = css.create({
  base:  { 
    display:  isWeb() ? "inline-flex" : "flex";
    alignSelf: isWeb() ? "unset" : "flex-start";
});

<h.div style={styles.base} />

Is that correct?

Can you also elaborate more on what you mean with env.web/native? I would also intuitively be inclined on having an isWeb tool, and curious to understand how those example would look like using "env" instead and in what way it would have better ergonomics and make testing easier

[necolas]

Creating a utility like env can work like Platform but avoid developers needing to use string equality checks (which is the downside of how that API is designed in RN)

[axyz]

Got it, so something like

// env.ts
export const isWeb = true;
export const isNative = false;
export const isIOS = false;
export const isAndroid = false;

// env.native.ts
export const isWeb = false;
export const isNative = true;
export const isIOS = Platform.os === "ios";
export const isAndroid = Platform.os === "android";

[nandorojo]

For the record, as someone who has spent the last 5 years building across web and native with one codebase (and having built Solito), I now prefer to use platform file extensions (.native.tsx, etc.) in favor of Platform.OS. It guarantees tree shaking which I like, and lets you keep platform-specific code well-isolated.

It might seem less clean in the moment, but I actually like it. And you can configure VSCode to not auto-import from files with platform extensions so that your imports are always clean.

It's up to you of course, but I actually prefer the file extensions.

My other personal preference is to always treat web as the default file: index.ts, index.native.ts (where needed), etc.

[axyz]

Related question / additional example:

One of the biggest fear I have observed around RN is on performance of long lists. This seems mostly a solved problem currently with FlatList, FlashList and similar. As you mentioned RSD being used in production on instagram and FB, maybe you have suggestions on how to cleanly integrate those components and similar ones.

Based on your example my naive intuition is that with FlatList being a RN exclusive API, we could have something like this:

// VirtualList.ts  (RSD file)

export function VirtualList(props: SharedPropsType) {
  // use something like react-virtualized
}

// VirtualList.native.ts

export function VirtualList(...props: SharedPropsType) {
  return (
    <compat.native {...props}>
      // use FlatList
    </compat.native>
}

and then on other RSD or .native files alike we can just do

<VirtualList doStuff />

Is this correct? Or is there a different pattern/solution you recommend for this use case?

Thanks again for your support.

[necolas]

Yep, something like that is how Meta renders feed items on web and VR. You don't even need the compat.native component unless the component has web props like style. For components with little to no props API, and a simple file fork may be sufficient.

[axyz]

@necolas quick question regarding compat.native. Does that only allows to pass style specifically?

Or is there some mechanism similar to https://www.nativewind.dev/api/remap-props that could allow to pass stylex styles to different props.

In my FlatList example above, that component does not have a style prop, but it has listFooterComponentStyle, listHeaderComponentStyle, and columnWrapperStyle. Would they work out of the box with compat.native? And if not is there a different workaround for these types of components with multiple style props?

[nmn]

Does it make sense to translate this discussion to a FAQ page on the RSD website?

[necolas]

This information is in the docs already