react-native-safe-modules

A safe way to consume React Native NativeModules

Motivation

React Native enables a new aspect of mobile development: "Code Push". Code Push provides developers a way to push updates to their JS code base to mobile clients without going through the app store.

Since you can code push to older versions of the native client app, this type of deployment creates a new point of failure though: JavaScript code that is incompatible with the native version of the app it's running on.

React Native JS interacts with the Native code entirely through "Native Modules", which are injected at run-time onto the ReactNative.NativeModules namespace. As a result, having code that interacts with these modules directly can result in run-time errors. This library allows you to more safely interact with native modules, and provide version-specific overrides for the module, as well as mocks to use in the case that the method or module is entirely absent. The result is more robust code that can be code pushed to more users, as well as code that can be tested in an environment without a host app (e.g, Node).

Installation

npm i --save react-native-safe-modules

Usage

Importing SafeModule is as simple as:

import SafeModule from 'react-native-safe-modules';

Basic Usage

If you were using a Native Module before, such as NativeModules.FooModule like this:

import { NativeModules } from 'react-native';
const { FooModule } = NativeModules;

// ...

FooModule.doSomething().then(...)

You can instead do:

import SafeModule from 'react-native-safe-modules';
const FooModule = SafeModule.create({
  moduleName: 'FooModule',
  mock: {
    doSomething: () => Promise.resolve(...),
  },
});

// ...

FooModule.doSomething().then(...)

Version-Specific Overrides

By default, SafeModule assumes that you are exporting a constant VERSION with each Native Module that can be used to identify which version of the native module it is. If you would like to specify the version a different way, you are able to add a getVersion option to the SafeModule configuration which is a function expected to return the correct version of the module.

Often times you may need to make a breaking change to the API of your Native Module, but it can be made backwards compatible with SafeModule very easily.

For example, imagine we have a Scrolling module with a scrollTo(...) method.

In version "7" of the module, the method signature of scrollTo looked something like scrollTo(x: number, y: number, animated: true).

In the latest version of the module, we have changed the method signature to look something like: scrollTo(options: {x: number, y: number, animated: true}).

This is a breaking change, but we can make it backwards compatible with SafeModule:

// Scrolling.js
import SafeModule from 'react-native-safe-modules';

module.exports = SafeModule.create({
  moduleName: 'MyCustomScrollingModule',
  mock: {
    scrollTo: () => { /* do nothing */},
  },
  overrides: {
    7: {
      // overrides are defined as higher-order functions which are first
      // called with the real module's method, and are expected to return
      // a new function with the current API.
      scrollTo: oldScrollTo => options => {
        return oldScrollTo(options.x, options.y, !!options.animated);
      },
    },
  },
});

Module Name Changes

Sometimes we want to change the name of a Native Module. In this case, we need to support both versions of the name. SafeModule allows you to specify moduleName as an array of names. It will use the first name it finds.

For example, consider the case where we have a module named FooExperimentalModule, and we want to change the name of it to be just FooModule.

// FooModule.js
import SafeModule from 'react-native-safe-modules';

module.exports = SafeModule.create({
  moduleName: ['FooModule', 'FooExperimentalModule'],
  mock: {
    ...
  },
});

In this case, SafeModule will look for FooModule first, and then FooExperimentalModule if it is not found. Finally, it will fall back to the mock implementation if none is found.

API

SafeModule.create(options)

Parameters:

• options.moduleName: (required, string | Array<string>) the name, or array of names, to look for the module at on the NativeModules namespace.
• options.mock: (required, mixed) The mock implementation of the native module.
• options.getVersion: ((module) => string|number) Optional. A function that returns the version of the native module. Only needed if you are specifying overrides and not exporting a VERSION property on your native module. Defaults to x => x.VERSION.
• options.overrides: ({[version: string]: mixed) Optional. A map of version numbers to overridden implementations of the corresponding property/method. If an overridden property or method is a function, it will be called during SafeModule.create(...) with two arguments, the original value of that property on the original module, and the original module itself. The return value of this function will be put on the return value of SafeModule.create(...).
• options.isEventEmitter: (bool) Optional. A flag indicating that the native module is expected to be an EventEmitter. Puts the EventEmitter instance on the emitter property of the resulting module. Defaults to false.

TODO

• [ ] Implement onInit lifecycle method
• [ ] Implement onNoModuleFound lifecycle method
• [ ] Implement onVersionFound lifecycle method
• [ ] Implement onOverrideUsed lifecycle method
• [ ] Implement onOverrideCalled lifecycle method