Adding Web3 to Your Legacy Site with Web3Modal

As blockchain adoption accelerates, legacy websites need seamless Web3 integration. Web3Modal is a modular JavaScript library that simplifies wallet connections, supporting MetaMask, WalletConnect, and many others. This guide covers everything from setup to advanced customization, ensuring a smooth transition to Web3 capabilities.

Why Use Web3Modal

Unified UX: One dialog to connect any wallet.
Modularity: Plug in providers like MetaMask, WalletConnect, Torus, and more.
Customizable: Theme, network filtering, caching options.
Lightweight: Minimal footprint, tree-shakable.

Prerequisites

Basic JavaScript/TypeScript knowledge.
Familiarity with Ethers.js or Web3.js.
Access to an RPC provider: Infura or Alchemy.

1. Installation Setup

Install via npm or yarn:

npm install web3modal ethers

yarn add web3modal ethers

Import key modules:

import Web3Modal from web3modal
import { ethers } from ethers

2. Basic Integration (Vanilla JS)

2.1. Configuration Object

Property	Type	Description
network	string	Default chain (e.g., mainnet, rinkeby).
cacheProvider	boolean	Enable session caching.
providerOptions	object	Specify wallet providers and settings.

2.2. Sample Code

const providerOptions = {
nbspnbspwalletconnect: {
nbspnbspnbspnbsppackage: WalletConnectProvider,
nbspnbspnbspnbspoptions: {
nbspnbspnbspnbspnbspnbspinfuraId: YOUR_INFURA_ID
nbspnbspnbspnbsp}
nbspnbsp}
}

const web3Modal = new Web3Modal({
nbspnbspnetwork: mainnet,
nbspnbspcacheProvider: true,
nbspnbspproviderOptions
})

async function connectWallet() {
nbspnbspconst instance = await web3Modal.connect()
nbspnbspconst provider = new ethers.providers.Web3Provider(instance)
nbspnbspconst signer = provider.getSigner()
nbspnbspconsole.log(await signer.getAddress())
}

3. React Integration

Leverage React hooks for state management.

3.1. useWeb3Modal Hook

import React, { useState, useEffect } from react
import Web3Modal from web3modal
import { ethers } from ethers

function useWeb3Modal() {
nbspnbspconst [provider, setProvider] = useState(null)
nbspnbspconst [signer, setSigner] = useState(null)

nbspnbspuseEffect(() => {
nbspnbspnbspnbsp// Auto-connect if cached
nbspnbspnbspnbspif (web3Modal.cachedProvider) connect()
nbspnbsp}, [])

nbspnbspasync function connect() {
nbspnbspnbspnbspconst instance = await web3Modal.connect()
nbspnbspnbspnbspconst web3Provider = new ethers.providers.Web3Provider(instance)
nbspnbspnbspnbspsetProvider(web3Provider)
nbspnbspnbspnbspsetSigner(web3Provider.getSigner())
nbspnbsp}

nbspnbspreturn { provider, signer, connect }
}

export default useWeb3Modal

3.2. Usage in Component

Display connect button when no signer.
Show wallet address and allow transactions upon connection.

4. Advanced Customization

4.1. Theming

Override default styles via theme object:

const web3Modal = new Web3Modal({
nbspnbsptheme: {
nbspnbspnbspnbspbackground: rgb(250,250,255),
nbspnbspnbspnbspmain: rgb(0, 95, 255),
nbspnbspnbspnbsp>secondary: rgb(20,20,42)
nbspnbsp}
})

4.2. Network Filtering

Restrict wallets to approved chains:

const web3Modal = new Web3Modal({
nbspnbspnetwork: rinkeby,
nbspnbspproviderOptions
})

5. Error Handling Best Practices

Try/Catch: Wrap connect() calls to manage rejections.
State Sync: Listen to accountsChanged and chainChanged events on the provider instance.
Security: Always validate on-chain data server-side before performing sensitive operations.

6. Server-Side SSR Considerations

Legacy sites often use Next.js or other SSR frameworks. Since Web3Modal requires window context:

Load web3modal only in useEffect or dynamic import with ssr:false.
Maintain session state in cookies/localStorage to rehydrate on client.

7. Performance Bundle Optimization

Tree Shaking: Import only necessary provider packages.
Lazy Load: Defer modal code until user interaction.
CDN: For minimal overhead, consider loading web3modal.min.js from an optimized CDN.

8. Security Compliance

Ensure user is informed about permissions requested by wallets.
Never expose private keys or secret RPC endpoints in client code.
Validate and sanitize on-chain data server-side (OWASP Blockchain Security).

Conclusion

Integrating Web3Modal into a legacy site transforms it into a modern Web3-enabled platform with minimal effort. From simple wallet connections to advanced theming and SSR support, Web3Modal provides the flexibility needed by both small projects and enterprise-grade applications.

For more information and advanced guides, visit the official documentation at web3modal.com and explore the Ethers.js docs.

Adding Web3 to Your Legacy Site with Web3Modal