Web3-webpacked-react NPM

Web3: Webpacked - React

Example GIF

This is a fully compatible port of the web3-webpacked library for use in React projects.

The module consists of:

A robust management framework for the global web3 object injected into browsers by MetaMask, Trust, etc. The framework exposes an instantiated web3.js instance, the current account, and network ID via a React Context available to all children of the provided Web3Provider component.
Generic utility functions that fetch Ether and ERC20 balances, sign data, format Etherscan links, expose npm packages, etc.
A fully managed solution for sending transactions that abstracts away from common annoyances like estimating gas usage and fetching current gas prices.

This project was partially inspired/derived from react-web3, which unfortunately uses the deprecated React Context API.

Example Projects

Projects using web-webpacked-react include:

Snowflake Dashboard

Open a PR to add your project to this list!

Installation

To install the npm package:

npm install web3-webpacked-react

Usage

The package exports 3 objects:

Web3Provider. The default export. This component should be a parent to any component that needs access to the web3 context.
Web3Consumer: This consumer object is exposed so that users may employ render props rather than using an HOC.
withWeb3: This HOC provides a web3 context to specific components by injecting a w3w object into this.props.

Recommended - Use `web3-webpacked-react` with Render Props

An example implementation using render props might look like:

import React from 'react'
import Web3Provider, { Web3Consumer } from 'web3-webpacked-react'

const Page = (
  <Web3Provider supportedNetworks={[1]} ...>
    <Web3Consumer>
      {context =>
        ...
      }
    </Web3Consumer>
  </Web3Provider>
)

ReactDOM.render(Page, document.getElementById('root'))

Any component inside the Web3Consumer render prop will have access to web3 variables via the context object. Note that this pattern will work for arbitrarily deeply nested components, i.e. the consumer doesn't necessarily need to be at the root of your app. There also won't be performance concerns if you choose to use multiple Web3Consumers at different nesting levels.

This component accepts two optional props: recreateOnNetworkChange and recreateOnAccountChange. Both true by default, these flags control whether children components are freshly re-rendered upon network and account changes, respectively. Re-renders are typically the desired behavior (for example, the calculated balance of a user account should be updated automatically on account change). For more information on derived state, see this article on derived state in React..

Not Recommended - Use `web3-webpacked-react` with HOCs

Note that HOCs are less than ideal for a number of reasons, and using render props is strictly preferred. If you prefer to use HOCs instead, your code might look like the following (assuming that there is a Web3Provider parent somewhere in your tree):

import React, { Component } from 'react'
import { withWeb3 } from 'web3-webpacked-react';

const MyApp = class MyApp extends Component {...}

export default withWeb3(MyApp)

Any component wrapped in withWeb3 can access the web3 context via the this.props.w3w object. Note that whatever high-level component which includes your <Web3Provider>...</Web3Provider> declaration cannot be wrapped with the withWeb3 HOC. if you require the web3 context in such an instance, use the render props pattern.

Functionality

Regardless of how it's injected, the provided context looks like the following:

{
  web3js: ...,
  account: ...,
  networkId: ...,
  ...
}

The many functions available in the context are documented in the web3-webpacked README.

`props`

Web3Provider takes 4 optional props:

Web3Provider.propTypes = {
  screens:           PropTypes.shape({
    initializing:       PropTypes.any,
    noWeb3:             PropTypes.any,
    permissionNeeded:   PropTypes.any,
    unlockNeeded:       PropTypes.any,
    unsupportedNetwork: PropTypes.any,
    web3Error:          PropTypes.any
  }),
  pollTime:          PropTypes.number,
  supportedNetworks: PropTypes.arrayOf(PropTypes.number),
  children:          PropTypes.node
}

screens: These must be React components which will be displayed accordingly depending on the state of the user's browser.

initializing: Shown when web3 is being initialized. This screen is typically displayed very briefly, and accordingly the default initialization screen only appears after 1 second of initializing (which really only happens on very slow network connections, or if the app is e.g. waiting for user permission when requesting account access).
noWeb3: Shown when no injected web3 variable is found. The default screen encourages users to install MetaMask/download Trust.
permissionNeeded: Shown when users deny permission to access their account (a pattern that will be enabled as of November 2, 2018). Right now, denying access disallows any usage of the app. If this is an issue for your use case, i.e. if your dApp supports read-only experiences, please file an issue or submit a PR!
unlockNeeded: Shown when no account is available. The default screen encourages users to unlock their wallet. This could possibly be combined with the permissionNeeded screen. Suggestions/PRs welcome!
unsupportedNetwork: Shown when the user is on a network not in the supportedNetworks list. The default screen encourages users to connect to any of the networks in supportedNetworks. The list of names of supported networks is passed to this component as a supportedNetworkNames prop.
web3Error: Shown whenever a web3 error occurs in the polling process for account and network changes. The error is passed to this component as an error prop.

pollTime: The poll interval (in milliseconds). The current recommendation is to poll for account and network changes.
supportedNetworks: Enforces that the web3 instance is connected to a particular network. If the detected network id is not in the passed list, the unsupportedNetwork screen will be shown. Supported network ids are: 1, 3, 4, and 42.
children: React Components, within a context render prop or wrapped with the withWeb3 HOC.

Default props

The default values for these props are shown below (to see the default screens, just play around with the CodeSandbox sample app or check out the implementation).

Web3Provider.defaultProps = {
  screens:           {
    initializing:       ...,
    noWeb3:             ...,
    unlockNeeded:       ...,
    unsupportedNetwork: ...,
    web3Error:          ...,
  pollTime:          1000,
  supportedNetworks: [1, 3, 4, 42],
  children:          ''
}