Mini Apps

Appearance

Setting up a React App with MiniPay ​

This guide is the manual alternative to the Celopedia Quick Start — it walks through setting up a React project with MiniPay wallet integration by hand using Vite, TypeScript, and Wagmi. If you'd rather have your AI assistant scaffold this for you, start with the Quick Start instead.

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, chainId } = useConnection();

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

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

  return (
    <div>
      <p>Address: {address}</p>
      <p>Chain ID: {chainId}</p>
    </div>
  );
}

Next steps ​