RFC: React Native WebAPIs

[tido64]

Abstract

React Native currently lacks a well-defined, stable and complete API surface. Compared to what both Android and iOS provide out of the box, React Native core is missing quite a lot today. To fill that gap, we have a "wild west" of community modules, each with its own set of interfaces and behaviors. While this is in line with the broader experience in the web/npm space, at the end of the day this means that it is the developers' responsibility to find modules that fit their needs and that are seemingly actively maintained.

Additionally, the APIs are not compatible with Web APIs, thus closing the door to a wealth of open source libraries that do not have explicit React Native support. This often means that developers cannot reuse existing web code, and must search for or even create one for their needs.

In this RFC, we are proposing to close this gap by providing our own implementation of the Web APIs for React Native. The ultimate goal is to open the possibility to run non-UI code directly in a React Native app; to provide a familiar environment for existing web developers as well as a well-documented API for developers of any experience level.

Click here to read the rendered version

---

This RFC is meant to be complementary to React DOM for Native

[NickGerleman]

This overall proposal makes a lot of sense.

Inside of React native, a similar sort of polyfill organization (registered differently) was used for Performance APIs.

1. https://github.com/facebook/react-native/blob/main/packages/react-native/Libraries/WebPerformance/Performance.js
2. https://github.com/facebook/react-native/blob/main/packages/react-native/Libraries/Core/setUpPerformance.js
3. https://github.com/facebook/react-native/blob/main/packages/react-native/Libraries/Core/InitializeCore.js#L31

[necolas]

I think it's important for this to live in the react-native repo and not be another 3rd party project that people have to go looking around for to find modules. My position is that the DOM/Web APIs is the long-term future of the maintained RN JS APIs, and it's critical that they be hosted and maintained out of the main monorepo infra.

[kelset]

hey @necolas, it's great to know that we are very much aligned in exploring this direction 🤗 about this specific angle of where the code should live, while I agree that in the long-term all this xplat code should live together, I think that while this is still very much experimental it'd be better to keep it somewhere else, and then potentially migrate it in the react-native repo if/when we validate that it's viable.
I'm concerned that moving the code into rn now will create a lot of overhead in both maintenance and contribution speed, and during this first experimental phase we want to be able to move swiftly without worrying inadvertently breaking something else.
Let's chat again about this further down the line?

[necolas]

Depends how long "experimental" goes on for. We're currently greatly slowed by a lot of past forking and out-of-repo initiatives, and have long and complicated projects to defork those things. That needs to be avoided with new work.

We also have existing Web APIs that we've implemented and they're not separate repos or projects either. They'll be highly dependent on new internals like an event loop model and native extension points, so being out of core will make it harder for Web APIs with those needs to be tested and inform development.

Curious to hear @rubennorte's thoughts

[rubennorte]

