In this guide, we will build a basic React App with the Wally Web3 Modal. After completing this walkthrough, you will have an understanding of how to create an App on Wally, the end-to-end user onboarding flow using Wally, and how you can start using Wally when building new Web3 apps.

What is Wally?

A major goal of any product, Web3 or not, is to increase the number of users using the product. What is unique to Web3 products is that there are some obstacles that are stopping the user growth of your Web3 project. The main source of this is requiring users to create and manage their own crypto wallets.

Wally is the solution. Wally enables users to onboard to your Web3 product the same way they would onboard to any other product - using their email. Building on top of the popular Web3 Modal, Wally focuses on building a great onboarding experience for both users and developers.

Enough talking, let's start building!

What You Need

React

We will be using `create-react-app` for this guide but the code will be the same if you prefer to use Vite or another way to start building React Apps.

Start by creating a React App. You can call it whatever you want, for this guide we will use the name `wally-react`

npx create-react-app wally-react

Wally Web3 Modal + Web3 Packages

Now we will install the Wally and Web3 NPM packages. The Wally package looks very similar to the “web3modal” package but it comes with a bit of Wally magic to power the email onboarding experience.

npm install wally-web3modal web3

Important Note - Web3 NPM Package

There is a known issue with the Web3 package and `create-react-app`. If you are using a version of Web3 that is less than 1.8.0 then please follow these instructions.

Part 1 - App Setup

The Wally Dashboard

Creating an App

‍

The first thing we will do is create an app on the Wally Dashboard. A Wally App is the hub for all the user wallets, analytics, contracts, and logs for your application.

You can create an application by clicking on the `Get Started` link on the Wally app welcome page. You will need to create an account if you don't have one.

‍

‍

After logging in or creating your account, you will see the main dashboard that has a list of your created apps. If you have not created an app before, this list will be empty.

Let's now create an app by clicking the `Create` button:

‍

From here you will need to fill out some information about the app:

- App Name - This is for you to easily track all your apps using Wally

- Website URL - We love to promote builders and see Wally in action. If you don't have an active URL now, that is ok!

- Environment - This is the network that you want the app to be active on. We are continuing to support more networks. For this tutorial, we will use the `Goerli (Ethereum Testnet)`

‍

Getting Your API Credentials + Client ID

‍

Once you have created an application, you will receive your API credentials. We will not be using these credentials in this guide but it is good to store these in a safe place if you do decide to use the Wally API in a future project. You can always regenerate them later if needed however.

We will be using the `Client ID` of your Application. You will find this by going to the Wally Dashboard, clicking the name of your application, and then clicking on the `...` and selecting `Get Client ID`.

‍

‍

‍

After clicking on `Get Client ID` you will see your App's Client ID. We will use this later when setting up the configuration of the Wally Web3 Modal so save this somewhere until then.

Setting Up a Redirect URL

‍

From this page you can also create a Redirect URL. This is the URL that users are redirected to after they have completed your onboarding flow. For this tutorial and to increase our pageviews ;) we will use `https://www.wally.xyz/`

Now we have set up everything on the Wally Dashboard to get our app up and running, let's go to our code editor and start building the app!

‍

Part 2 - The Code

Worker.JS

To keep the onboarding flow streamlined, Wally opens another tab after the user has entered their emails in the modal. This allows them to enter a One-Time-Password that is sent to confirm their email:

The `Worker.JS` file powers this experience. You will need to create a new file called Worker.js and place it wherever you are serving static pages.

For this guide, we will place it in the `Public` folder of our React App

‍

‍

Here is the code for the Worker.JS file:

"use strict";
const _self = self;
_self.ports = [];
const broadcast = (e) => {
    _self.ports.forEach((p) => p.postMessage(e.data));
};
_self.onconnect = function (e) {
    const port = e.ports[0];
    _self.ports.push(port);
    port.addEventListener('message', broadcast);
    port.start();
};

To verify that this has loaded correctly, you can run `npm start` and go to `http://localhost:3000/worker.js`. You should see the code you entered in the browser now.

