New Renderer Interop Layer

[cipolleschi]

Important

Exciting changes for the Interop Layers from 0.74. Read more here

TL;DR: With React Native 0.72, we are releasing an interop layer for both Android and iOS to use non-migrated libraries on New Architecture apps. This post describes what it is, how to use it, and it serves as a way to collect feedback.

Hi all,
We’re excited to share that React Native 0.72 will ship with an interop layer to use legacy components in the New Architecture.

What it is

The interop layer is a feature that lets you reuse legacy Native Components in New Architecture apps, without the need for them to be migrated. It’s a platform layer that allows you to register legacy components into the New Renderer (aka Fabric) and it maps legacy function invocation (for example, the setters for specific properties) to the equivalent in the New Renderer (the updateProps function).

You need to explicitly opt-in on a component basis to use this layer. Which means that you’ll have to list your components in a specific file in order to load them in the New Architecture.
Please note that this layer is experimental. There could be several edge cases not yet covered.

Please, report them as a comment in this discussion.

How to use the interop layer

The interop layer is shipped with React Native 0.72. If no components are registered, it does nothing.
The only step required to use it is to register a component in the layer.

To register a component, you have to edit the react-native.config.js file in your application project to list the legacy components required by the app, in the Android and iOS sections:

module.exports = {
    project:{
      android: {
        unstable_reactLegacyComponentNames: [ "ComponentName" ]
      },
      ios: {
        unstable_reactLegacyComponentNames: [ "ComponentName" ]
      }
    },
  };

Technical Background

To embrace the New Architecture completely, an app has the strong requirement to have all the Native Components migrated to the new Native Components system and to the New Render (Fabric). The migration of Native Components to the New Renderer is complex, requires a lot of time and usually can not be automated as the paradigm is completely different. The result is that it’s very hard for apps to start using the New Architecture.

Under these hypothesis, we decided to share an interop layer between the legacy and the New Architecture that we’ve been using internally for some of our products to facilitate the migration.

The interop layer is effectively a wrapper that allows your legacy component to work with the New Renderer.

Under the hoods, whenever a prop is updated or a command sent, it is forwarded to the UIManager of the New Renderer. The UIManager sends the message to the wrapper which takes care to convert it to a format that the legacy architecture can understand and it lets the legacy component handle it. It then back-propagates the message to JS, updating the UI.

Supported Features

Currently, the supported features of the interop layer are:

• Props
• Events
• Native View Commands (i.e. using UIManager.dispatchViewManager)
• Native Methods described in the website (setNativeProps and measure* functions)
• Exporting Constants to JS

Limitations

We know that there are some use cases that we are not covering yet. We will analyze them case by case and we will decide whether to implement them in the interop layer or not, based on how common the use case is and how hard will be to implement it w.r.t. properly migrate the component to the New Architecture.

Please, report them as a comment in this discussion.

So far, we know that the following features are not implemented or for which we may not guarantee a perfect execution:

• Concurrent Features (such as startTransition) => They should not work in the interop layer. If they do, is for an accident. We can’t guarantee that they will work in all the situations, and you should definitely not rely on the interop layer for those features.
  These features require a proper migration to the New Renderer to work correctly, and we cannot fully support them in the interop layer due to architectural limitations.

The Interop Layer in Action

Before

Before the interop layer, when you were trying to use a Legacy Component on the new Architecture, you would have seen something like this:

Android	iOS

Those pinkish views are indicating that the component is not compatible with the New Renderer and the library maintainer need to migrate it to be used in the New Architecture.

Adopting the interop layer

To adopt the nRIL, you just need to:

1. Open the react-native.config.js of your app.
   1. If you don’t have one, create it with the following structure:

module.exports = {}

1. Update the file, adding the following lines (in our case RNCAndroiddialogPicker for Android and RNCPicker for iOS):

module.exports = {
    project:{
      android: {
        unstable_reactLegacyComponentNames: [
            // list of conponents that needs to be wrapped by the interop layer
        ]
      },
      ios: {
        unstable_reactLegacyComponentNames: [
            // list of conponents that needs to be wrapped by the interop layer
        ]
      }
    },
  };

1. Build and relaunch your app with yarn android (or npm run android) or yarn ios (or npm run ios).

After

After relaunching the app, you should see the actual component in place of the pinkish view of before:

Android	iOS

What’s Next

