Skip to main content
For app developers starting a new project on Celo. Celo Composer is a CLI that generates a starter monorepo: a Next.js frontend with a wallet connector already configured for Celo mainnet and Celo Sepolia, plus an optional smart contract workspace.

​
Prerequisites

  • Node.js 18 or later
  • pnpm 8 or later — the generated project is a pnpm workspace driven by Turborepo

​
Create a project

Nothing to install. Run the CLI with npx:
The CLI prompts for a project name and description, a template, a wallet provider, a smart contract framework, and whether to install dependencies. Pass flags to skip the prompts:
To take every default without answering anything:
The new project is initialized as a Git repository with an initial commit.

​
Choose a template

​
Basic web app (default)

A Next.js web application with the App Router, Tailwind CSS and shadcn/ui components.

​
Farcaster miniapp

Adds the Farcaster Mini App SDK (@farcaster/miniapp-sdk).

​
MiniPay app

Mobile-first, for apps that run inside the MiniPay wallet. See MiniPay for what MiniPay expects from a Mini App.

​
AI chat app

A standalone Next.js AI chat application.

​
x402 paid API

Keeps the basic web app and adds an apps/api workspace with an x402-paid endpoint and a buyer script that pays it in USDC.

​
Choose a wallet provider

The wallet provider handles wallet connection and transaction signing in the frontend. This choice applies to the basic template — MiniPay always uses RainbowKit, the Farcaster template ships its own wallet setup, and the AI chat and x402 templates have no wallet UI.
  • RainbowKit (default): wallet connector for React, wired up with wagmi and viem
  • thirdweb: wallet connector from thirdweb
  • None: no wallet integration, bring your own

​
Choose a smart contract framework

  • Hardhat (default): generates apps/contracts with Hardhat, Ignition deployment modules and a test setup
  • Foundry: generates apps/contracts with a Foundry project
  • None: frontend only

​
Command options

​
Project structure

If you selected Hardhat or Foundry, the root package.json also exposes the contract tasks through Turborepo: pnpm contracts:compile, pnpm contracts:test and pnpm contracts:deploy:celo-sepolia.

​
Configure wallet connection

apps/web/.env.template lists the variables the frontend reads. Copy it and fill it in before connecting a wallet:
With the default RainbowKit provider, set NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID to a project ID from Reown (formerly WalletConnect). Without it the config falls back to the placeholder string YOUR_PROJECT_ID, and any connection that goes through WalletConnect — mobile wallets and the QR flow — fails. A browser-extension wallet connects over its own injected provider and is unaffected. If you chose the thirdweb provider, set NEXT_PUBLIC_THIRDWEB_CLIENT_ID instead.

​
Run the app

Turborepo runs the dev task in each workspace. The web app reports the address it is serving:

​
Verify the app runs

  1. Open the URL the dev server printed — http://localhost:3000 unless that port was already taken.
  2. The landing page loads with your project name and a Connect Wallet button in the header.
  3. Click Connect Wallet, pick a wallet and approve the connection. The button is replaced by the connected network and your shortened address, which is the signal that wagmi, the connector and the Celo chain config are all working.
From here, write your contracts in apps/contracts and your UI in apps/web/src.

​
Troubleshooting

​
Port 3000 is already in use

Next.js does not fail; it takes the next free port and says so:
Always open the URL from the terminal rather than assuming 3000.

​
Failed to install dependencies during create

The CLI continues and leaves the project in place. Install manually:

​
The browser shows an error instead of the landing page

Read the dev server output rather than the browser. Next.js names the failing module or component there — Module not found: Can't resolve '<package>' points at a dependency, a ReferenceError at a component — while the browser only shows a 500. If the error names a file you have not edited, it comes from the template rather than your code. Report it on the Celo Composer issue tracker with the dev server output and the version of @celo/celo-composer you scaffolded with.

​
Resources

  • Network overview — chain IDs, RPC URLs and the faucet you need for Celo mainnet and Celo Sepolia
  • MiniPay — what to change when the target is the MiniPay wallet
  • Hardhat — configure the generated contracts workspace for Celo
  • Farcaster — build and publish a miniapp from the Farcaster template