@walletconnect/react-native-dapp

A drop-in library which helps easily connect your React Native dapps to Ethereum Wallets on Android, iOS and the Web.

Notice: This library assumes you have already enabled prerequisite support for Web3 inside your application. This can be done by creating a new project using npx create-react-native-dapp, or by introducing support for Web3 in an existing project by using npx rn-nodeify --install --hack.

For more details, check out the documentation.

Installing

To get started, install @walletconnect/react-native-dapp:

yarn add @walletconnect/react-native-dapp

If you haven't already, you may also need to install react-native-svg alongside a persistent storage provider such as @react-native-async-storage/async-storage:

yarn add react-native-svg @react-native-async-storage/async-storage

Architecture

This library is implemented using the React Context API, which is used to help make an instance of a connector accessible globally throughout your application. This permits you to use a uniform instance within even deeply nested components, and ensures your rendered application is always synchronized against the connector state.

WalletConnectProvider

At the root of your application, you can declare a WalletConnectProvider which controls access and persistence to a connector instance:

import * as React from 'react';
import WalletConnectProvider from '@walletconnect/react-native-dapp';
import AsyncStorage from '@react-native-async-storage/async-storage';

export default function App(): JSX.Element {
  return (
    <WalletConnectProvider
      redirectUrl={Platform.OS === 'web' ? window.location.origin : 'yourappscheme://'}
      storageOptions= {{
        asyncStorage AsyncStorage,
      }}>
      <>{/* awesome app here */}</>
    </WalletConnectProvider>
  );
}

Above, we pass the WalletConnectProvider two required parameters; redirectUrl and storageOptions:

• The redirectUrl is used to help control navigation between external wallets and your application. On the web, you only need to specify a valid application route; whereas on mobile platforms, you must specify a deep link URI scheme.
• The storageOptions prop allows you to specify the storage engine which must be used to persist session data.
  • Although in our examples we use @react-native-async-storage/async-storage, this can be which engine you please, provided it conforms to the IAsyncStorage generic storage interface declaration.

Notably, the WalletConnectProvider optionally accepts WalletConnect configuration arguments as defined by the IWalletConnectOptions interface:

import * as React from 'react';
import WalletConnectProvider from '@walletconnect/react-native-dapp';
import AsyncStorage from '@react-native-async-storage/async-storage';

export default function App(): JSX.Element {
  return (
    <WalletConnectProvider
      bridge="https://bridge.walletconnect.org"
      clientMeta={{
        description: 'Connect with WalletConnect',
        url: 'https://walletconnect.org',
        icons: ['https://walletconnect.org/walletconnect-logo.png'],
        name: 'WalletConnect',
      }}
      redirectUrl={Platform.OS === 'web' ? window.location.origin : 'yourappscheme://'}
      storageOptions= {{
        asyncStorage AsyncStorage,
      }}>
      <>{/* awesome app here */}</>
    </WalletConnectProvider>
  );
}

In the snippet above, aside from the required props, we can see the default configuration of the WalletConnectProvider.

Tip: Your custom options are merged deeply against this default configuration. Therefore it's possible to override individual nested properties without being required to define all of them.

withWalletConnect

Alternatively to manually using the WalletConnectProvider, you can use the withWalletConnect higher order component which will wrap your root application in a WalletConnectProvider for you:

import * as React from 'react';
import { withWalletConnect, useWalletConnect } from '@walletconnect/react-native-dapp';
import AsyncStorage from '@react-native-async-storage/async-storage';

function App(): JSX.Element {
  const connector = useWalletConnect(); // valid
  return <>{/* awesome app here */}</>;
}

export default withWalletConnect(App, {
  clientMeta: {
    description: 'Connect with WalletConnect',
  },
  redirectUrl: Platform.OS === 'web' ? window.location.origin : 'yourappscheme://',
  storageOptions: {
    asyncStorage: AsyncStorage,
  },
});

This is almost identical in functionality to the manual implementation of a WalletConnectProvider, with the key difference that we're able to make a call to useWalletConnect directly from the App component. By contrast, in the previous example only child components of the WalletConnectProvider may be able to invoke this hook.

useWalletConnect

The useWalletConnect hook provides access to a WalletConnect connector instance which is accessible on Android, iOS and the Web. This conforms to the original specification:

import AsyncStorage from '@react-native-async-storage/async-storage';
import { useWalletConnect, withWalletConnect } from '@walletconnect/react-native-dapp';
import * as React from 'react';

function App(): JSX.Element {
  const connector = useWalletConnect();
  if (!connector.connected) {
    /**
     *  Connect! 🎉
     */
    return <Button title="Connect" onPress={() => connector.connect())} />;
  }
  return <Button title="Kill Session" onPress={() => connector.killSession()} />;
}

export default withWalletConnect(App, {
  redirectUrl: Platform.OS === 'web' ? window.location.origin : 'yourappscheme://',
  storageOptions: {
    asyncStorage AsyncStorage,
  },
});

Customization

@walletconnect/react-native-dapp also permits you to customize the presentation of the QrcodeModal. This is achieved by passing the Render Callback prop, renderQrcodeModal, to our calls to withWalletConnect or instances of WalletConnectProvider.

For example, you could choose to render a wallet selection using a BottomSheet opposed to a Modal:

import AsyncStorage from '@react-native-async-storage/async-storage';
import BottomSheet from 'react-native-reanimated-bottom-sheet';
import { Image, Text, TouchableOpacity } from 'react-native';
import {
  useWalletConnect,
  withWalletConnect,
  RenderQrcodeModalProps,
  WalletService,
} from '@walletconnect/react-native-dapp';
import * as React from 'react';

function CustomBottomSheet({
  walletServices,
  visible,
  connectToWalletService,
  uri,
}: RenderQrcodeModalProps): JSX.Element {
  const renderContent = React.useCallback(() => {
    return walletServices.map((walletService: WalletService, i: number) => (
      <TouchableOpacity key={`i${i}`} onPress={() => connectToWalletService(walletService, uri)}>
        <Image source={{ uri: walletService.logo }} />
        <Text>{walletService.name}</Text>
      </TouchableOpacity>
    ));
  }, [walletServices, uri]);
  return <BottomSheet renderContent={renderContent} {...etc} />;
};

function App(): JSX.Element {
  const connector = useWalletConnect();
  return <>{/* awesome custom app here */}</>;
}

export default withWalletConnect(App, {
  redirectUrl: Platform.OS === 'web' ? window.location.origin : 'yourappscheme://',
  storageOptions: {
    asyncStorage AsyncStorage,
  },
  renderQrcodeModal: (props: RenderQrcodeModalProps): JSX.Element => (
    <CustomBottomSheet {...props} />
  ),
});