celo-composer

Scaffold Celo dApps with Celo Composer. Use when starting new Celo projects, creating MiniPay apps, or setting up development environments.

This skill covers using Celo Composer to scaffold Celo dApps with pre-configured templates.

When to Use

• Starting a new Celo project
• Creating a MiniPay Mini App
• Setting up a Farcaster Miniapp
• Need pre-configured Next.js + Web3 setup

Quick Start

Interactive Mode

npx @celo/celo-composer@latest create

Follow the prompts to select your options.

With Project Name

npx @celo/celo-composer@latest create my-celo-app

Non-Interactive (Flags)

npx @celo/celo-composer@latest create my-celo-app \
  --template basic \
  --wallet-provider rainbowkit \
  --contracts hardhat

Quick Start with Defaults

npx @celo/celo-composer@latest create my-celo-app --yes

Templates

Template	Description	Use Case
basic	Standard Next.js 14+ dApp	General web3 applications
minipay	Mobile-first MiniPay app	MiniPay Mini Apps
farcaster-miniapp	Farcaster SDK + Frame	Farcaster integrations
ai-chat	Standalone chat application	AI-powered dApps

Create MiniPay App

npx @celo/celo-composer@latest create -t minipay

Create Farcaster Miniapp

npx @celo/celo-composer@latest create -t farcaster-miniapp

Configuration Options

Wallet Providers

Provider	Description
rainbowkit	Popular wallet connection UI (default)
thirdweb	thirdweb Connect SDK
none	No wallet provider

Smart Contracts

Option	Description
hardhat	Hardhat development environment (default)
foundry	Foundry development environment
none	No smart contracts

Project Structure

my-celo-app/
├── apps/
│   ├── web/              # Next.js application
│   │   ├── app/          # App router pages
│   │   ├── components/   # React components
│   │   └── ...
│   └── contracts/        # Smart contracts (if selected)
│       ├── contracts/    # Solidity files
│       ├── scripts/      # Deployment scripts
│       └── test/         # Contract tests
├── packages/
│   ├── ui/               # Shared UI components
│   └── utils/            # Shared utilities
├── pnpm-workspace.yaml   # Workspace configuration
├── turbo.json            # Turborepo configuration
└── package.json

Running the Project

cd my-celo-app

# Install dependencies
pnpm install

# Start development server
pnpm dev

# Build for production
pnpm build

Tech Stack

• Framework: Next.js 14+ with App Router
• Styling: Tailwind CSS
• Components: shadcn/ui
• Monorepo: Turborepo + PNPM workspaces
• Language: TypeScript
• Web3: viem + wagmi (or thirdweb)

Requirements

• Node.js 18.0.0 or higher
• PNPM (recommended) or npm/yarn

Working with Contracts

If you selected Hardhat or Foundry:

Hardhat

# Navigate to contracts
cd apps/contracts

# Compile
npx hardhat compile

# Test
npx hardhat test

# Deploy to Celo Sepolia
npx hardhat run scripts/deploy.ts --network celoSepolia

Foundry

# Navigate to contracts
cd apps/contracts

# Build
forge build

# Test
forge test

# Deploy to Celo Sepolia
forge script script/Deploy.s.sol --rpc-url https://forno.celo-sepolia.celo-testnet.org --broadcast

Environment Variables

Create .env.local in apps/web/:

# Required for wallet connection
NEXT_PUBLIC_WC_PROJECT_ID=your_walletconnect_project_id

# Optional: Alchemy API key
NEXT_PUBLIC_ALCHEMY_API_KEY=your_alchemy_key

Create .env in apps/contracts/:

PRIVATE_KEY=your_private_key
CELOSCAN_API_KEY=your_celoscan_api_key

Customization

Adding New Pages

Create files in apps/web/app/:

// apps/web/app/my-page/page.tsx
export default function MyPage() {
  return <div>My Custom Page</div>;
}

Adding Components

Add to apps/web/components/ or shared packages/ui/:

// apps/web/components/MyComponent.tsx
export function MyComponent() {
  return <div>My Component</div>;
}

Additional Resources

• templates.md - Detailed template documentation