Top lessons we learned while building a React Native bridge library

This will be a two-part article. The first part focuses on the big picture and setting up the library structure. In the second part I’ll describe best practices for writing methods and passing objects.

As you build React Native applications, sooner or later you’ll want to use a 3rd party SDK. These usually come in iOS and Android variants. A bridge library lets you call native methods from both worlds, in Javascript.

You can find them for many popular SDKs. But, what if there is no bridge for the SDK you want to use, what do you do? Well, you’re out of luck. We recently had a similar situation in Shoutem when we wanted to integrate with Shopify.

I’ll show you how we went from zero to publishing a library that’s growing in popularity. We want to help you avoid all the pitfalls we met and make the process effortless.

Sharing is caring

You might be thinking why not plug the native SDKs in your application and call it a day. The official documentation on native modules for iOS and Android covers this well. But, if you create a bridge library and use it in your application as a dependency:

  • You’ll have an easier time maintaining it
  • If you open source it, others will give you feedback and even contribute. With our Shopify bridge, other developers are integrating Apple Pay
  • You’ll help the community, and you can’t put a price on that

Let’s start a library

If you think that react-native init is a good place to start, you’re not alone. We thought that as well. But, it’s meant to scaffold an application, not a library, and won’t work for our purpose. Luckily, there is a great tool, called react-native-create-bridge, that does exactly this. Run it, and your library is good to go. You can set up this structure on your own, but it’s a cumbersome and error-prone process. Before we continue, consider giving some appreciation to the author.

React Native changed the import format for its iOS headers in version 0.40. If you want to support both older and newer applications, use this neat trick for all React imports:

// import RCTBridgeModule
#if __has_include(<React/RCTBridgeModule.h>)
#import <React/RCTBridgeModule.h>
#elif __has_include(“RCTBridgeModule.h”)
#import “RCTBridgeModule.h”
#else
#import “React/RCTBridgeModule.h” // Required when used as a Pod in a Swift project
#endif

For local development, add the module as a dependency in your package.json. Then install it and run react-native link. Projects that’ll use it will do the same.

Where to put the native SDK?

You should let the consumer of your library decide. The bridge shouldn’t include it but assume that it can import its header files. For iOS, applications usually install SDKs with CocoaPods. You should change your header search paths to look for header files in the Pods directory. The image below shows how to do it. We’re in node_modules/library_name/ios, so we need to move up three times to get to the application root. Then we move down to the Pods folder.

Header search path for SDKs that you install with CocoaPods

Including the SDK in the bridge is a bad idea. It introduces a transitive dependency, but that’s a topic for another story.

You can find our React Native Shopify bridge on GitHub. Stay tuned for the second part!

If you like what you read, please tap or click “♥︎” to help to promote this piece to others.


I work at Shoutem where I help creating tools to supercharge your React Native development.

One clap, two clap, three clap, forty?

By clapping more or less, you can signal to us which stories really stand out.