Integration with Existing Apps #

Project with Native Code Required

This page only applies to projects made with react-native init or to those made with Create React Native App which have since ejected. For more information about ejecting, please see the guide on the Create React Native App repository.

React Native is great when you are starting a new mobile app from scratch. However, it also works well for adding a single view or user flow to existing native applications. With a few steps, you can add new React Native based features, screens, views, etc.

The specific steps are different depending on what platform you're targeting.

• iOS (Objective-C)
• iOS (Swift)
• Android (Java)

Key Concepts

The keys to integrating React Native components into your Android application are to:

1. Set up React Native dependencies and directory structure.
2. Develop your React Native components in JavaScript.
3. Add a ReactRootView to your Android app. This view will serve as the container for your React Native component.
4. Start the React Native server and run your native application.
5. Verify that the React Native aspect of your application works as expected.

Prerequisites

Follow the instructions for building apps with native code from the Getting Started guide to configure your development environment for building React Native apps for Android.

1. Set up directory structure

To ensure a smooth experience, create a new folder for your integrated React Native project, then copy your existing Android project to a /android subfolder.

2. Install JavaScript dependencies

Go to the root directory for your project and create a new package.json file with the following contents:

{ "name" : "MyReactNativeApp" , "version" : "0.0.1" , "private" : true , "scripts" : { "start" : "node node_modules/react-native/local-cli/cli.js start" } }

Next, you will install the react and react-native packages. Open a terminal or command prompt, then navigate to the root directory for your project and type the following commands:

$ npm install --save react@ 16.0 . 0 -beta .5 react -native

Make sure you use the same React version as specified in the React Native package.json file. This will only be necessary as long as React Native depends on a pre-release version of React.

This will create a new /node_modules folder in your project's root directory. This folder stores all the JavaScript dependencies required to build your project.

Adding React Native to your app

Configuring maven

Add the React Native dependency to your app's build.gradle file:

