Registry / web-framework / react-native-macos

react-native-macos

JSON →
library0.81.7jsnpmunverified

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-macos
INSTALL
IMPORT
SIG · REACT-NATIVE-MACOS
R
react-native-macos
web-frameworkjavascriptv0.81.7
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

View
import { View } from 'react-native-macos'
const { View } = require('react-native-macos')
Modern React Native projects, including for macOS, primarily use ES Modules. CommonJS `require` is generally incorrect.
Text
import { Text } from 'react-native-macos'
import Text from 'react-native-macos/Libraries/Components/Text/Text'
Import core components directly from 'react-native-macos'. Do not use internal paths.
Button
import { Button } from 'react-native-macos'
Standard UI component for user interaction.
StyleSheet
import { StyleSheet } from 'react-native-macos'
Used for creating declarative styles similar to CSS.
AppRegistry
import { AppRegistry } from 'react-native-macos'
Essential for registering the root component of your application.

Demonstrates a basic React Native for macOS application with a functional component, displaying text and a button, and registering the app.

import React from 'react'; import { AppRegistry, StyleSheet, Text, View, Button } from 'react-native-macos'; const App: React.FC = () => { const handlePress = () => { console.log('Button pressed!'); // In a real app, you might update state or navigate }; return ( <View style={styles.container}> <Text style={styles.welcome}>Welcome to React Native for macOS!</Text> <Text style={styles.instructions}> To get started, edit App.tsx and save to reload. </Text> <Button onPress={handlePress} title="Learn More" color="#841584" accessibilityLabel="Learn more about this app" /> </View> ); }; const styles = StyleSheet.create({ container: { flex: 1, justifyContent: 'center', alignItems: 'center', backgroundColor: '#F5FCFF', }, welcome: { fontSize: 20, textAlign: 'center', margin: 10, }, instructions: { textAlign: 'center', color: '#333333', marginBottom: 5, }, }); AppRegistry.registerComponent('MyMacOSApp', () => App); // To run this app: // 1. npx @react-native-community/cli init MyMacOSApp --version 0.81.2 # Use exact minor version as react-native-macos // 2. cd MyMacOSApp // 3. npx react-native-macos-init // 4. npm install # Ensure dependencies are correct // 5. npm start # In one terminal // 6. npx react-native run-macos # In another terminal
Debug
Known issues
breakingReact Native for macOS is a fork that closely tracks upstream React Native. Major version upgrades in core React Native often introduce breaking changes that require manual intervention or the use of `react-native-upgrade-helper` to align project files and dependencies, particularly native code.
fix
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.
affects: >=0.60
gotchaNative module linking issues are a frequent source of errors. Modules with native code (Objective-C/C++) must be correctly linked during the build process, typically via CocoaPods, to be accessible from JavaScript.
fix
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.
affects: >=0.60
gotchaDevelopment environment setup for React Native for macOS has strict requirements for Xcode version, macOS version (Big Sur 11+), and Node.js. On Apple Silicon Macs, some legacy components or dependencies might require running Xcode under Rosetta.
fix
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.
affects: >=0.60
gotchaSome core React Native components or APIs, such as `Modal`, might not be fully supported or have different behaviors on macOS compared to iOS/Android, requiring platform-specific code or alternative UI patterns.
fix
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.
affects: All versions
gotchaMetro bundler can encounter issues like 'Port already in use' (default 8081) or 'EMFILE: too many open files' on macOS, particularly in large projects.
fix
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`.
affects: All versions
Errors
Common errors & fixes
Invariant Violation: requireNativeComponent: "[ComponentName]" was not found in the UIManager.
A native UI component was not properly linked or registered with the native module system.
fix
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`.
error: Module 'React' not found
Xcode cannot find the React Native framework headers during compilation, often due to CocoaPods or incorrect header search paths.
fix
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.
error: Multiple commands produce '/Users/.../main.jsbundle'
Xcode project has duplicate rules for creating or copying the JavaScript bundle, usually from a React Native build script and a manual 'Copy Bundle Resources' entry.
fix
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.
Error: EMFILE: too many open files
The system's file watcher limit is exceeded, common on macOS due to many files in `node_modules` and bundlers like Watchman/Metro.
fix
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.
Project 'MyMacOSApp' uses React Native 0.xx.y which is no longer supported with this version of the CLI. Please update your 'react-native' package version in the package.json and run 'npm install' or 'yarn install' again.
Mismatch between the `react-native` version specified in `package.json` and the version expected by the `react-native-macos` CLI or other tools.
fix
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.
Upgrade
Version history
0.81.7latest on npm
Audit
Dependencies
reactrequiredCore React library for UI development.
@types/reactrequiredTypeScript type definitions for React.
react-nativerequiredCore React Native framework, `react-native-macos` is a fork that aligns closely with upstream versions.
Agent activity
27 hits · last 30 days
node
20
Meta
1
OpenAI (training)
1
Resources
react-native-macos — npm install react-native-macos · libregistry