Skip to content
Get packs

Guide · Open source

How to use react-native-macos: install, run and what to know first

Updated · written with AI from the project's own documentation and checked against our catalogue data

react-native-macos is an experimental fork of React Native that lets developers build macOS desktop applications with JavaScript and React-style components. This guide walks through the documented install and run steps, the requirements, and an important warning: the README says the project is deprecated and no longer maintained. By the end you will know what the commands do, whether the project fits your situation, and which successor the maintainers recommend.

React Native macOSptmt/react-native-macos · ★ 11.2k · MIT

Quick start

  1. 1Confirm requirements. Check that you have Node 4.x or later and OS X 10.11 or later, and that you already know basic React Native.
  2. 2Install the CLI. Run npm install react-native-macos-cli -g to add the command-line tool globally.
  3. 3Create a project. Run react-native-macos init MyProject to generate a new project folder.
  4. 4Open the project folder. Change into the new folder with cd MyProject.
  5. 5Run the macOS app. Run react-native-macos run-macos to start the app on macOS.

Check the deprecation status before you start

The README opens with a deprecation notice: the project is no longer maintained. It points to Microsoft's version of React Native for desktop, React Native for Windows, at https://microsoft.github.io/react-native-windows/ as the successor.

The README also notes that React Native can run on Catalyst, with a link to a community discussion on the subject.

  • Good reasons to continue: you maintain an existing project that already depends on this fork, or you want to study how React Native was adapted to Cocoa.
  • Good reason to stop: you are starting a new production project.

Confirm your requirements

The README lists two requirements: Node 4.x or later, and OS X 10.11 or later. It also says previous React Native experience is highly recommended, so beginners should learn basic React Native first.

Because the README lists only these versions, do not assume support for newer Node or macOS releases.

  • Node 4.x+
  • OS X 10.11+
  • Prior React Native experience (highly recommended)

Install the command-line tool

The README installs a separate CLI package globally with npm. Run this in a terminal:

npm install react-native-macos-cli -g

Create a new project and run the macOS app

Use the CLI to create a project, move into its folder, and start the macOS app. The project name MyProject is the README's example; you can replace it with your own.

react-native-macos init MyProject cd MyProject react-native-macos run-macos

Add a macOS target to an existing React Native project

The README says you can add a macOS target to an existing iOS, Android or Windows project. Follow the steps above to create the macOS folder, merge that folder into your current React Native project, then place the rn-cli.config.js file from the linked gist in the project root.

Back up your project before merging, since the README gives no further detail on conflicts.

Find documentation and get help

The README says the fork is the same as React Native, so you can follow the React Native documentation for general instructions. For project-specific help, the README lists StackOverflow (tag react-native-macos), the #react-native-platforms channel on Reactiflux, and the maintainer on Twitter. It states that GitHub issues are used for bugs and feature requests, and that maintainer bandwidth is limited.

The README also includes an RNTesterApp with component examples. It can load external JavaScript bundles over HTTP, and it is available as a downloadable UIExplorer.zip file.

What people use it for

  • Exploring how React Native components map to macOS desktop windows using the RNTesterApp examples.
  • Maintaining an older desktop app that already depends on react-native-macos.
  • Adding a macOS target to an existing React Native project by merging the generated folder.
  • Studying how React Native was adapted to Cocoa-based desktop apps.

Frequently asked questions

Is react-native-macos still maintained?

No. The README states that the project is no longer maintained and points to Microsoft's React Native for Windows as the successor. It is also described as experimental.

What are the requirements for react-native-macos?

The README lists Node 4.x or later and OS X 10.11 or later. It also recommends previous React Native experience.

How do I install react-native-macos?

Install the CLI with npm install react-native-macos-cli -g, then run react-native-macos init MyProject to create a project. The README does not describe a separate install of the library itself.

Is react-native-macos free to use?

The project is MIT licensed, and the README states that React Native is MIT licensed. Check the repository's license file for the exact terms of the fork.

What should I use instead of react-native-macos?

The README recommends Microsoft's React Native for Windows. The project's comparable options also include Electron, Tauri, and Catalyst, which the README links to as a way to run React Native on macOS.

Where can I get help if the app will not run?

The README suggests asking on StackOverflow with the react-native-macos tag, or chatting in the #react-native-platforms channel on Reactiflux. It notes that GitHub issues are for bugs and feature requests, and maintainer bandwidth is limited.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use react-native-macos only to study the history of React Native on desktop or to maintain an existing project that already depends on it. For new production work, the README points to React Native for Windows, and Electron or Tauri are other options to compare.

Install options & downloads