dependencies { ... compile "com.facebook.react:react-native:+" // From node_modules. }

If you want to ensure that you are always using a specific React Native version in your native build, replace + with an actual React Native version you've downloaded from npm.

Add an entry for the local React Native maven directory to build.gradle. Be sure to add it to the "allprojects" block:

allprojects { repositories { ... maven { // All of React Native (JS, Android binaries) is installed from npm url "$rootDir/node_modules/react-native/android" } } ... }

Make sure that the path is correct! You shouldn’t run into any “Failed to resolve: com.facebook.react:react-native:0.x.x" errors after running Gradle sync in Android Studio.

Configuring permissions

Next, make sure you have the Internet permission in your AndroidManifest.xml:

<uses -permission android :name = "android.permission.INTERNET" / >

If you need to access to the DevSettingsActivity add to your AndroidManifest.xml:

<activity android :name = "com.facebook.react.devsupport.DevSettingsActivity" / >

This is only really used in dev mode when reloading JavaScript from the development server, so you can strip this in release builds if you need to.

Code integration

Now we will actually modify the native Android application to integrate React Native.

The React Native component

The first bit of code we will write is the actual React Native code for the new "High Score" screen that will be integrated into our application.

1. Create a index.js file

First, create an empty index.js file in the root of your React Native project.

index.js is the starting point for React Native applications, and it is always required. It can be a small file that requires other file that are part of your React Native component or application, or it can contain all the code that is needed for it. In our case, we will just put everything in index.js.

2. Add your React Native code

In your index.js, create your component. In our sample here, we will add simple <Text> component within a styled <View>:

'use strict' ; import React from 'react' ; import { AppRegistry , StyleSheet , Text , View } from 'react-native' ; class HelloWorld extends React.Component { render ( ) { return ( <View style = {styles .container } > <Text style = {styles .hello } >Hello , World < /Text > < /View > ) } } var styles = StyleSheet . create ( { container : { flex : 1 , justifyContent : 'center' , } , hello : { fontSize : 20 , textAlign : 'center' , margin : 10 , } , } ) ;AppRegistry . registerComponent ( 'MyReactNativeApp' , ( ) => HelloWorld ) ;

3. Configure permissions for development error overlay

If your app is targeting the Android API level 23 or greater, make sure you have the overlay permission enabled for the development build. You can check it with Settings.canDrawOverlays(this);. This is required in dev builds because react native development errors must be displayed above all the other windows. Due to the new permissions system introduced in the API level 23, the user needs to approve it. This can be achieved by adding the following code to the Activity file in the onCreate() method. OVERLAY_PERMISSION_REQ_CODE is a field of the class which would be responsible for passing the result back to the Activity.

if (Build .VERSION .SDK_INT >= Build .VERSION_CODES .M ) { if ( !Settings . canDrawOverlays( this ) ) { Intent intent = new Intent (Settings .ACTION_MANAGE_OVERLAY_PERMISSION , Uri . parse( "package:" + getPackageName( ) ) ) ; startActivityForResult(intent , OVERLAY_PERMISSION_REQ_CODE ) ; } }

Finally, the onActivityResult() method (as shown in the code below) has to be overridden to handle the permission Accepted or Denied cases for consistent UX.

@Override protected void onActivityResult( int requestCode , int resultCode , Intent data ) { if (requestCode == OVERLAY_PERMISSION_REQ_CODE ) { if (Build .VERSION .SDK_INT >= Build .VERSION_CODES .M ) { if ( !Settings . canDrawOverlays( this ) ) { // SYSTEM_ALERT_WINDOW permission not granted... } } } }

The Magic: ReactRootView

You need to add some native code in order to start the React Native runtime and get it to render something. To do this, we're going to create an Activity that creates a ReactRootView, starts a React application inside it and sets it as the main content view.

If you are targetting Android version <5, use the AppCompatActivity class from the com.android.support:appcompat package instead of Activity.

public class MyReactActivity extends Activity implements DefaultHardwareBackBtnHandler { private ReactRootView mReactRootView ; private ReactInstanceManager mReactInstanceManager ; @Override protected void onCreate(Bundle savedInstanceState ) { super . onCreate(savedInstanceState ) ; mReactRootView = new ReactRootView ( this ) ; mReactInstanceManager = ReactInstanceManager . builder( ) . setApplication( getApplication( ) ) . setBundleAssetName( "index.android.bundle" ) . setJSMainModulePath( "index" ) . addPackage( new MainReactPackage ( ) ) . setUseDeveloperSupport(BuildConfig .DEBUG ) . setInitialLifecycleState(LifecycleState .RESUMED ) . build( ) ; mReactRootView . startReactApplication(mReactInstanceManager , "MyReactNativeApp" , null ) ; setContentView(mReactRootView ) ; } @Override public void invokeDefaultOnBackPressed( ) { super . onBackPressed( ) ; } }

If you are using a starter kit for React Native, replace the "HelloWorld" string with the one in your index.js file (it’s the first argument to the AppRegistry.registerComponent() method).

If you are using Android Studio, use Alt + Enter to add all missing imports in your MyReactActivity class. Be careful to use your package’s BuildConfig and not the one from the ...facebook... package.

We need set the theme of MyReactActivity to Theme.AppCompat.Light.NoActionBar because some components rely on this theme.

<activity android:name=".MyReactActivity" android:label="@string/app_name" android:theme="@style/Theme.AppCompat.Light.NoActionBar"></activity>

A ReactInstanceManager can be shared amongst multiple activities and/or fragments. You will want to make your own ReactFragment or ReactActivity and have a singleton holder that holds a ReactInstanceManager. When you need the ReactInstanceManager (e.g., to hook up the ReactInstanceManager to the lifecycle of those Activities or Fragments) use the one provided by the singleton.

Next, we need to pass some activity lifecycle callbacks down to the ReactInstanceManager:

@Override protected void onPause( ) { super . onPause( ) ; if (mReactInstanceManager != null ) { mReactInstanceManager . onHostPause( this ) ; } }@Override protected void onResume( ) { super . onResume( ) ; if (mReactInstanceManager != null ) { mReactInstanceManager . onHostResume( this , this ) ; } }@Override protected void onDestroy( ) { super . onDestroy( ) ; if (mReactInstanceManager != null ) { mReactInstanceManager . onHostDestroy( ) ; } }

We also need to pass back button events to React Native:

@Override public void onBackPressed( ) { if (mReactInstanceManager != null ) { mReactInstanceManager . onBackPressed( ) ; } else { super . onBackPressed( ) ; } }

This allows JavaScript to control what happens when the user presses the hardware back button (e.g. to implement navigation). When JavaScript doesn't handle a back press, your invokeDefaultOnBackPressed method will be called. By default this simply finishes your Activity.

Finally, we need to hook up the dev menu. By default, this is activated by (rage) shaking the device, but this is not very useful in emulators. So we make it show when you press the hardware menu button (use Ctrl + M if you're using Android Studio emulator):

@Override public boolean onKeyUp( int keyCode , KeyEvent event ) { if (keyCode == KeyEvent .KEYCODE_MENU && mReactInstanceManager != null ) { mReactInstanceManager . showDevOptionsDialog( ) ; return true ; } return super . onKeyUp(keyCode , event ) ; }

Now your activity is ready to run some JavaScript code.

Test your integration

You have now done all the basic steps to integrate React Native with your current application. Now we will start the React Native packager to build the index.bundle package and the server running on localhost to serve it.

1. Run the packager

To run your app, you need to first start the development server. To do this, simply run the following command in the root directory of your React Native project:

$ npm start

2. Run the app

Now build and run your Android app as normal.

Once you reach your React-powered activity inside the app, it should load the JavaScript code from the development server and display:

Creating a release build in Android Studio

You can use Android Studio to create your release builds too! It’s as easy as creating release builds of your previously-existing native Android app. There’s just one additional step, which you’ll have to do before every release build. You need to execute the following to create a React Native bundle, which will be included with your native Android app:

$ react -native bundle --platform android --dev false --entry -file index .js --bundle -output android /com /your -company -name /app - package -name /src /main /assets /index .android .bundle --assets -dest android /com /your -company -name /app - package -name /src /main /res/

Don’t forget to replace the paths with correct ones and create the assets folder if it doesn’t exist.

Now just create a release build of your native app from within Android Studio as usual and you should be good to go!

Now what?

At this point you can continue developing your app as usual. Refer to our debugging and deployment docs to learn more about working with React Native.

← Previous Continue Reading →

Improve this page by sending a pull request!