A Wormhole
allows your โ๏ธ React Native application to consume components from a remote URL as if it were a local import
, enabling them to easily become remotely configurable at runtime!
โ ๏ธ Implementors must take care to protect their Wormholes from arbitrary code execution. Insufficient protection will put your user's data and device at risk. ๐ Please see Verification and Signing for more information.
Using Yarn:
yarn add react-native-wormhole
Next, you'll need a component to serve. Let's create a quick project to demonstrate how this works:
mkdir my-new-wormhole
cd my-new-wormhole
yarn init
yarn add --dev @babel/core @babel/cli @babel/preset-env @babel/preset-react
That should be enough. Inside my-new-wormhole/
, let's quickly create a simple component:
my-new-wormhole/MyNewWormhole.jsx
:
import * as React from 'react';
import { Animated, Alert, TouchableOpacity } from 'react-native';
function CustomButton() {
return (
<TouchableOpacity onPress={() => Alert.alert('Hello!')}>
<Animated.Text children="Click here!" />
</TouchableOpacity>
);
}
export default function MyNewWormhole() {
const message = React.useMemo(() => 'Hello, world!', []);
return (
<Animated.View style={{ flex: 1, backgroundColor: 'red' }}>
<Animated.Text>{message}</Animated.Text>
<CustomButton />
</Animated.View>
);
}
๐ค What syntax am I allowed to use?
By default, you can use all functionality exported by
react
andreact-native
. The only requirement is that you mustexport default
the Component that you wish to have served through theWormhole
.
Now our component needs to be transpiled. Below, we use Babel to convert MyNewWormhole
into a format that can be executed at runtime:
npx babel --presets=@babel/preset-env,@babel/preset-react MyNewWormhole.jsx -o MyNewWormhole.js
After doing this, we'll have produced MyNewWormhole.js
, which has been expressed in a format that is suitable to serve remotely. If you're unfamiliar with this process, take a quick look through the contents of the generated file to understand how it has changed.
Next, you'd need to serve this file somewhere. For example, you could save it on GitHub, IPFS or on your own local server. To see an example of this, check out the Example Server.
๐ฎ Security Notice
In production environments, you must serve content using HTTPS to prevent Man in the Middle attacks. Additionally, served content must be signed using public-key encryption to ensure authenticity of the returned source code. A demonstration of this approach using Ethers is shown in the Example App.
Finally, let's render our <App />
! For the purpose of this tutorial, let's assume the file is served at https://cawfree.com/MyNewWormhole.jsx:
import * as React from 'react';
import { createWormhole } from 'react-native-wormhole';
const { Wormhole } = createWormhole({
verify: async () => true,
});
export default function App() {
return <Wormhole source={{ uri: 'https://cawfree.com/MyNewWormhole.jsx' }} />;
}
And that's everything! Once our component has finished downloading, it'll be mounted and visible on screen. ๐
By default, a Wormhole
is only capable of consuming global functionality from two different modules; react
and react-native
, meaning that only "vanilla" React Native functionality is available. However, it is possible to introduce support for additional modules. In the snippet below, we show how to allow a Wormhole
to render a WebView
:
const { Wormhole } = createWormhole({
+ global: {
+ require: (moduleId: string) => {
+ if (moduleId === 'react') {
+ return require('react');
+ } else if (moduleId === 'react-native') {
+ return require('react-native');
+ } else if (moduleId === 'react-native-webview') {
+ return require('react-native-webview);
+ }
+ return null;
+ },
+ },
verify: async () => true,
});
โ ๏ธ Version changes toreact
,react-native
or any other dependencies your Wormholes consume may not be backwards-compatible. It's recommended that APIs serving content to requestors verify the compatibility of the requester version to avoid serving incompatible content.react-native-wormhole
is not a package manager!
Calls to createWormhole
must at a minimum provide a verify
function, which has the following declaration:
readonly verify: (response: AxiosResponse<string>) => Promise<boolean>;
This property is used to determine the integrity of a response, and is responsible for identifying whether remote content may be trusted for execution. If the async
function does not return true
, the request is terminated and the content will not be rendered via a Wormhole
. In the Example App, we show how content can be signed to determine the authenticity of a response:
+ import { ethers } from 'ethers';
+ import { SIGNER_ADDRESS, PORT } from '@env';
const { Wormhole } = createWormhole({
+ verify: async ({ headers, data }: AxiosResponse) => {
+ const signature = headers['x-csrf-token'];
+ const bytes = ethers.utils.arrayify(signature);
+ const hash = ethers.utils.hashMessage(data);
+ const address = await ethers.utils.recoverAddress(
+ hash,
+ bytes
+ );
+ return address === SIGNER_ADDRESS;
+ },
});
In this implementation, the server is expected to return a HTTP response header x-csrf-token
whose value is a signedMessage
of the response body. Here, the client computes the expected signing address of the served content using the digest stored in the header.
If the recovered address is not trusted, the script will not be executed.
Making a call to createWormhole()
also returns a preload
function which can be used to asynchronously cache remote JSX before a Wormhole
has been mounted:
const { preload } = createWormhole({ verify: async () => true });
(async () => {
try {
await preload('https://cawfree.com/MyNewWormhole.jsx');
} catch (e) {
console.error('Failed to preload.');
}
})();
Wormholes dependent upon the external content will subsequently render immediately if the operation has completed in time. Meanwhile, concurrent requests to the same resource will be deduped.