Edits to App.JS

Now we will add the code to our App.JS file (src/App.JS). Below is the complete code but we will also look at this in blocks:

import Web3 from "web3";
import Web3Modal from "wally-web3modal";
import { useState, useEffect } from 'react';

function App() {

  const [web3Modal, setWeb3Modal] = useState(null)
  useEffect(() => {
    const providerOptions = {}
    const newWeb3Modal = new Web3Modal({
      cacheProvider: true,
      network: "mainnet",
      providerOptions,  
      wallyClientId: "[INSERT CLIENT ID]"  // required
    })
    setWeb3Modal(newWeb3Modal)
  }, [])
  async function onConnect() {
    const provider = await web3Modal.connect();
    const web3 = new Web3(provider);
    provider.enable();
  }
  return (<button onClick={onConnect}>Connect</button>)
}

export default App;

‍

Most of this will be familiar to you if you have ever built a React application before. We are importing the packages we will be using and managing the [state of our Modal](https://beta.reactjs.org/learn/managing-state) which we have named Web3Modal.

‍

Web3Modal Settings

As mentioned earlier, Wally is built on top of Web3Modal. This means you can use the same configuration options as you would with Web3Modal.

The main difference here is that we are also adding the Wally Client ID that we got from the Wally Dashboard earlier in this guide:

const providerOptions = {}

    const newWeb3Modal = new Web3Modal({
      cacheProvider: true,
      network: "mainnet",
      providerOptions,
      wallyClientId: "[INSERT CLIENT ID]"  // required
    });
    setWeb3Modal(newWeb3Modal)
  }, [])

For this guide, we have not added any additional Wallet providers but this can is done in the `providerOptions` object.

**IMPORTANT NOTE:** It is also best practice to store your client in an environment variable so it is not shown when sharing your code.

Connecting to Web3 Modal

After we have set up the configuration of our modal, we need to add a function that connects to web3Modal to enable the providers. In this case, we will be enabling Wally to load in the modal.

 
 async function onConnect() {
    const provider = await web3Modal.connect();
    const web3 = new Web3(provider);
    provider.enable();

  }

As we said, this is a simple demo, and won't be winning any design awards. So we will render a simple button to run our function:

return (<button onClick={onConnect}>Connect</button>)

Part 3 - Running the App

After making the changes to the `App.js` file, we are now ready to run our application! Run `npm start` in the terminal.

If everything has been set correctly, you should see a little lonely `Connect` button on your browser page like so:

‍

‍

‍

If you are receiving any errors or issues, check at the bottom of this guide for potential fixes.

After clicking on the `Connect` button you will set your brand new Wally Web3 Modal popup to start the onboarding process!

Make sure to enter a real email that you have access to as the next step will be to `Submit` your email and receive the On Time Password to log in. This is done after the new tab has opened up after clicking submit:

‍

Check your email and you should have received an email with this one-time password. Enter that password in the modal and click `Log In`. This should now take you to the `Redirect URL` we set up earlier.

To check if everything worked correctly, head over to the Wally Dashboard of the app you created. From there, you will see a new user wallet created for the email you used:

‍

‍

Part 4 - Next Steps

Congratulations on integrating Wally into a React App!

Now that you have an understanding of the development steps and user flow, you can start adding Wally to your Web3 projects to unlock a whole group of users who don't have crypto wallets.

‍

Stay tuned for more guides on how you can use Wally with other tools you might be using already like Zapier, Google Forms as well as popular Web3 services like ThirdWeb and Alchemy.

‍

Listed below are some known errors/issues you might receive and how to fix them. Feel free to ping us on Twitter if you get stuck!

Known Issues

Error: The top-level-await experiment is not enabled

This is fixed by changing the config settings in your Webpack.config.js file. Find more information here.

‍

Module Warning (from ./node_modules/source-map-loader/dist/cjs.js):

This is only a warning but the messages can be ignored by changing the config setting in your Webpack.config.js file. Find more information here.

‍