React Native OOT platform API

[douglowder]

Adding notes and ideas here on defining the React Native core API for out-of-tree platform support. I'd really appreciate comments and feedback, to help firm these ideas up into something that could be submitted as an RFC.

(See “Formalize OOT platform concept (Vega, Desktop, TV, etc.)” in the list of projects in-flight in the React Foundation planning document. )

Updated 25 July 2026

Requirements

• Should work for all the existing OOT RN platforms
• Should be introspectable in a consistent way
• Should be namespaced to avoid collisions between APIs that are different (or nonexistent) on the different platforms
• Should be consistent for platforms of the same type
• For RSC purposes, should be client only

Changes to Platform.OS values

• Currently in main we have these allowed values for Platform.OS:
  • ios
  • android
  • macos
  • windows
  • web
  • native
• Suggestions:
  • Remove native (it isn’t really a platform in the same sense as the others, just a way for Metro to identify non-web components)
  • Add new platforms:
    • tvos
    • androidtv
    • vega
    • visionos (?)
    • metaquest (?)
    • webtv (?)
  • Carefully separate the concepts of Metro platform and native Platform.OS
  • Each RN OOT fork would determine the correct platform value for its own implementation, and surface that value in
    • Runtime Platform native implementation
    • Platform-dependent native implementation of APIs
    • Bundle URL implementation (determines platform flag that goes to the packager)
    • Build steps (determines the platform flag used to build the embedded JS bundle)

Platform.Variant

• Define a Platform.Variant API (similar to Platform.OS) that returns whether we are on TV, desktop, etc.
  • Android native already has such an API), that returns the Android specific Platform.uiMode constant.
  • This API defines other variants (car, appliance, watch) that may be useful in future, but as far as I know, are not supported today as React Native platform targets
• Suggested values
  • mobile (default)
  • desktop
  • tv
  • headset
  • web
• The value of Platform.Variant would be determined at runtime, the way uiMode is determined for Android today
• For each Platform.Variant, have a namespace where all OOT platform specific APIs and components live
  • E.g. we would have a top level TV namespace where TVFocusGuideView, TVEventHandler, etc. would now live
  • Similarly for a Desktop namespace
  • All OOT platforms of the same variant would move to implement the same JS APIs, as far as possible
    • react-native-macos and react-native-windows would provide exactly identical APIs in the Desktop namespace
    • react-native-tvos and Vega would do the same for TV
  • We might need a way to allow additional APIs or components needed by a specific OOT platform

Metro considerations

• We need to ensure that a bundle built for a TV platform does not see unnecessary size increases from inclusion of other (desktop, etc.) platform code
• One way to ensure this is to require that each OOT react-native package only include implementations for one variant. Since a given Metro bundle should only include one “react-native”, this will ensure that unused code for other variants is excluded.
• Metro would need to be aware of the new values for Platform.OS and Platform.Variant
• Metro would also need to have changes to its default resolver to correctly pick up source modules with different extensions, including extensions for the variants.
  • By default, the resolutions would look for OS-specific files, then variant-specific files, then general files
  • There may be adjustments for specific platforms to take care of backwards compatibility and other issues
• Some examples of how this might work:
  • For macos platform, Metro would resolve these in order:
    • Component.macos.tsx
    • Component.desktop.tsx
    • Component.tsx
  • For androidtv platform, Metro would also pick up android for backward compatibility
    • Component.androidtv.tsx
    • Component.android.tsx
    • Component.tv.tsx
    • Component.tsx

[Abbondanzo]

+1 native doesn't make much sense as a Platform.OS check but it is more useful from a Metro perspective as highlighted. But there isn't much of a difference between android/androidtv/metaquest--it seems like Platform.Variant is more applicable here.

[Saadnajmi]

I'll add that "we use ".native" extensively to differentiate stuff shared with web. So while it doesn't make sense in terms of just RN, for mixed codebases I think it's more useful. Not sure if we are following an anti pattern though

[douglowder]

@Abbondanzo as I recall, both android and metaquest are supported in RN core, so it makes sense for them to be considered the same platform. But androidtv is not -- it requires a lot of native changes that are only in react-native-tvos fork.

Good point though, we should clarify here the distinction between OS and Variant. OS really means that the native code is distinct enough to require a separate native implementation (usually in a separate repo).

[Abbondanzo]

@Saadnajmi agreed these make great file extensions for Metro--we also use .native.js and .web.js absolutely everywhere--but not as runtime checks--there is no PlatformNativeStatic runtime type to suggest that making a check like Platform.OS === 'native' is possible. What I was leaning into was the idea that Platform.Variant is a great way to provide a bit more granularity like @douglowder is suggesting.

@douglowder for OS, the potential line you could possibly draw in the sand is "OS shares the same Core runtime, Variant is a form factor of that OS". For Android, I can use the same prebuilt runtime across Meta Quest, Android TV, and Android mobile apps but on iOS, I'll almost certainly have different prebuilts for macOS vs. iOS vs tvOS (i.e. AppKit vs. UIKit). Phrasing is not my strong suit and that might be too loose an interpretation of the runtime itself.

As a general rule of thumb, for ensuring dead code doesn't make its way into the bundle, we always try to encourage and lean into Metro's platform-based bundle splitting here. Smaller one-liners are generally okay (i.e bridge API calls, string ternaries, inline props) and I could imagine Platform.Variant abiding by the same rules. You could go wild combining variants with OS somehow (i.e. .tv.android.js vs. .headset.android.js) but I would imagine such circumstances are pretty rare.

[douglowder]

@Abbondanzo agreed, except that Android TV cannot use the same prebuilt runtime as MetaQuest or Android mobile, unless react-native-tvos Android changes are merged into the core repo.

[dantuki]

I like the idea of separating the concepts of operating system and device category through Platform.OS and Platform.Variant.

The proposed API seems easier to reason about than maintaining long lists of platform-specific checks, especially as React Native expands to TVs, desktop environments, and headsets.

One concern I have is the potential for confusion between Platform.OS and Platform.Variant when developers decide which one to use. For example, some libraries may check for Android while others may check for mobile, even when they are trying to solve the same problem.

It could be helpful to provide clear guidelines and examples describing when platform-specific behavior should rely on Platform.OS versus Platform.Variant. This may help keep ecosystem APIs more consistent as additional out-of-tree platforms are added. ;)

[douglowder]

Thanks @dantuki -- I've made some updates today to try to clarify how these changes would work.