node package manager
Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »


React Native Schemes Manager

Now you can use Xcode build configurations / schemes with React Native without pulling your hair out.

Build Status Supported by Thinkmill

If your app has multiple environments, you'd probably like to be able to manage these the way native developers have been doing for years, Xcode schemes and build configurations.

By default, React Native doesn't handle these particularly well, and the ability to launch dev tools or run in debug mode is impacted. This package fixes these problems.

Made by Kevin Brown, supported by Thinkmill. Thank you for making this project possible!


yarn add --dev react-native-schemes-manager


npm install --save-dev react-native-schemes-manager

Once the package is installed in your project, you just need to configure it by adding an xcodeSchemes section to your package.json and adding a postinstall script which will re-run the script whenever you add or remove packages to/from your project:

    "name": "your-awesome-app",
    "version": "1.0.0",
    "scripts": {
        "postinstall": "react-native-schemes-manager all"
    "xcodeSchemes": {
        "Debug": ["Staging", "Preflight"],
        "Release": ["Beta"],
        "projectDirectory": "iOS"

This configuration will copy the "Debug" build configuration to the "Staging" and "Preflight" build configurations in all your dependent library projects. This configuration will also copy the "Release" build configuration to the "Beta" build configuration for all of the dependent libraries. The "Debug" and "Release" arrays are both optional.

If your Xcode project is not in the default directory, "ios", you can specify the directory using the optional projectDirectory configuration. The above configuration specifies that the project is in an "iOS" directory instead (directories are case sensitive).

What Then?

The package is able to do three things:

  • Swap its own version of in instead of the stock one that assumes all debug schemes are named 'Debug'.
  • Add your build configurations to all library Xcode projects.
  • Hide any schemes that come from your library projects so they don't show up in the menu.

As long as react-native-schemes-manager all has run whenever you add react native modules, you should be good to go.

It's not working!

A good starting point for troubleshooting is:

  • Completely quit Xcode.
  • rm -rf node_modules
  • yarn or npm i
  • Re open Xcode
  • Product -> Clean
  • Run

If you're still having trouble, post an issue so we can look into it.

Tested with the following RN versions

Folks using this module have confirmed the library works with the following React Native versions. If your version is not on the list and you have confirmed it works as expected please create a PR (you can even do it on

  • 0.42.0
  • 0.43.0
  • 0.44.0

Running Manually

You can run the three parts of this package on demand by running either:

  • react-native-schemes-manager fix-libraries: Adds your build configurations to all library Xcode projects.
  • Specify the --single-project parameter to fix a single Xcode project. Example: --single-project=React
  • react-native-schemes-manager fix-script: Swaps a schemes aware build script in instead of the stock react native one.
  • react-native-schemes-manager hide-library-schemes: Hides any build schemes that come from your node_modules folder xcodeproj files as you don't usually want to see them anyway.

And of course you can run all 3 easily if you'd prefer:

  • react-native-schemes-manager all: Runs all the scripts above.

The best way to give yourself a manual trigger for this is add to your package.json scripts section like so:

    "name": "your-awesome-app",
    "version": "1.0.0",
    "scripts": {
        "fix-xcode": "react-native-schemes-manager all",
        "postinstall": "react-native-schemes-manager all"

You can then yarn run fix-xcode or npm run fix-xcode which will run the cleanup scripts on demand.


If you decide this isn't working out for you, we'd love to know why and to try to fix it. Please open an issue.

But if you still want to get rid of this and revert the changes to your project, you can follow these steps:

  1. yarn remove react-native-schemes-manager or npm remove react-native-schemes-manager --save-dev
  2. Open your Xcode project.
  3. Click on the project itself on the left sidebar to ensure it's selected.
  4. Click the "Build Phases" tab.
  5. Expand the "Bundle React Native code and images" phase.
  6. Change the script to:
export NODE_BINARY=node

Then, you can revert the changes to the installed libraries by:

  1. Quitting Xcode.
  2. rm -rf node_modules
  3. yarn or npm i
  4. Re-open Xcode.

You're back to where you started!

Further Reading

These are some great articles about related topics in case you're hungry for more:


Licensed under the MIT License, Copyright © 2017 Kevin Brown.

See LICENSE for more information.


This project builds on a lot of earlier work by clever folks all around the world. We'd like to thank Alek Hurst and Craig Edwards who contributed ideas and inspiration, without which this project wouldn't have been possible.