Algorand Starter: Full Stack

Smart contracts and a React frontend, wired together with npm workspaces.

Prerequisites

• Node.js >= 24
• Docker and VibeKit -- to run LocalNet

Getting Started

cp contracts/.env.localnet.example contracts/.env.localnet
cp app/.env.local.example app/.env.local

npm install
vibekit localnet start

npm run build
npm run deploy
# => Deployed HelloWorld: APP_ID=1234

Set VITE_APP_ID to that number in app/.env.local -- the key is already there, so edit it in place -- then:

npm run dev

Without VITE_APP_ID the UI shows a "Contract Not Configured" card instead of failing.

Layout

• contracts/ -- @repo/contracts: contract source, tests, deploy script, and artifacts/ (compiled TEAL + generated client, committed so the app type-checks before a build)
• app/ -- @repo/app: React frontend. App.tsx sets up wallets, components/AppCalls.tsx calls the contract, utils/algorand.ts reads env.

How It Works

The frontend imports the generated client through the workspace -- no copying, no codegen step in the app:

import { HelloWorldClient } from '@repo/contracts'

const appClient = new HelloWorldClient({ algorand: getAlgorandClient(), appId })
const response = await appClient.send.hello({
  args: { name: input },
  sender: activeAddress,
  signer: transactionSigner,
})

The client has no default signer, so pass sender and signer from use-wallet on every call. Wallet UI comes from @txnlab/use-wallet-ui-react: KMD on LocalNet, Pera and Lute everywhere else.

Deploying

npm run deploy              # LocalNet
npm run deploy:testnet      # TestNet
npm run deploy:mainnet      # MainNet

LocalNet uses the built-in dispenser. For TestNet and MainNet, copy the matching template and set DEPLOYER_MNEMONIC in it:

cp contracts/.env.testnet.example contracts/.env.testnet

Don't skip that edit -- an empty DEPLOYER_MNEMONIC falls back to the LocalNet dispenser and fails with a confusing connection error.

To point the frontend at TestNet, copy app/.env.testnet.example over app/.env.local and set VITE_APP_ID. Only .env*.example files are committed.

Testing

npm test   # builds contracts, runs unit + e2e (needs LocalNet)