{"id":11781,"library":"react-native-macos","title":"React Native for macOS","description":"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.","status":"active","version":"0.81.7","language":"javascript","source_language":"en","source_url":"https://github.com/microsoft/react-native-macos","tags":["javascript","react","react-native","android","ios","mobile","cross-platform","app-framework","mobile-development","typescript"],"install":[{"cmd":"npm install react-native-macos","lang":"bash","label":"npm"},{"cmd":"yarn add react-native-macos","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-native-macos","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core React library for UI development.","package":"react","optional":false},{"reason":"TypeScript type definitions for React.","package":"@types/react","optional":false},{"reason":"Core React Native framework, `react-native-macos` is a fork that aligns closely with upstream versions.","package":"react-native","optional":false}],"imports":[{"note":"Modern React Native projects, including for macOS, primarily use ES Modules. CommonJS `require` is generally incorrect.","wrong":"const { View } = require('react-native-macos')","symbol":"View","correct":"import { View } from 'react-native-macos'"},{"note":"Import core components directly from 'react-native-macos'. Do not use internal paths.","wrong":"import Text from 'react-native-macos/Libraries/Components/Text/Text'","symbol":"Text","correct":"import { Text } from 'react-native-macos'"},{"note":"Standard UI component for user interaction.","symbol":"Button","correct":"import { Button } from 'react-native-macos'"},{"note":"Used for creating declarative styles similar to CSS.","symbol":"StyleSheet","correct":"import { StyleSheet } from 'react-native-macos'"},{"note":"Essential for registering the root component of your application.","symbol":"AppRegistry","correct":"import { AppRegistry } from 'react-native-macos'"}],"quickstart":{"code":"import React from 'react';\nimport { AppRegistry, StyleSheet, Text, View, Button } from 'react-native-macos';\n\nconst App: React.FC = () => {\n  const handlePress = () => {\n    console.log('Button pressed!');\n    // In a real app, you might update state or navigate\n  };\n\n  return (\n    <View style={styles.container}>\n      <Text style={styles.welcome}>Welcome to React Native for macOS!</Text>\n      <Text style={styles.instructions}>\n        To get started, edit App.tsx and save to reload.\n      </Text>\n      <Button\n        onPress={handlePress}\n        title=\"Learn More\"\n        color=\"#841584\"\n        accessibilityLabel=\"Learn more about this app\"\n      />\n    </View>\n  );\n};\n\nconst styles = StyleSheet.create({\n  container: {\n    flex: 1,\n    justifyContent: 'center',\n    alignItems: 'center',\n    backgroundColor: '#F5FCFF',\n  },\n  welcome: {\n    fontSize: 20,\n    textAlign: 'center',\n    margin: 10,\n  },\n  instructions: {\n    textAlign: 'center',\n    color: '#333333',\n    marginBottom: 5,\n  },\n});\n\nAppRegistry.registerComponent('MyMacOSApp', () => App);\n\n// To run this app:\n// 1. npx @react-native-community/cli init MyMacOSApp --version 0.81.2 # Use exact minor version as react-native-macos\n// 2. cd MyMacOSApp\n// 3. npx react-native-macos-init\n// 4. npm install # Ensure dependencies are correct\n// 5. npm start # In one terminal\n// 6. npx react-native run-macos # In another terminal","lang":"typescript","description":"Demonstrates a basic React Native for macOS application with a functional component, displaying text and a button, and registering the app."},"warnings":[{"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.","message":"React 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.","severity":"breaking","affected_versions":">=0.60"},{"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.","message":"Native 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.","severity":"gotcha","affected_versions":">=0.60"},{"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.","message":"Development 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.","severity":"gotcha","affected_versions":">=0.60"},{"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.","message":"Some 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.","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"Metro bundler can encounter issues like 'Port already in use' (default 8081) or 'EMFILE: too many open files' on macOS, particularly in large projects.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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`.","cause":"A native UI component was not properly linked or registered with the native module system.","error":"Invariant Violation: requireNativeComponent: \"[ComponentName]\" was not found in the UIManager."},{"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.","cause":"Xcode cannot find the React Native framework headers during compilation, often due to CocoaPods or incorrect header search paths.","error":"error: Module 'React' not found"},{"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.","cause":"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.","error":"error: Multiple commands produce '/Users/.../main.jsbundle'"},{"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.","cause":"The system's file watcher limit is exceeded, common on macOS due to many files in `node_modules` and bundlers like Watchman/Metro.","error":"Error: EMFILE: too many open files"},{"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.","cause":"Mismatch between the `react-native` version specified in `package.json` and the version expected by the `react-native-macos` CLI or other tools.","error":"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."}],"ecosystem":"npm"}