As highlighted in the Limitations section, we are aware that the interop layer is not complete. We are not aiming to make it 100% complete as, to leverage all the new features we are going to develop, we need that all the native components in the ecosystem are properly migrated to the New Architecture, avoiding invocation to functions that do not work well with the New Architecture.
However, we want to learn about the use cases when the interop layer fails short: we will evaluate them on a case-by-case basis and we can decided to support some of those if the use case is widely spread or very easy to implement.

So, we need you!

If you can, take some time to test this layer and report here use cases when it doesn’t work. For each of them, please add a short description and a way to reproduce it, so we can double-check the example and understand how to move forward.

Thank you so much!

[mrousavy]

This is pretty awesome!

As for the roadmap, do you have any plans for when to remove the compatibility layer again?

[cortinico]

do you have any plans for when to remove the compatibility layer again?

We'll keep the interop layer for the foreseable future. We're not going to drop support for the Old Architecture in the immediate future, and we received several feedbacks that this kind of interoperability layers are needed to support a smooth migration.

[numandev1]

awesome

[alfonsocj]

This will help greatly when only a few native dependencies don't support the new arch yet!
I just tested it with an old non-fabric compatible version of @react-native-community/datetimepicker and it worked great. Then I upgraded to the latest which supports fabric (without removing RNDateTimePicker from unstable_reactLegacyComponentNames) and I noticed that it uses fabric instead of the Interop Layer (awesome! 🙌). I'm not sure if the level of effort is worth it but a minor tweak would be to show a warning for having unstable_reactLegacyComponentNames when a fabric compatible module is already being used.

[cortinico]

Sadly, it's C++ land so as of now it would instacrash the app if we add a fatal there. We can working out something more user friendly for the future though

[cipolleschi]

Preview for iOS:

• Warn users when a component is registered in Rendere and in the interop facebook/react-native#38089

[kelset]

@cipolleschi do we want/need to backport this to 0.72 branch?

[cipolleschi]

potentially yes, If I manage to land this before tomorrow EOD.
There is another PR coming to fix facebook/react-native#37905

[kelset]

I'll add both in 0.72.1 so that we can keep track nvm you already did that 🤣

[numandev1]

I think we can use strong regex to detect which package or library is using a legacy component or not instead of finding and writing it in unstable_reactLegacyComponentNames
we can do this on post-install of node_modules. maybe we can add this functionality in cli level

[cortinico]

Nope because that's against the philosophy of the interop layer. We want the users to explicitely register a component there so they know they opted-in into this layer. We won't be adding a regex mechanism there as, if we decide to ship this change as stable, we might just remove the registration mechanism entirely and do the component discovery automatically.

[numandev1]

discovery automatically would be very good. I was thinking about the doctor command to list legacy and New Architecture components, checking one by one component in existing projects is harder. thanks for explaining

[joemun]

The interop layer is really great. I did have a question about events interop, as implemented here: facebook/react-native#37059

As described in that PR, in Fabric, all event names need to be prefixed with the word "top". In that PR, it looks like the normalization logic to prepend "top" only applies to bubbling events, and not direct events. Is this intentional? Pre-Fabric, I don't believe the "top" prefix was required for direct events.

To provide a specific example, the interop feature wasn't working for the stable version of react-native-video (v5.2.1). I was able to get it to work by doing 2 things in a fork of the library:

1. renaming the component name from "RCTVideo" to anything else without the "RCT" prefix (which I presume has to do with "RCT" being a reserved prefix for core RN components)
2. prefixing the event names returned from getExportedCustomDirectEventTypeConstants() with "top".

I'm wondering why the "top" normalization was performed only for bubbling events? Given that this naming convention was not required for direct events prior to Fabric, doesn't that mean the interop layer won't work out of the box for libraries using direct events?

Thanks!

(in case it helps illustrate my experience, here are my changes in a fork of react-native-video: discord/react-native-video@4baa987)

[cipolleschi]

That's definitely possible, but the parts in C++ and in the ReactCommon folder are usually shared between iOS and Android, so if the issue was there, I expect for it not to work on iOS as well... So, prolly, the actual problem is somewhere in the Android side.

[TheRogue76]

Lottie maintainer here. Maybe i can give a bit more of a context.

The way Lottie works is we have the RCTView from the react native side as a parent view, and then we have a child Lottie view from lottie-ios and lottie-android. We use take the boundry properties of the RCTView and apply them to the child, along side some other APIs that we expose.

