Vite dapp template

The whitechain-dapp-vite starter is a client-only single-page app for Whitechain Sepolia with wallet connect and contract calls already wired. You clone it, add a Reown project id, and run. It runs on React 19, Vite, TanStack Router, and Tailwind v4, with Reown AppKit over wagmi v3 and viem. It suits developers who want a static dapp without building the wallet layer by hand. For a server-rendered app that can hide secrets behind a backend, use the Next dapp template instead.

This is a static SPA with no server, so it cannot hold secrets. Everything in the bundle ships to the browser. A Reown projectId is public by design, which is fine. Never put a privileged key in a VITE_* variable.

What you get

Wallet connect through Reown AppKit, with the connected account, network, and WBT balance.
A public read of the Storage contract that shows the current value with no wallet connected.
A write that stores a new value and refreshes the read when the transaction confirms.
A standalone codebase: every dependency is a public npm package, and the web3 layer lives in src/lib.

Before you start

Node.js 20.19 or later and pnpm through Corepack.
A Reown project id from dashboard.reown.com.
Optional: your own Storage contract. The template defaults to a public verified one, so you can skip this. To use your own, deploy with Hardhat or Foundry and copy its address.
Test WBT for the write transaction, from the faucet.

1. Get the template

Clone the templates repository and enter the dapp folder.

Terminal

git clone https://github.com/whitechain-labs/templates.git
cd templates/whitechain-dapp-vite

2. Install dependencies

Enable the pinned pnpm through Corepack, then install. Every dependency comes from public npm, so no registry token is needed.

Terminal

corepack enable
pnpm install

3. Configure the environment

Copy the example file and set the public values. Vite exposes VITE_* variables to the browser bundle at build time.

Terminal

cp .env.example .env

Variable	Value
`VITE_REOWN_PROJECT_ID`	Your Reown project id.
`VITE_STORAGE_ADDRESS`	Optional. Defaults to a public verified Storage contract; set to use your own.

VITE_STORAGE_ADDRESS is optional. The template defaults to a public, verified Storage contract on Whitechain Sepolia: 0xC880eF22c01184a3Db08F2c306684311C48cB495. Set the variable only to point at your own deployment.

4. Run the app

Terminal

pnpm dev

Open http://localhost:5173. The Storage card reads the current value over the public RPC right away. Select Connect wallet, approve the connection, and the account, network, and balance appear.

5173 is the Vite default. If it is already in use, Vite starts on the next free port and prints the URL.

5. Read and write the contract

retrieve() is a view call, so the stored value shows without a wallet. store(uint256) sends a transaction. With a wallet connected on Whitechain Sepolia, enter a number and confirm it in the wallet. The value updates once the transaction confirms. Open the transaction on the explorer to check it.

If the wallet is on another network, the panel shows a switch action. store() stays disabled until the wallet is on Whitechain Sepolia (chain 1874).

How it looks

Whitechain Vite dapp with a wallet card and a Storage contract card — The Vite dapp: wallet and Storage contract cards

The home page shows a title and two cards. The wallet card connects a wallet through Reown AppKit, then shows the account address and WBT balance. The Storage card reads the current value with no wallet, and shows a number input and Store button once a wallet is connected on the right network.

Project layout

Path	What it holds
`src/lib/wagmi.ts`	Chain, RPC, and the Reown AppKit and wagmi config.
`src/lib/wallet.ts`	The `useWallet` hook: account, network, disconnect, switch.
`src/lib/storage.ts`	The Storage ABI and address.
`src/lib/cn.ts`	The `cn` class-merge helper (clsx and tailwind-merge).
`src/components/ui/`	Plain Tailwind primitives: Button, Card, Spinner.
`src/components/web3/`	The wallet and Storage panels.
`src/routes/`	File-based routes; the route tree generates into `src/routeTree.gen.ts`.
`src/main.tsx`	App entry: wagmi and TanStack Query providers and the router.

Components

The web3 layer lives in src/lib and the panels in src/components/web3. Each essential part is below, trimmed to the lines that matter.

Chain and wallet config

src/lib/wagmi.ts defines the chain with viem’s OP Stack chainConfig, then wires Reown AppKit over wagmi. Change the RPC URL to use your own node; set enableCoinbase: true to add the Coinbase connector.

