React Native Pt. III: Native Modules

React Native is a JavaScript library that allows you to create native Android and iOS apps. This series of posts follows me on my journey to learn the language. In the first two posts I documented the basics of React Native, dove into the project file structure, and discussed various concepts. In this post we will look at native modules and how they are used to connect native code to the JavaScript in React Native.


Note: This is documented through the lens of a macOS user and it is assumed you have some familiarity with JavaScript, Swift, Java, and bash. You should also already have Xcode and Android Studio installed and configured. My examples are shown using Android.

Native Modules

Native modules allow your React Native application to access native code. This is mostly used for platform specific APIs that are not built out in React Native. These modules allow you to implement your own code, or external packages made available by other developers (npm packages). This guide will walk through the Toast example that is given in the React Native documents. I will attempt to be a little more granular than those docs, as I hit some bumps during the integration.

Native Module Setup

The easiest way to get started with native modules is to use the nifty react-native-create-library tool. Details on the tool can be found here, but in short it creates all of the files and directories you need to get started with building your own module. We can use the following commands to install the tool globally and the run the command where you want your module directory to be created.

npm install -g react-native-create-library
react-native-create-library ToastLibrary

You should now have a basic native module in it’s own directory that looks like the following.

You can now cd into that directory and run npm install to pull in all dependencies this package requires. Next we will add some code into the module that will allow you to use the native Android Toast feature.

Building the Toast Module and Package

In the screenshot above, you can see module and package files in the directory ToastLibrary/android/src/main/java/com/reactlibrary, but we will create our own native module,, and register it as a package, All native modules extend ReactContextBaseJavaModule and implement the native functionality required by your JavaScript — in this case the show method used by Toast. Along with this, we need the required getName() method that returns the name of the native module. Your code should look similar to the following

The show method may look different for you (you may also take in toast length as a parameter for example), but this shows the most basic setup. Be sure to include the @ReactMethod annotation over the show method, which will expose it to JavaScript, and to @Override the getName() method.

Next we need to register the module as a package so that it is available to your JavaScript. This is done by creating a new class that implements ReactPackage and looks like the following.

Lastly, we add this line to the index.js file of our native module to expose the native ToastModule as a JavaScript module.

 module.exports = NativeModules.ToastModule;

Configuring the App

To finish up our Toast module integration, we need to make some changes to our HelloWorld app and pull in the package for use. First, you need to add the Toast module you just created as a dependency within your apps package.json file. Since this module is local (and not in the npm registry) your dependency will have a directory listed instead of a version.

"react-native-toast-library": "file:../ToastLibrary"

After this has been added, you need to install and link the dependency to your project by running these commands.

npm install
react-native link

Now, open up your file within the HelloWorld/android/src/main/java/com/helloworld directory and add your ToastPackage to the ReactPackage array in the getPackages() method. Be sure to import the package as well.

Your native module is now included in your app and can be called from JavaScript. This is done by importing the module into the JS file you want to use it in and calling the show method. Updating our App.js file from earlier in the series would look like this

That’s it! You should be able to run your app and see a toast when the Switch button is pressed.