React Native for macOS is a Microsoft-maintained fork of the core React Native framework, extending its capabilities to build native desktop applications for Apple's macOS operating system using JavaScript and React. Currently at version 0.81.7, it closely tracks the main React Native releases, offering regular patch updates and new minor versions approximately every two months (aiming for six per year), ensuring compatibility with the broader React ecosystem. Its primary differentiator is enabling developers to leverage their existing React Native knowledge and codebase to target macOS, facilitating significant code reuse across mobile (iOS/Android) and desktop platforms. This allows for a consistent developer experience and declarative UI development, similar to building for mobile, but tailored for the macOS environment.
npm install react-native-macosVerified import paths — ran on the pinned version, not inferred.
Demonstrates a basic React Native for macOS application with a functional component, displaying text and a button, and registering the app.
Refer to the official upgrade guide and `react-native-upgrade-helper` for specific version migrations. Ensure `react-native` and `react-native-macos` package versions are compatible.
Verify that `pod install` has been run in the `macos/` directory and that the `.xcworkspace` file (not `.xcodeproj`) is opened in Xcode. Check `Linked Frameworks and Binaries` in Xcode project settings.
Consult the 'System Requirements' documentation on the React Native for Windows + macOS website. Ensure Xcode Command Line Tools are correctly installed and selected. Install Rosetta if encountering architecture-related build failures on Apple Silicon.
Utilize React Native's `Platform.OS === 'macos'` checks or create platform-specific files (e.g., `MyComponent.macos.tsx`) to manage UI or API differences. Review documentation for component compatibility.
For 'Port already in use', terminate the conflicting process or run `npm start -- --port=8088`. For 'EMFILE', run `watchman watch-del-all` and `watchman shutdown-server`.
Ensure `pod install` has been run in the `macos/` directory, and the project is opened via the `.xcworkspace` file. Clean the Xcode build folder (`Cmd+Shift+K`) and rebuild. Verify the native module is compatible with `react-native-macos`.
Run `cd macos && pod deintegrate && pod install && cd ..` to reinstall CocoaPods dependencies. Ensure Xcode's 'Header Search Paths' are correctly configured for your project and pods.
In Xcode, navigate to your target's 'Build Phases', then 'Copy Bundle Resources'. Remove one of the entries for `main.jsbundle` or ensure the build script is not duplicating this action.
Run `watchman watch-del-all` followed by `watchman shutdown-server` to clear Watchman caches. Consider increasing the system's file descriptor limit if the issue persists.
Ensure the `react-native` dependency in your `package.json` matches the compatible version for your `react-native-macos` installation. Use `npx react-native-macos-init` after updating.