React Native Windows and macOS: Out-of-Tree Platforms Explained | Mironsoft

1. What an out-of-tree platform means in React Native

React Native Windows and React Native macOS belong to a category that Facebook, now Meta, officially calls out-of-tree platforms: instead of forking the React Native core for every additional target platform, React Native has defined stable extension points for a few years now, through which external teams can plug in their own platform implementations without touching the core itself. React Native Windows and React Native macOS are both primarily maintained by Microsoft and use exactly this architecture, as does React Native visionOS for Apple's Vision Pro by now.

The key difference from a classic community fork is update compatibility: because both projects build against the same official extension points, such as TurboModules and the Fabric renderer architecture, that iOS and Android also use, they stay structurally closer to current React Native versions than an independent fork typically would. That does not mean new React Native core versions are immediately available on Windows and macOS though, in practice there is regularly a gap of several weeks to months between a core release and the corresponding Windows or macOS release.

2. React Native Windows: architecture built on WinUI 3

React Native Windows does not render components through a web view or its own drawing engine, it maps them onto real native Windows controls, in current versions through the Windows App SDK with WinUI 3 as the UI layer, in older versions through UWP XAML. Native modules are written in C++/WinRT, which for teams with pure iOS and Android experience means a genuine third native language on top of Swift and Kotlin, whenever platform-specific Windows functionality beyond the default scope is needed.

The Fabric renderer architecture, which React Native uses as its standard rendering pipeline since the more recent versions, also forms the foundation on Windows, meaning many of the performance improvements from React Native's new architecture rework carry over to Windows as well. In practice this means a React Native project that has already moved to Fabric and TurboModules tends to run more smoothly on Windows than a project still built on the old bridge architecture.

// windows/MyApp/NativeModules/BatteryModule.h
#pragma once
#include "NativeModules.h"

namespace winrt::MyApp {

REACT_MODULE(BatteryModule)
struct BatteryModule {
  REACT_SYNC_METHOD(GetBatteryLevel)
  double GetBatteryLevel() noexcept {
    return 1.0;
  }
};

}

3. React Native macOS: closer to the iOS code than Windows is to Android

React Native macOS shares structurally far more code with React Native iOS than React Native Windows does with React Native Android, because both Apple platforms use the same underlying Objective-C and Swift toolchain along with large parts of the rendering infrastructure. Instead of WinUI or UWP, React Native macOS renders onto AppKit, the classic macOS UI framework, which means many native iOS modules work under macOS with comparatively little adaptation effort, as long as they do not depend on purely iOS-specific APIs such as touch gestures.

Microsoft uses React Native macOS internally for parts of its Office and Messenger applications among others, which gives the project an unusually stable production reference inside the same company that also funds its ongoing development. That is a notable difference from many other projects in the React Native ecosystem, where maintenance depends on individual maintainers' spare time rather than on a company with its own productive stake in the project's stability.

4. What gets shared across platforms, and what does not

The vast majority of actual app logic can be shared between mobile and desktop targets: React components, state management, API clients, and business rules stay platform-independent JavaScript or TypeScript code, as long as they do not directly touch mobile-specific APIs like the camera or GPS. The TurboModule and Fabric architecture keeps the same component interface consistent across every supported platform, even when the underlying native implementation is completely different.

What almost always stays platform-specific, on the other hand, is packaging and distribution: on Windows, the app is typically built as an MSIX package for the Microsoft Store or as a sideload install, on macOS as a classic .app bundle with Apple notarization for distribution outside the Mac App Store. UI details such as keyboard shortcuts, menu bar integration on macOS, or native context menus on Windows also generally require their own platform-specific code, something that simply does not exist in this form under iOS or Android.

{
  "name": "shared-business-logic",
  "main": "src/index.ts",
  "dependencies": {
    "zustand": "^4.5.0"
  }
}

5. Assessing maturity and community size realistically

The release cadence of React Native Windows and React Native macOS follows the React Native core release, but typically trails it by a few weeks to months, because each new core version first needs to be validated and adapted against the respective platform. For teams that always want to run the very latest React Native version, this is a relevant planning factor, since a brand-new core feature is not immediately available on Windows or macOS, it catches up with a delay.

The community size of both projects is noticeably smaller than iOS and Android, measurable in GitHub stars, the number of active contributors, and the speed at which third-party libraries add Windows or macOS support. In practice this means that when picking npm packages from the React Native ecosystem, you regularly have to check whether a library even ships a Windows or macOS implementation, instead of being able to take it for granted the way you can with iOS and Android.

6. Practical example: an internal desktop tool built on the existing app

A realistic use case for React Native Windows is an internal admin tool, say an inventory dashboard for staff, that uses the same API client, the same data models, and large parts of the component library that already exist for the mobile React Native app. Instead of setting up a completely new desktop project in a different framework, you add React Native Windows as an additional target inside an existing monorepo and share the vast majority of application code between the mobile app and the desktop tool.

This scenario works particularly well when the affected functionality mostly consists of forms, lists, and data displays that are already designed to be platform-independent, and relies little on mobile-exclusive interaction patterns such as touch gestures or camera access. For a purely internal tool with a manageable user count, the extra build and maintenance overhead of another platform usually pays off faster than it would for a publicly distributed consumer app.

7. Practical limitations in day-to-day work

Not every React Native third-party package works automatically on Windows or macOS, even when it runs flawlessly on iOS and Android. Many libraries implicitly assume only ios and android subfolders exist, and the autolinking system for React Native Windows or macOS expects additional, explicitly named windows or macos directories with their own native implementation, something many package authors have simply never added.

In practice, this means teams have to check every existing dependency individually before adopting React Native Windows or macOS, to see whether a compatible implementation exists, whether the missing functionality can be worked around with a simple conditional platform branch in their own code, or whether, in the worst case, a custom native module has to be written for the missing platform, which eats into the time savings originally hoped for from code reuse.

8. When the extra platform support genuinely pays off

The extra effort for Windows or macOS support pays off above all when an existing, production React Native codebase already contains a high share of platform-independent business logic and a genuine desktop use case exists that can reuse most of that logic. Teams with deep in-house React Native experience benefit further, because they do not need to learn a completely new technology, they keep reusing the same React concepts and most of their existing toolchain.

For a greenfield desktop project with no existing React Native mobile app, the calculation usually looks different: frameworks like Electron or Tauri, purpose-built for desktop-only use cases, often bring a more mature desktop toolchain and a wider selection of desktop-specific libraries, without the extra complexity of a cross-mobile-desktop architecture that React Native Windows and macOS structurally carry along.

9. Setup and tooling in everyday development

Getting started runs through the commands npx react-native-windows-init or npx react-native-macos-init, which add the respective platform configuration and the necessary folder structure to an existing React Native project. React Native Windows additionally requires a full Visual Studio installation with the C++ desktop development workload, while React Native macOS only needs the Xcode installation already present for iOS development anyway, which noticeably eases the entry for existing iOS teams.

The actual build and debug cycle runs through npx react-native run-windows or npx react-native run-macos, each using the same Metro bundler and fast refresh behavior as iOS and Android, which keeps the developer experience pleasantly consistent. For platform-specific debugging of native C++/WinRT or Objective-C/Swift modules, though, switching into Visual Studio or Xcode remains necessary, just as it does for native module issues on iOS or Android.

npx react-native-windows-init --overwrite
npx react-native run-windows

npx react-native-macos-init
npx react-native run-macos

10. Summary

11. FAQ: React Native Windows and macOS: The Essentials at a Glance