create-bun-eth

Scaffold a Bun-first Ethereum project - Full-Stack dApp or Backend-Only API.

Usage

Interactive Mode (Recommended)

bunx create-bun-eth@latest my-project

You'll be prompted to choose:

1. Full-Stack dApp - Next.js frontend + Backend + Contracts
2. Backend-Only - API + Contracts only

Non-Interactive Mode

# Full-stack dApp
bunx create-bun-eth@latest my-dapp --full-stack

# Backend-only API
bunx create-bun-eth@latest my-api --backend-only

Project Types

Full-Stack dApp

Perfect for building complete decentralized applications with a modern web interface.

Includes:

• 🎨 Next.js 14 - App Router with React 18
• 🌈 RainbowKit - Beautiful wallet connection UI
• 🔗 wagmi v2 - React hooks for Ethereum
• 🎣 Custom Hooks - @bun-eth/hooks for contract interactions
• 🧱 Web3 Components - @bun-eth/components (Address, Balance, Faucet, etc.)
• 🔥 Contract Hot Reload - Frontend auto-updates when contracts change
• 💰 Burner Wallet - Ephemeral wallet for local testing
• 🚰 Local Faucet - Get test ETH instantly
• 🚀 Elysia Backend - Fast TypeScript API
• 📜 Foundry Contracts - Forge, Anvil, Cast
• 🐳 Docker Compose - Full dev stack (Web + API + Anvil)

Services:

• Web UI: http://localhost:3000
• API: http://localhost:3001
• Anvil: http://localhost:3002

Backend-Only

Perfect for APIs, bots, scripts, or when you want to build your own custom frontend.

Includes:

• 🚀 Elysia Backend - Fast TypeScript API
• 📜 Foundry Contracts - Forge, Anvil, Cast
• 📦 TypeScript SDK - Type-safe contract interactions
• 🐳 Docker Compose - API + Anvil
• ⚡ Taskfile - Command orchestration
• 🧪 Bun-Native Tests - Testing for SDK/API

Services:

• API: http://localhost:3001
• Anvil: http://localhost:3002

Prerequisites

• Bun >= 1.1.0
• Foundry
• Docker
• Task (optional but recommended)

Quick Start

1. Create project:

   bunx create-bun-eth@latest my-project

2. Navigate to project:

   cd my-project

3. Complete setup (installs deps, compiles contracts, runs tests):

   task setup

4. Start development stack:

   task dev:up

5. Deploy contracts:

   task contracts:deploy

6. Open browser (Full-Stack only):

   open http://localhost:3000

Available Commands

# Setup & Development
task setup              # Complete setup with tests
task dev:up             # Start development stack
task dev:down           # Stop services
task dev:logs           # View all logs
task dev:auto-ports     # Find and configure free ports

# Contracts
task contracts:compile  # Compile smart contracts
task contracts:deploy   # Deploy to local Anvil
task contracts:test     # Run Foundry tests
task contracts:generate # Generate TypeScript types

# Testing
task test               # Run all tests
task test:contracts     # Foundry tests only
task test:api           # API tests only
task test:sdk           # SDK tests only

# Utilities
task check:health       # Check API health
task status             # View service status
task --list             # See all commands

Project Structure

Full-Stack

my-dapp/
├── apps/
│   ├── web/                    # Next.js frontend
│   └── api/                    # Elysia backend
├── packages/
│   ├── contracts/              # Foundry smart contracts
│   ├── hooks/                  # Custom React hooks (@bun-eth/hooks)
│   ├── components/             # Web3 UI components (@bun-eth/components)
│   ├── burner-connector/       # Burner wallet connector
│   ├── foundry-deployer/       # Hot reload system
│   ├── core/                   # Shared utilities & types
│   └── sdk/                    # TypeScript SDK
├── docker/                     # Docker Compose setup
└── tooling/task/               # Taskfile orchestration

Backend-Only

my-api/
├── apps/api/           # Elysia backend
├── packages/
│   ├── contracts/      # Foundry smart contracts
│   ├── core/          # Shared utilities & types
│   └── sdk/           # TypeScript SDK
├── docker/            # Docker Compose setup
└── tooling/task/      # Taskfile orchestration

Features

Full-Stack Exclusive

• Contract Hot Reload: Edit your contracts and watch your frontend auto-update
• Custom React Hooks: Type-safe hooks with full TypeScript inference
  • useScaffoldReadContract - Read contract state with auto-refresh
  • useScaffoldWriteContract - Write to contracts with notifications
  • useDeployedContractInfo - Get contract addresses and ABIs
  • useScaffoldEventHistory - Subscribe to contract events
  • useScaffoldEventSubscriber - Real-time event streaming
• Web3 Components: Pre-built UI components
  • <Address /> - Display addresses with ENS, Blockie, copy, explorer link
  • <Balance /> - Show ETH/token balances
  • <Faucet /> - Local faucet for test ETH
  • <BurnerWalletInfo /> - Burner wallet management UI
• Burner Wallet: Ephemeral wallets for quick testing (localhost only)
• RainbowKit Integration: Beautiful wallet connection UX

Both Project Types

• Bun-Native: 100% Bun, no Node.js required
• Foundry: Blazing fast Solidity development
• TypeScript: Full type safety across the stack
• Docker Compose: Complete local dev environment
• Monorepo: Clean package architecture
• Native Tests: Bun tests for TS, Forge tests for Solidity

Port Configuration

By default, services use these ports:

• Web: 3000 (Full-Stack only)
• API: 3001
• Anvil: 8545

If ports are in use, run:

task dev:auto-ports

This will automatically find free ports and update your .env file.

Environment Variables

Copy .env.example to .env (done automatically by task setup):

# Ports (consecutive for easy management)
WEB_PORT=3000
API_PORT=3001
ANVIL_PORT=3002

# API
PORT=3001
NODE_ENV=development

# Ethereum
ANVIL_NODE=http://localhost:3002
CHAIN_ID=31337
PRIVATE_KEY=0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80

# Frontend (Full-Stack only)
NEXT_PUBLIC_WC_PROJECT_ID=  # Get from https://cloud.walletconnect.com
NEXT_PUBLIC_ANVIL_PORT=3002

Documentation

For full documentation, visit the main repository.

License

MIT