Repository files navigation

AWormhole allows your⚛️React Native application to consume components from a remote URL as if it were a localimport, enabling them to easily become remotely configurable at runtime!

🎬Watch the Demo!

⚠️ Implementors must take care to protect their Wormholes fromarbitrary code execution. Insufficient protection will put your user's data and device at risk. 💀 Please seeVerification and Signing for more information.

UsingYarn:

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-wormholecd my-new-wormholeyarn inityarn add --dev @babel/core @babel/cli @babel/preset-env @babel/preset-react

That should be enough. Insidemy-new-wormhole/, let's quickly create a simple component:

my-new-wormhole/MyNewWormhole.jsx:

import*asReactfrom'react';import{Animated,Alert,TouchableOpacity}from'react-native';functionCustomButton(){return(<TouchableOpacityonPress={()=>Alert.alert('Hello!')}><Animated.Textchildren="Click here!"/></TouchableOpacity>);}exportdefaultfunctionMyNewWormhole(){constmessage=React.useMemo(()=>'Hello, world!',[]);return(<Animated.Viewstyle={{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 byreact 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 betranspiled. Below, we useBabel to convertMyNewWormhole 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 producedMyNewWormhole.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 theExample Server.

👮Security Notice

In production environments, youmust serve content usingHTTPS to preventMan 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 usingEthers is shown in theExample App.

Finally, let's render our<App />! For the purpose of this tutorial, let's assume the file is served athttps://cawfree.com/MyNewWormhole.jsx:

import*asReactfrom'react';import{createWormhole}from'react-native-wormhole';const{ Wormhole}=createWormhole({verify:async()=>true,});exportdefaultfunctionApp(){return<Wormholesource={{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, aWormhole is only capable of consuming global functionality from two different modules;react andreact-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 aWormhole to render aWebView:

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 isnot a package manager!

Calls tocreateWormhole must at a minimum provide averify function, which has the following declaration:

readonlyverify:(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 theasync function does not returntrue, the request is terminated and the content will not be rendered via aWormhole. In theExample 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 headerx-csrf-token whose value is asignedMessage 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 scriptwill not be executed.

Making a call tocreateWormhole() also returns apreload function which can be used to asynchronously cache remote JSX before aWormhole has been mounted:

const{ preload}=createWormhole({verify:async()=>true});(async()=>{try{awaitpreload('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.

MIT