React Native App : White Label 101

Part 1: iOS

8 min readSep 9, 2019

Mobile devs have been white-labelling native Android & iOS apps since the dawn of time. The key is to use the built in solutions that the platform-tools provide. Namely:

Android: Product Flavors
iOS: Targets

But what about React Native? RN build tools don’t provide an out of the box solution for white-labelling in the same breadth as the native tools. But with a bit of gumption and know-how, we can use the same native tools for white-labelling our React Native project.

What is white labelling?

White labelling is the process of creating different products using the same template. In the mobile development world, this means creating a project that has one code base but can produce many apps all with different:

App Icons
Image Assets
String Localizations
Styles
(Sometimes) User Features

Getting Started

To begin, we will create a React Native project. Let’s call it WhiteLabelDemo. Our project will have these 3 source files

WhiteLabelDemo/
    app/
        App.tsx
        AppTheme.tsx
        whitelabel/
            WhiteLabelConfig.tsx

Let’s see what these files look like

Our project has the familiar app component with styling; nothing special there. The magic comes from the WhiteLabelConfig.tsx file. We hard code these values for now, but will soon hook into the real implementation.

Take a walk on the Native side: iOS

The React Native Bridge

We are going to open the ios/WhiteLabelDemo.xcworkspace file in Xcode and create the WhiteLabelConfig objective-c files to communicate to our RN app from iOS.

Let’s create the Objective-C header file of our React Native Bridge. Right click on the WhiteLabelConfig/ yellow folder in the Project Navigator tab in the left window pane of Xcode. Select New File... , choose the “Header File” option and click “Next”. In the “Save As:” field, name the file WhiteLabelConfig.h. Make sure that onlyWhiteLabelDemo target in “Targets” is selected and click “Create”.

Now copy the contents of the following into the newly created header file

Now let’s create our implementation file. Right click on the WhiteLabelConfig/ yellow folder in the Project Navigator tab in the left window pane of Xcode. Select New File... , choose the “Objective-C File” option and click “Next”. In the “File:” field, name the file WhiteLabelConfig.m. Make sure that onlyWhiteLabelDemo target in “Targets” is selected and click “Create”.

Now copy the contents of the following into the newly created file

Lastly, let’s change the WhiteLabelConfig.tsx file to implement the React Native Bridge we’ve setup

We now have the same app that we started with, but with styles and strings coming from the native iOS project. We are now in a great place to setup different targets to create all the white label iOS apps we want!

iOS Targets

WhiteLabelDemo doesn’t really roll off the tongue. Let’s change the target “WhiteLabelDemo” so that it creates an end-product/app that’s more fun.

Select the Project Navigator, select the WhiteLabelDemo project icon. In the list of targets, single-click the “WhiteLabelDemo” target and rename it “PurpleParrots”.

Then in the Xcode window menu, select Product > Scheme > Manage Schemes… In the list of schemes, select the old WhiteLabelDemo scheme and rename it to PurpleParrots

Then in the Project Navigator, select the WhiteLabelDemo project, select the PurpleParrots target. In the General tab, rename the Display Name to Purple Parrots. Rename the Bundle Identifier to org.reactjs.native.example.WhiteLabelDemo.PurpleParrots

We’re going to create a new group(folder) for our white-label-specific files so they are organized neatly. Right click the WhiteLabelDemo folder in the Project Navigator and select New Group with Folder. Name the new folder PurpleParrots. Finally move the Images.xcassets & WhiteLabelConfig.m file into the PurpleParrots folder.

To better show off what we’ve done in customizing this target, we will update the colors and text of the final product. Update the WhiteLabelConfig.m file

We’re also going to add a new icon for the home screen. I’m sure you can guess what it’s going to be.

Download the above image and use the Icon Set Creator to create the required app icons. Once you’ve generated the icons, drag them into the Image.xcassets > AppIcon set in Xcode.

Lastly, we need to run the new iOS target. We are going to specify the scheme used to run the new target and create the final Purple Parrots app.

react-native run-ios --scheme "PurpleParrots"

this is what you should see as the result, a new app with custom colors, name, and icon

Encore, Encore…

Let’s put all that hard work to good use and create a new white-labelled app. Select the Project Navigator, select the WhiteLabelDemo project icon. In the list of targets right-click the PurpleParrots and select Duplicate. A pop-up window will appear. Select Duplicate Only.

A new PurpleParrots copy target will be created. Let’s rename the target and scheme like we did before. Single click PurpleParrots copy and rename to GreenMonkeys.

Then rename the scheme by going to the Xcode window menu and navigating to Product > Scheme > Manage Schemes… selecting the PurpleParrots copy in the list of schemes and renaming it to GreenMonkeys.

Now in the Project Navigator, select the WhiteLabelDemo project, select the GreenMonkeys target. In the General tab, rename the Display Name to Green Monkeys. Rename the Bundle Identifier to org.reactjs.native.example.WhiteLabelDemo.GreenMonkeys

Next, rename the newly created PurpleParrots copy-Info.plist file to GreenMonkeys.plist. Next go to the Project Navigator, select the WhiteLabelDemo project, select the GreenMonkeys target. In the General tab, click Choose Info.plist File…

Next, select the GreenMonkeys.plist and click Choose.

Now we create a new group(folder) for our GreenMonkeys target-specific files. Right-click the WhiteLabelDemo folder in the Project Navigator and select New Group with Folder (or New Group if only available). Name the new folder GreenMonkeys.

Right-click on the new GreenMonkeys folder and select New File… Select the Objective-C File option and name the file WhiteLabelConfig.m. In the next window MAKE SURE you only select the target GreenMonkeys and then click Create.

Now copy and paste the code below into the new file

Next we add a new asset catalog to hold our green monkeys specific app icon. Right-click GreenMonkeys folder and select New File… Scroll down to Resource and select Asset Catalog and click Next.

Save As: Images.xcassets and MAKE SURE you only select the GreenMonkeys target. Then click Create. Select the new Images.xcassets file and in the left pane of the asset, window click the + button at the bottom.

go to App Icons & Launch Images > New iOS App Icon and click New iOS App Icon.

Just as we did before, use the Icon Set Creator to make an iOS icon of our Green Monkeys image below

Drag the icon images created by Icon Set Creator into the GreenMonkeys > Images.xcassets.

Let’s do a quick check to make sure our white-label logic files target the correct targets. All files in the PurpleParrots folder should only have the PurpleParrots target selected in the Target Membership list in the File Inspector window pane to the right. So make sure that WhiteLabelConfig.m & Images.xcassets in the PurpleParrots folder only have PurpleParrots Target Membership

Similarly, make sure that WhiteLabelConfig.m & Images.xcassets in the GreenMonkeys folder only have GreenMonkeys Target Membership

Now we get to run

react-native run-ios --scheme "GreenMonkeys"

And Voila!!!!

Conclusion

We have leveraged the native build tools in iOS to bundle all of our necessary files and assets into the right white-label targets for us. We don’t need to maintain gnarly bash scripts or add python scripts to our project just to script the white label packaging.

The key here is to maintain the contract between WhiteLabelConfig.tsx and the WhiteLabelConfig.m. However, this approach definitely can scale as long as you can maintain this contract.

You can grab the source code for the WhiteLabelDemo project on GitHub.

Stay tuned for React Native App : White Label 102 coming soon.