src/lib/wagmi.ts

export const whitechainTestnet: Chain = defineChain({
  ...chainConfig,
  id: 1874,
  name: 'Whitechain Sepolia',
  testnet: true,
  nativeCurrency: { decimals: 18, name: 'WhiteBIT Coin', symbol: 'WBT' },
  rpcUrls: { default: { http: ['https://rpc.testnet.whitechain.io'] } },
  blockExplorers: {
    default: { name: 'Whitechain Explorer', url: 'https://explorer.testnet.whitechain.io' },
  },
});

const adapter = new WagmiAdapter({ projectId, networks, ssr: false });
createAppKit({ adapters: [adapter], projectId, networks, enableCoinbase: false });
export const wagmiConfig = adapter.wagmiConfig;

Wallet state hook

src/lib/wallet.ts gives the panels one shape for account and network state. The connection itself is opened through the AppKit modal, not here.

src/lib/wallet.ts

export function useWallet(): WalletState {
  const { address, chainId, isConnected, isConnecting, connector } = useConnection();
  const { mutate: disconnect } = useDisconnect();
  const { mutate: switchChain } = useSwitchChain();
  return {
    address, chainId, isConnected, isConnecting, connector, disconnect,
    switchChain: (id: number) => switchChain({ chainId: id }),
  };
}

Wallet panel

src/components/web3/wallet-panel.tsx opens the modal to connect, then reads the balance with wagmi.

src/components/web3/wallet-panel.tsx

const { open } = useAppKit();
const { address, isConnected, isConnecting, disconnect } = useWallet();
const { data: balance } = useBalance({
  address,
  chainId: targetChainId,
  query: { enabled: Boolean(address) },
});

if (!isConnected) {
  return <Button loading={isConnecting} onClick={() => void open()}>Connect wallet</Button>;
}
// Connected: show the address, the formatted balance, and a Disconnect button.

Storage read

retrieve() is a public view call, so it runs over the RPC with no wallet connected.

src/components/web3/storage-panel.tsx

const { data: storedValue, refetch } = useReadContract({
  abi: storageAbi,
  address: storageAddress,
  functionName: 'retrieve',
  chainId: targetChainId,
  query: { enabled: Boolean(storageAddress) },
});

Storage write

store(uint256) is a write, gated on a connected wallet. The read refreshes once the transaction confirms.

src/components/web3/storage-panel.tsx

const { mutate: storeValue, data: txHash } = useWriteContract();
const receipt = useWaitForTransactionReceipt({ hash: txHash, chainId: targetChainId });

useEffect(() => {
  if (receipt.isSuccess) void refetch();
}, [receipt.isSuccess, refetch]);

// On submit:
storeValue({
  abi: storageAbi,
  address: storageAddress,
  functionName: 'store',
  args: [BigInt(inputValue)],
  chainId: targetChainId,
});

Troubleshooting

`typecheck` reports `Cannot find module './routeTree.gen'`

Run pnpm dev or pnpm build once. The TanStack Router plugin generates src/routeTree.gen.ts.

The wallet connects but the Storage panel stays disabled

Set VITE_STORAGE_ADDRESS and switch the wallet to Whitechain Sepolia (chain 1874).

`pnpm install` reports an engine error

Use Node 20.19 or later.

Wallet

Dapps

Deploy

Bridge

Block Explorer

Ecosystem

What you get

Before you start

1. Get the template

2. Install dependencies

3. Configure the environment

4. Run the app

5. Read and write the contract

How it looks

Project layout

Components

Chain and wallet config

Wallet state hook

Wallet panel

Storage read

Storage write

Troubleshooting

​What you get

​Before you start

​1. Get the template

​2. Install dependencies

​3. Configure the environment

​4. Run the app

​5. Read and write the contract

​How it looks

​Project layout

​Components

​Chain and wallet config

​Wallet state hook

​Wallet panel

​Storage read

​Storage write

​Troubleshooting

​Related

What you get

Before you start

1. Get the template

2. Install dependencies

3. Configure the environment

4. Run the app

5. Read and write the contract

How it looks

Project layout

Components

Chain and wallet config

Wallet state hook

Wallet panel

Storage read

Storage write

Troubleshooting

Related