deploy-react-frontend

name

deploy-react-frontend

description

Create React frontends for Algorand dApps with wallet integration. Use when creating React frontends that interact with smart contracts, setting up wallet connections (Pera, Defly, Exodus), integrating typed app clients with wallet signers, or building dApp UIs that call contract methods. Strong triggers include "create a frontend for my contract", "add wallet connection to my React app", "how do I call my contract from the frontend?", "set up use-wallet with my typed client", "connect Pera wallet to my dApp", "algorand.setSigner".

Deploying React Frontends for Algorand

Build React applications that connect to Algorand wallets and interact with smart contracts using typed clients.

Prerequisites

Before using this skill, ensure:

1. Smart contract is deployed with a known App ID
2. ARC-56/ARC-32 app spec exists (e.g., MyContract.arc56.json)
3. React project is set up (Vite, Next.js, or Create React App)

Core Workflow: The "Signer Handoff" Pattern

The key insight is passing the wallet's transaction signer to AlgorandClient, which then provides it to typed app clients:

Wallet (use-wallet) → transactionSigner
                              ↓
                    AlgorandClient.setSigner()
                              ↓
                    Typed App Client (defaultSender)
                              ↓
                    Contract Method Calls (auto-signed)

How to proceed

Step 1: Generate Typed Client

Generate a TypeScript client from your contract's app spec:

algokit generate client path/to/MyContract.arc56.json --output src/contracts/MyContractClient.ts

This creates a typed client with full IntelliSense for your contract's methods.

Step 2: Install Dependencies

Core packages:

npm install @algorandfoundation/algokit-utils @txnlab/use-wallet-react algosdk

Wallet peer dependencies (install only for wallets you're using):

Wallet	Package
Pera	@perawallet/connect
Defly	@blockshake/defly-connect
Kibisis	@agoralabs-sh/avm-web-provider
Lute	lute-connect

Example for Pera + Defly:

npm install @perawallet/connect @blockshake/defly-connect

Step 3: Set Up WalletProvider

Wrap your app with WalletProvider at the root level:

import { NetworkId, WalletId, WalletManager, WalletProvider } from '@txnlab/use-wallet-react'

const walletManager = new WalletManager({
  wallets: [WalletId.PERA, WalletId.DEFLY, WalletId.EXODUS],
  defaultNetwork: NetworkId.TESTNET,
})

export default function App() {
  return (
    <WalletProvider manager={walletManager}>
      <YourApp />
    </WalletProvider>
  )
}

Step 4: Create Wallet Connection UI

Use the useWallet() hook to display available wallets:

import { useWallet } from '@txnlab/use-wallet-react'

function ConnectWallet() {
  const { wallets, activeAddress } = useWallet()

  if (activeAddress) {
    return <p>Connected: {activeAddress}</p>
  }

  return (
    <div>
      {wallets.map((wallet) => (
        <button key={wallet.id} onClick={() => wallet.connect()}>
          Connect {wallet.metadata.name}
        </button>
      ))}
    </div>
  )
}

Step 5: Integrate Typed Client with Wallet Signer

This is the critical integration step. Register the wallet's signer with AlgorandClient:

import { useWallet } from '@txnlab/use-wallet-react'
import { AlgorandClient } from '@algorandfoundation/algokit-utils'
import { MyContractClient } from './contracts/MyContractClient'

function ContractInteraction() {
  const { transactionSigner, activeAddress } = useWallet()

  const callContract = async () => {
    if (!activeAddress || !transactionSigner) {
      alert('Please connect your wallet first')
      return
    }

    // 1. Create AlgorandClient for the network
    const algorand = AlgorandClient.testNet()

    // 2. Register wallet signer with AlgorandClient
    algorand.setSigner(activeAddress, transactionSigner)

    // 3. Create typed client with wallet as default sender
    const appClient = algorand.client.getTypedAppClientById(MyContractClient, {
      appId: 12345n, // Your deployed App ID
      defaultSender: activeAddress,
    })

    // 4. Call contract methods - signer is used automatically
    const result = await appClient.send.myMethod({ args: { value: 42n } })
    console.log('Result:', result.return)
  }

  return <button onClick={callContract}>Call Contract</button>
}

Step 6: Deploy New Contracts (Optional)

If deploying from the frontend (less common), use the Factory pattern:

import { MyContractFactory } from './contracts/MyContractClient'

const factory = new MyContractFactory({
  algorand,
  defaultSender: activeAddress,
})

const { appClient } = await factory.deploy({
  onSchemaBreak: 'append',
  onUpdate: 'append',
})

Important Rules / Guidelines

1. Always call setSigner() before creating clients - The signer must be registered with AlgorandClient first
2. Check for null activeAddress and transactionSigner - They are null when no wallet is connected
3. Use TypeScript - Typed clients provide full type safety and IntelliSense
4. Match networks - Ensure AlgorandClient network matches WalletManager network
5. React only - This skill covers React; other frameworks have different patterns

Getting the App Client

Three ways to get a typed app client:

Method	Use Case
getTypedAppClientById()	Known App ID (most common for frontends)
getTypedAppClientByCreatorAndName()	Resolve by creator address and app name
factory.deploy()	Deploy new instance and get client

// By App ID (recommended for frontends)
const appClient = algorand.client.getTypedAppClientById(MyContractClient, {
  appId: 12345n,
  defaultSender: activeAddress,
})

// By Creator and Name
const appClient = await algorand.client.getTypedAppClientByCreatorAndName(
  MyContractClient,
  {
    creatorAddress: 'CREATORADDRESS...',
    appName: 'MyContract',
  }
)

Common Errors / Troubleshooting

Error	Cause	Solution
activeAddress is null	Wallet not connected	Check wallet connection before contract calls
transactionSigner is undefined	No active wallet	Prompt user to connect wallet first
signer not found for address	Signer not registered	Call algorand.setSigner(activeAddress, transactionSigner)
app does not exist	Wrong App ID	Verify App ID matches deployed contract
Method not found	Wrong method name or signature	Check typed client API; ensure args match ABI
Network mismatch	Different networks	Ensure AlgorandClient and WalletManager use same network
User rejected transaction	User cancelled in wallet	Handle rejection gracefully in UI
global is not defined	algosdk references global in browser	Add to vite.config.ts: define: { global: 'globalThis' }
TypeScript errors in generated client	Strict TS mode incompatibility	Set verbatimModuleSyntax: false in tsconfig.json

Wallet Disconnect

Handle wallet disconnection:

function DisconnectButton() {
  const { wallets } = useWallet()

  const disconnect = async () => {
    const activeWallet = wallets.find((w) => w.isActive)
    if (activeWallet) {
      await activeWallet.disconnect()
    }
  }

  return <button onClick={disconnect}>Disconnect</button>
}

References / Further Reading

• REFERENCE.md - Detailed API reference
• EXAMPLES.md - Complete code examples
• use-wallet Documentation
• AlgoKit Utils TypeScript
• Typed App Clients