@necolas I think colocation is more critical for APIs that interact with internals from RN (like all the DOM traversal & layout APIs that interact with Fabric), but it might not be as important for standalone APIs like Battery, etc. that could be easily implemented as a userland module. I agree with the general direction of eventually having this provided by the framework out of the box, but I don't think it's that important at this point (and it'll help with iteration speed).

[necolas]

Agree that having auto-magic setup would be a great DX, and an essential part of opening up RN to developers coming from Web in the future.

[necolas]

We've been implementing MutationObserver and IntersectionObserver. Some Web APIs like those will come up against differences in the execution model of React Native vs Web, and we're working on an RFC to address that as well.

[kelset]

another note: to help us prioritize against our internal needs, we've been creating a tool to help us scrape a codebase to find usages of every WebAPI so that we can be data-driven #2621

[necolas]

Exciting to see this proposal and how complementary it is to other API convergence efforts. I appreciate the attention given to ideas for native app tooling as well. What are some of your next steps? Are you already prototyping the battery API using this approach?

[tido64]

What are some of your next steps? Are you already prototyping the battery API using this approach?

We've got a prototype working here: #2590. To make this work smoothly, we will need a few more things as I've mentioned in #2504 (comment).

[rubennorte]

I've been thinking about this too but the direction I was considering was a bit different. If we use the dependencies listed in package.json and the current autolinking approach, we might end up including JS and native code in the binary that's not actually used. The approach I was considering instead was doing 2 things:

1. Use metadata generated by Metro during bundling to know what native modules are actually used in the code. Use that information for autolinking (so a module that's installed but not actually imported in the bundle would not be included).
2. Use a Babel transform to automatically replace the browser API with imports to the native modules. E.g.:

// From
navigator.getBattery();

// To
require("@react-native-webapis/battery-status").getBattery();

Optionally, we could also make it so the resolved module is configurable by the user, so we can actually swap implementations whenever necessary.

[tido64]

Hi @rubennorte! Thanks for your feedback. I had some thoughts around these approaches as well (that I probably should put somewhere in the document),

1. You're right that current native autolinking is too naive. Your proposal makes sense — the only thing I would add is that we probably still need to keep the current approach as fallback for when there is no bundle e.g., because a dev server is used. Somewhere in this document, I mentioned a tool for telling authors that they're using a Web API that has not been polyfilled and either suggest or add a reasonable library. This same tool should be able to produce the metadata you mentioned.
2. Our current approach is to inject the polyfills at the beginning of the bundle. This approach simple to implement, but doesn't allow for tree shaking like yours does. Do you think replacing calls is something that we can perform with 100% accuracy? How do we know navigator doesn't refer to something else? I think the same problem applies to Range and other APIs? I'm not so well-versed in Babel or AST manipulation in general, so please forgive the dumb questions.

I'm thinking that we want to align with the behaviour of native autolinking i.e., we should allow autopolyfilling to be disabled via the very same mechanisms. If we can tell people that it works the exact same way native autolinking does, that will reduce cognitive load. We should aim to fix native autolinking behaviour as necessary. I'm a bit wary of introducing yet another concept and making it hard to debug/wrap your head around.

[rubennorte]

the only thing I would add is that we probably still need to keep the current approach as fallback for when there is no bundle e.g., because a dev server is used.

Yeah, I think there are cases where forcing this is reasonable (including when using OTA), so we definitely need a way to force certain native modules to always be included regardless of whether they're used or not. We probably shouldn't be doing that by default though.

In the future, if we shipped the browser APIs with RN, we could have an option in the RN config like:

browserGlobals: {
  select?: 'detected' | 'all' | 'none',
  include?: Array<string>,  // doesn't work with 'all'
  exclude?: Array<string>, // doesn't work with 'none'
}

Somewhere in this document, I mentioned a tool for telling authors that they're using a Web API that has not been polyfilled and either suggest or add a reasonable library. This same tool should be able to produce the metadata you mentioned.

I think that tool would be useful but only in the case we discussed before (using OTA or SSR). For the metadata, my approach was about native modules, not about Web APIs specifically (which has the added benefit of reducing bloat in a broader set of cases).

Our current approach is to inject the polyfills at the beginning of the bundle. This approach simple to implement, but doesn't allow for tree shaking like yours does. Do you think replacing calls is something that we can perform with 100% accuracy? How do we know navigator doesn't refer to something else? I think the same problem applies to Range and other APIs? I'm not so well-versed in Babel or AST manipulation in general, so please forgive the dumb questions.

We can tell if the reference to navigator is global or if it's redefined/imported from another module. The only requirement from this would be that you use it directly (as in navigator.getBattery()) instead of using indirection (e.g.: const {getBattery} = navigator; getBattery();).

I'm thinking that we want to align with the behaviour of native autolinking i.e., we should allow autopolyfilling to be disabled via the very same mechanisms. If we can tell people that it works the exact same way native autolinking does, that will reduce cognitive load. We should aim to fix native autolinking behaviour as necessary. I'm a bit wary of introducing yet another concept and making it hard to debug/wrap your head around.

I think it's fair to focus on the current capabilities in RN to implement this, but we need to make sure it wouldn't conflict with the direction that we want to take in the long term.

[rubennorte]

See my previous comment about autolinking and how it could completely solve the discovery problem :)

[rubennorte]

cc @motiz88. Flagging in case you have any concerns about this.

[rubennorte]

@tido64 could you use a specific example here? I'm not sure I understand the shape of this config 100%.

[tido64]

At the moment, there really isn't much else to it. We're building on top of the existing autolinking schema as defined in the CLI: https://github.com/react-native-community/cli/blob/main/docs/autolinking.md#what-do-i-need-to-have-in-my-package-to-make-it-work

Just to be clear, this react-native.config.js lives in the module package. Not in the app project.

[kelset]

thanks everyone for your inputs! this has made the RFC so much better - you can keep up with the actual coding work over in the issues section and the webapis folder of the repo: https://github.com/microsoft/rnx-kit/tree/main/incubator/%40react-native-webapis