We do support the new architecture, but at the moment, we are running into a problem that the bounds and frame property of the RCTView on iOS are returning an empty CGRect for the Json source. The Json source works like the rest of the sources (they all use the same function for attaching the Native Lottie View) with the only major difference being that since RN auto loads JSONs into the js side, we need to stringify on JS, pass it along and parse it on the native side.

We are working on trying to figure out what is wrong, but we are running into issues of Xcode's native debugger crashing when we turn on the new arch, so it is taking a bit longer than expected. I would love to hear any sort of feedback to see if we are doing something wrong here, but it might not be related to the scope of this issue. Let me know if i should move it somewhere else.

[cipolleschi]

@TheRogue76 thanks for the context. IIUC you are:

• requiring the lottie JSON in JS-land, which has some bounds and frame properties
• stringifying
• sending it over to native
• parsing it
• and try to use it in the native view, but the bounds and frame props are now empty

Or the empty CGRect is somewhere else completely?

Xcode's native debugger crashing when we turn on the new arch,

I'm not experiencing this at all! 😮 does it provide some kind of errors or just everything crashes?

[TheRogue76]

@cipolleschi No. The bounds and frame are read from the Parent RCTView itself (It is part of UIView's interface that RCTView has to implement). The reasoning is so that when the layout is calculated via yoga, we would be able to read it from there without any sort of need to interactions with the underlying RN stuff. We just have setters in place for those two values so we can update the native lottie view's sizing every time those calculations change.

The problem right now is that the behaviour seems to have changed slightly. On Paper, the setter for both frame and bounds are called correctly whenever the value changes:

On Fabric however, it seems like the frame is set multiple times, but bounds is not called at all:

Hence the breaking of the child view. Problem is, as far as we have been able to reproduce it, it only happens with the JSON source, and the setter for bounds is NOT called, even though we can observer that their values have indeed changed.

This is the function that is called at the end of every implementation of source (be it setSourceName, setSourceURL, setSourceDotLottieURI or setSourceJson):

[TheRogue76]

I'm not experiencing this at all! 😮 does it provide some kind of errors or just everything crashes?

Just a bunch of lldb-rpc-server crash logs. Mostly segment faults, but a bit above my knowledge of cpp so i cannot figure out what is happening. I can share them if you need.

[alexhernandez]

@cipolleschi, I think the interop approach is a great idea.

One challenge I've run into with the RN Interop layer is determining the suitable component name for 'unstable_reactLegacyComponentNames' as the 'package.json' name is not currently accepted.

While visual elements like the React Native Picker offer clear identification (pink bounding box), how can we identify keys for non-visual libraries since it doesn't seem to be standardized across iOS and Android?

For instance, how could developers find the necessary key for 'unstable_reactLegacyComponentNames' when dealing with libraries like React Native Cookies or React Native Netinfo since neither has a visual element that could help identify its key?

[cipolleschi]

Fabric is a renderer, so it has to render stuff on screen... If a library has no visual elements, we could argue that it should not go through the Fabric Interop Layer, right?

The New Renderer Interop Layer was born to use legacy Native Components in the New Architecture. If you are not working with a View Component, this interop layer does not make much sense.

For NativeModules, we will ship interop layers in 0.73. Consider that Legacy Modules works flawlessly in the current New Architecture..

[joemun]

@cipolleschi question regarding your statement:

For NativeModules, we will ship interop layers in 0.73. Consider that Legacy Modules works flawlessly in the current New Architecture..

If legacy modules already work today (alongside Turbo Modules) with New Arch enabled, mind elaborating on why there will be an interop layer?

[cortinico]

If legacy modules already work today (alongside Turbo Modules) with New Arch enabled, mind elaborating on why there will be an interop layer?

Legacy modules are working today as the New Architecture, as you experience it today, still has the bridge running. So those legacy modules still use the bridge to work.
Once we turn off the bridge, the won't be working anymore, that's why we're working on a Native Module Interop Layer to support those scenarios

[coofzilla]

so with the release of 0.74 and bridgeless mode, for non visual native modules, will they work out of the box using this native module interop layer? is there any documentation or discussion on this?

I saw this

Together with Bridgeless Mode, we're shipping a Native Module Interop Layer, that will allow you to reuse your old modules when in Bridgeless Mode.

I just want to confirm that I can upgrade to 0.74 use the new architecture/bridgeless mode without deprecating my native modules that use the bridge in the process. 😅

[cortinico]

I just want to confirm that I can upgrade to 0.74 use the new architecture/bridgeless mode without deprecating my native modules that use the bridge in the process. 😅

That's correct. If your native modules don't work on bridgeless mode is either:

1. A bug in the interop layer that we'd love to fix.
2. A known limitations of the interop layer that we'd like to document
   Otherwise things should just work.

So @coofzilla if you get any problems, please let us know with a bug report and we'll look into it.

[ngocle2497]

The interop layer is a great ideal. But i think if we can add unstable_reactNewArchComponentNames for old arch to use some component on new arch will be good for migration. Ex: I can use some component with fabric on production mode(app ready on store) to get more feed back about new arch.

[cipolleschi]

Hi @MasonLe2497, thank for your comment.
I'm not sure I'm completely getting the suggestion though: you are asking to be able to use New Renderer components in the Old Architecture?

This effort will require us to actively work on the Old Architecture to support running New Components in it, something we are not interested into as we want to remove the Old Architecture as soon as we can. Also, those new components will run in a setup which is much different with the one where they will be used, because the would be rendered by the old Renderer, so the feedback would be not precise.

Finally, as per my knowledge, I'm not sure that there are a lot of New Renderer-only components in the OSS right now. I feel that in most cases we have components that can run on both architecture. Do you have a list of New Renderer-only components? I would be interested in looking into them.

[Yandamuri]

Interop Layer is indeed great solution for non migrated libraries. But the question is how long this Interop Layer is supported? because some library maintainers might take longer time to migrate as the process complex.

[cortinico]

At the time being, we're committed to supporting the various Interop Layers we've released. We haven't announced any deprecation date and we're not planning to deprecate them in the foreseable future

[maya-salcedo]

Really big thank you. This Interop Layer works for me. After adding the components' names in react-native.config.js, I had to:

1. Delete the ~/Library/Developer/Xcode/DerivedData" folder
2. In the ios folder, run pod deintegrate && bundle install && RCT_NEW_ARCH_ENABLED=1 bundle exec pod install

[CptFabulouso]

Hello, I've been trying out a lib on new arch before doing anything (private repo, sadly can't share), expecting to see the pinkish box, but everything renders as it should. I see fabric is enabled in console log. In what cases the pink box appears? Just trying to understand that. The lib was created using react-native-builder-bob (0.30.0), using the old arch options during init, I did not follow any new arch instructions during development.

