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:
import SafeModule from 'react-native-safe-modules';
module.exports = SafeModule.create({
moduleName: 'MyCustomScrollingModule',
mock: {
scrollTo: () => { },
},
overrides: {
7: {
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
.
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