Mini Apps

Appearance

Setting up a React App with MiniPay ​

This guide shows how to set up a React project with MiniPay wallet integration. We'll use Vite, TypeScript, and Wagmi for wallet interactions.

Create Your Project ​

Create a new React app using Vite:

bash
npm create vite@latest
# or
pnpm create vite
# or
bun create vite
# or
yarn create vite

Choose:

  • Framework: React
  • Variant: TypeScript

Then install dependencies:

bash
cd mini-app
npm install
# or pnpm install / bun install / yarn install

Install Wallet Dependencies ​

Install Wagmi, Viem, and React Query for wallet integration:

bash
npm install wagmi viem@2.x @tanstack/react-query
# or pnpm add / bun add / yarn add

Configure Wagmi for MiniPay ​

Create a wagmi.ts file in your src directory:

ts
import { http } from "viem";
import { createConfig } from "wagmi";
import { injected } from "wagmi/connectors";
import { celo, celoSepolia } from "wagmi/chains";

export const config = createConfig({
  chains: [celo, celoSepolia],
  connectors: [
    injected(), // MiniPay injects window.ethereum
  ],
  transports: {
    [celo.id]: http(),
    [celoSepolia.id]: http(),
  },
});

Set Up Your App ​

Wrap your app with the WagmiProvider and set up auto-connect:

tsx
// src/App.tsx
import { WagmiProvider } from "wagmi";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { config } from "./wagmi";
import { useAutoConnect } from "./hooks/useAutoConnect";

const queryClient = new QueryClient();

function AppContent() {
  useAutoConnect(); // Auto-connect to MiniPay on load

  return (
    <div>
      <h1>My Mini App</h1>
      {/* Your app content */}
    </div>
  );
}

function App() {
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        <AppContent />
      </QueryClientProvider>
    </WagmiProvider>
  );
}

export default App;

Create Auto-Connect Hook ​

Create src/hooks/useAutoConnect.ts:

tsx
import { useEffect } from "react";
import { useConnect, useConnectors } from "wagmi";

export function useAutoConnect() {
  const connectors = useConnectors();
  const { connect } = useConnect();

  useEffect(() => {
    // Auto-connect on page load - required for MiniPay
    if (connectors.length > 0) {
      connect({ connector: connectors[0] });
    }
  }, [connectors, connect]);
}

Optional: Check for MiniPay and provider ​

Your app should run inside MiniPay where window.ethereum is injected. You can throw a clear error if the provider is missing:

ts
// src/env.ts or similar
export function getEthereumProvider() {
  if (typeof window === "undefined" || !window.ethereum) {
    throw new Error(
      "window.ethereum is required. Please run this app inside MiniPay."
    );
  }
  return window.ethereum;
}

// Optional: detect MiniPay
export function isMiniPay(): boolean {
  return typeof window !== "undefined" && window.ethereum?.isMiniPay === true;
}

If you use a custom transport in Wagmi (e.g. custom(getEthereumProvider())), this check runs when the config is used. See Project setup for a full config example.

Verify connection ​

Test that your app connects to MiniPay using Wagmi v3's useConnection():

tsx
import { useConnection } from "wagmi";

function WalletStatus() {
  const { address, isConnected, isConnecting } = useConnection();

  if (isConnecting) {
    return <div>Connecting to MiniPay...</div>;
  }

  if (!isConnected || !address) {
    return <div>Not connected. Run this app inside MiniPay.</div>;
  }

  return <div>Connected: {address}</div>;
}

Next steps ​