> ## Documentation Index
> Fetch the complete documentation index at: https://docs.celo.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Scaffold a Celo app with Celo Composer and run it locally

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

```bash theme={null}
npx @celo/celo-composer@latest create
```

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:

```bash theme={null}
npx @celo/celo-composer@latest create my-celo-app \
  --template basic \
  --wallet-provider rainbowkit \
  --contracts hardhat \
  --description "My Celo app"
```

To take every default without answering anything:

```bash theme={null}
npx @celo/celo-composer@latest create my-celo-app --yes
```

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.

```bash theme={null}
npx @celo/celo-composer@latest create --template basic
```

### Farcaster miniapp

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

```bash theme={null}
npx @celo/celo-composer@latest create --template farcaster-miniapp
```

### MiniPay app

Mobile-first, for apps that run inside the MiniPay wallet. See [MiniPay](/build/mini-apps/overview) for what MiniPay expects from a Mini App.

```bash theme={null}
npx @celo/celo-composer@latest create --template minipay
```

### AI chat app

A standalone Next.js AI chat application.

```bash theme={null}
npx @celo/celo-composer@latest create --template ai-chat
```

### x402 paid API

Keeps the basic web app and adds an `apps/api` workspace with an [x402](/build/agents/x402)-paid endpoint and a buyer script that pays it in USDC.

```bash theme={null}
npx @celo/celo-composer@latest create --template x402
```

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

```bash theme={null}
npx @celo/celo-composer@latest create --wallet-provider rainbowkit
```

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

```bash theme={null}
npx @celo/celo-composer@latest create --contracts hardhat
```

## Command options

```bash theme={null}
npx @celo/celo-composer@latest create [project-name] [options]
```

| Flag | Description | Default |
| - | - | - |
| `-d, --description <description>` | Project description | Interactive prompt |
| `-t, --template <type>` | Template type (`basic`, `farcaster-miniapp`, `minipay`, `ai-chat`, `x402`) | `basic` |
| `--wallet-provider <provider>` | Wallet provider (`rainbowkit`, `thirdweb`, `none`) | `rainbowkit` |
| `-c, --contracts <framework>` | Smart contract framework (`hardhat`, `foundry`, `none`) | `hardhat` |
| `--skip-install` | Skip automatic dependency installation | `false` |
| `-y, --yes` | Skip all prompts and use defaults | `false` |

## Project structure

```
my-celo-app/
├── apps/
│   ├── web/                 # Next.js app: src/app, src/components, Tailwind config
│   └── contracts/           # Hardhat or Foundry workspace, if you selected one
├── package.json             # Root scripts: dev, build, lint, contracts:*
├── pnpm-workspace.yaml      # pnpm workspace config
├── turbo.json               # Turborepo configuration
└── tsconfig.json            # TypeScript configuration
```

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:

```bash theme={null}
cp my-celo-app/apps/web/.env.template my-celo-app/apps/web/.env
```

With the default RainbowKit provider, set `NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID` to a project ID from [Reown](/build/tools/libraries-sdks/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

```bash theme={null}
cd my-celo-app
pnpm install   # only if you passed --skip-install
pnpm dev
```

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

```text theme={null}
web:dev:   - Local:        http://localhost:3000
```

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

```text theme={null}
web:dev:  ⚠ Port 3000 is in use, trying 3001 instead.
web:dev:   - Local:        http://localhost:3001
```

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:

```bash theme={null}
cd my-celo-app
pnpm install
```

### 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](https://github.com/celo-org/celo-composer/issues) with the dev server output and the version of `@celo/celo-composer` you scaffolded with.

## Resources

| Resource | Link |
| - | - |
| Celo Composer repository | [github.com/celo-org/celo-composer](https://github.com/celo-org/celo-composer) |
| Celo Composer issues | [github.com/celo-org/celo-composer/issues](https://github.com/celo-org/celo-composer/issues) |
| Celo Discord, `#build-with-celo` | [discord.com/invite/celo](https://discord.com/invite/celo) |

## Related

* [Network overview](/learn/network/overview) — chain IDs, RPC URLs and the faucet you need for Celo mainnet and Celo Sepolia
* [MiniPay](/build/mini-apps/overview) — what to change when the target is the MiniPay wallet
* [Hardhat](/build/tools/dev-environments/hardhat) — configure the generated contracts workspace for Celo
* [Farcaster](/build/build-with-farcaster) — build and publish a miniapp from the Farcaster template


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.