OMies dApp Template

Production-ready Web3 monorepo for MANTRA Chain

Quick Start · Features · Commands · Stack · Docs

---

⚡ Quick Start

# Clone and enter the project
git clone https://github.com/mantramatt/omies-dapp-spa-template.git
cd omies-dapp-spa-template

# Install dependencies
yarn install

# Start the development server
yarn dev

That's it! Open http://localhost:5173 to see your dApp.

Tip

New to the project? Run the setup wizard to personalize the template:

./setup.sh

---

✨ Features

Category	What You Get
🔗 Smart Contracts	Solidity + Foundry with deployment scripts, auto-verification
⚛️ Frontend	React 19, TypeScript, Vite, TanStack Router (file-based)
🎨 Design System	ShadCN UI + OMies visual identity (teal cartoon aesthetic)
👛 Web3	Wagmi + Viem + AppKit (MetaMask, WalletConnect, Keplr)
📦 Monorepo	Yarn workspaces with shared configs and independent packages
🚀 Deployment	Cloudflare Workers edge deployment, automatic contract verification
🛠 DX	Storybook, DevTools page, Kitchen Sink, hot reload

Pre-built Components

15+ Web3 components ready to use:

• WalletConnectPill — Custom wallet button with balance + address
• TransactionDialog — Review → Sign → Pending → Success flow
• TokenInput — Amount input with max button + balance
• AddressDisplay — Shortened address with copy + explorer link
• NetworkBanner — Testnet/unsupported network warnings
• ConnectGuard — Protect routes for connected users only

See all components →

---

🏗 Project Structure

omies-dapp-spa-template/
├── packages/
│   ├── contracts/          # 🔗 Foundry smart contracts
│   │   ├── src/            # Solidity source files
│   │   ├── script/         # Deployment scripts
│   │   └── test/           # Contract tests
│   │
│   └── webapp/             # ⚛️ React SPA (your main workspace)
│       ├── src/
│       │   ├── components/ # UI + Web3 components
│       │   ├── config/     # Chain configs (file-per-network)
│       │   ├── hooks/      # Custom React hooks
│       │   └── routes/     # TanStack file-based routes
│       └── public/         # Static assets
│
├── docs/
│   ├── dev/                # 📖 Developer documentation
│   └── agents/             # 🤖 AI assistant instructions
│
└── openspec/               # 📋 Project specifications

---

📋 Commands

All commands run from the repository root.

Development

Command	Description
yarn dev	Start webapp dev server (localhost:5173)
yarn build	Build webapp for production
yarn storybook	Component development (localhost:6006)

Smart Contracts

Command	Description
yarn contracts:test	Run Foundry tests
yarn contracts:test:watch	Tests in watch mode
yarn contracts:deploy:local	Deploy to local Anvil
yarn contracts:deploy:dukong	Deploy to Dukong testnet
yarn contracts:deploy:mainnet	Deploy to mainnet

Dependencies

# Add package to webapp
yarn workspace @dapp-evm/webapp add [package]

# Add dev dependency
yarn workspace @dapp-evm/webapp add -D [package]

---

🔧 Configuration

Environment Variables

Create packages/webapp/.env:

# Required for wallet connections
VITE_WALLETCONNECT_PROJECT_ID=your_project_id_here

Get your Project ID at WalletConnect Cloud.

For contracts, copy and configure:

cp packages/contracts/.env.example packages/contracts/.env

Supported Networks

Network	Chain ID	RPC Endpoint	Explorer
Mainnet	5888	https://evm.mantrachain.io	blockscout.mantrascan.io
Dukong Testnet	5887	https://evm.dukong.mantrachain.io	explorer.dukong.io
Local (Anvil)	1337	http://localhost:8545	—

Adding a New Network

1. Create config file: packages/webapp/src/config/networks/[network].ts
2. Export chain definition and config object
3. Register in packages/webapp/src/config/chains.ts

Step-by-step guide →

---

🛠 Tech Stack

Layer	Technology	Purpose
Framework	React 19	UI library with latest features
Build	Vite	Lightning-fast dev server & bundler
Routing	TanStack Router	Type-safe file-based routing
Styling	Tailwind CSS v4	Utility-first CSS
Components	ShadCN/UI	Accessible primitives
Web3	Wagmi + Viem	Ethereum interactions
Wallets	AppKit	Multi-wallet connections
State	TanStack Query + Jotai	Server & client state
Contracts	Foundry	Solidity development toolkit
Deployment	Cloudflare Workers	Edge hosting

---

📖 Documentation

For Developers

Document	Description
Getting Started	Quick start, key concepts, project structure
Architecture Guide	Config system, state management, patterns
Workflows	Step-by-step guides for common tasks
Webapp README	Component reference, hooks, usage examples
Contracts README	Contract addresses, deployment, testing

For AI Assistants

Document	Description
Master Instructions	Complete system prompt for LLM agents
Design Tokens	Colors, fonts, animations reference
Component API	Component specifications & state machines

---

🌐 Networks & Resources

Contract Addresses

MANTRA Mainnet (5888)

Contract	Address
Multicall3	0xcA11bde05977b3631167028862bE2a173976CA11
Wrapped OM	0xE3047710EF6cB36Bcf1E58145529778eA7Cb5598
Create2	0x4e59b44847b379578588920cA78FbF26c0B4956C
Createx	0xba5Ed099633D3B313e4D5F7bdc1305d3c28ba5Ed

MANTRA Dukong Testnet (5887)

Contract	Address
Multicall3	0xcA11bde05977b3631167028862bE2a173976CA11
Wrapped OM	0x10d26F0491fA11c5853ED7C1f9817b098317DC46
Create2	0x4e59b44847b379578588920cA78FbF26c0B4956C
Createx	0xba5Ed099633D3B313e4D5F7bdc1305d3c28ba5Ed

Supported Wallets

Type	Wallets
EVM	MetaMask, Rabby, WalletConnect-compatible
Cosmos	Keplr, Leap

Useful Links

Resource	Link
📚 MANTRA Docs	docs.mantrachain.io
🔍 Block Explorer	blockscout.mantrascan.io
💧 Testnet Faucet	faucet.dukong.mantrachain.io
🔨 Foundry Book	book.getfoundry.sh
⚙️ Wagmi Docs	wagmi.sh
🎨 ShadCN UI	ui.shadcn.com

---

🚀 Deployment

Smart Contracts

# Deploy to testnet (auto-verifies on Blockscout)
yarn contracts:deploy:dukong

# Deploy to mainnet
yarn contracts:deploy:mainnet

Frontend

The webapp deploys automatically via CI/CD to Cloudflare Workers:

Environment	URL
Testnet	dapp-template-nonprod.mantra-development.workers.dev
Mainnet	dapp-template-prod.mantra-chain-new-account.workers.dev

---

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit changes: git commit -m 'Add amazing feature'
4. Push to branch: git push origin feature/amazing-feature
5. Open a Pull Request

---

📄 License

This project is open source and available under the MIT License.

---

Built with ❤️ for the MANTRA ecosystem

MANTRA Chain · Documentation · Discord