React Native for macOS

Common errors

• Invariant Violation: requireNativeComponent: "[ComponentName]" was not found in the UIManager.

  cause 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

  cause 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'

  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.
  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

  cause 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.

  cause 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.

Warnings

• breaking 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha Metro 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`.

Install

• npm install react-native-macos npm
• yarn add react-native-macos yarn
• pnpm add react-native-macos pnpm

Imports

• View
  wrong:

  const { View } = require('react-native-macos')

  correct:

  import { View } from 'react-native-macos'

  Modern React Native projects, including for macOS, primarily use ES Modules. CommonJS `require` is generally incorrect.
• Text
  wrong:

  import Text from 'react-native-macos/Libraries/Components/Text/Text'

  correct:

  import { Text } from 'react-native-macos'

  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.

Quickstart

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