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

bash

npx @celo/celo-composer@latest create

Follow the prompts to select your options.

With Project Name

bash

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

Non-Interactive (Flags)

bash

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

Quick Start with Defaults

bash

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

bash

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

Create Farcaster Miniapp

bash

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

text

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

bash

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

bash

# 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

bash

# 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/:

bash

# 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/:

bash

PRIVATE_KEY=your_private_key
CELOSCAN_API_KEY=your_celoscan_api_key

Customization

Adding New Pages

Create files in apps/web/app/:

tsx

// 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/:

tsx

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

Additional Resources

• templates.md - Detailed template documentation