Secondly, can I get a clarification on this:

To register a component, you have to edit the react-native.config.js file in your application project to list the legacy

Link that got me here was about migrating a library, not application. Is react-native.config.js file created in library reflected during build? Or does the app owner need to create/modify their file?

[cipolleschi]

@CptFabulouso In the newer versions of React native, the Fabric interop layer is completely automatic.

It means that if you have a component that is not migrated to Fabric and you try to render it, the interop layer wraps it in a component that is Fabric compatible and forwards all the methods calls and the props update to the old component.

There is no need to register components manually anymore and the expectation is not to see any pink box anymore as well.

If everything works fine, the interop layer is doing its job well! 😄

[CptFabulouso]

Alright, that's nice, thanks for response! :) I just found out it's mentioned under the link at the top, maybe it could be mentioned here already. I was already deep in many links before I got here and you just gotta stop somewhere :D

[WilliamPeralta]

I added the configuration file and now it works only the first time, that is, when I open the map (react-native-maps) for the first time after closing the app it works. If I continue the navigation and return, they no longer appear. I have to completely close the app and reopen it. The same happens if there is an hot reload. :(

[cipolleschi]

you should not need any configuration file. Can you prepare a reproducer using this template?

[salah-ghanim]

@cipolleschi here is an example where the bug is visible:
https://github.com/salah-ghanim/nested-interlopbug/tree/main

and the result of my analysis in this comment:
react-native-maps/react-native-maps#5206 (comment)

summery: introplayer doesn't play nicely when two interop views are nested inside each other because first view consolidation / render happens, and it picks the interop view as a child view instead of the real view to be rendered (paperview)

triggering re-render on the native side does help solve it but since interop logic is private / can't be extended I couldn't come up with a clean solution.

it would be amazing if:

1. the bug itself is solved in the interop view (android implementation works somehow)
2. there is a way to customize the interop functionality to find ways to manage the render of the paperview manually

tldr, nested interopviews lead to the native state being 1 state behind the react-native / js state.

[cipolleschi]

thanks, can you open a proper issue with those reproducers on the react-native repo? In this way we are sure to track it and we can work on that.