Bun-Eth

A Bun-first scaffold for Ethereum projects

A pure Bun-native monorepo template for building Ethereum-based applications. Replace scaffold-eth-2's Node/React stack with a modern, TypeScript-first approach using Bun, Elysia, and Foundry.

✨ Features

🔥 Contract Hot Reload - Your frontend auto-adapts to your smart contracts as you deploy them
🎣 Custom Hooks - Type-safe React hooks for reading, writing, and watching contracts (@bun-eth/hooks)
🧱 Web3 Components - Pre-built UI components for addresses, balances, inputs, and more (@bun-eth/components)
💰 Burner Wallet - Ephemeral wallets for instant testing without MetaMask
🚰 Local Faucet - Built-in faucet for quick testing on Anvil
🌈 RainbowKit - Beautiful wallet connection UI with multi-wallet support
🚀 Bun-Native - 100% Bun, no Node.js required - lightning fast builds
⚡ Elysia Backend - Fast, TypeScript-first web framework for REST API
🎨 Next.js Frontend - Modern React framework with shadcn/ui components
🔨 Foundry Contracts - Blazing fast Rust-based smart contract framework (Forge + Anvil)
🐳 Docker Compose - Complete local development environment
📦 Clean Monorepo - Well-architected packages with clear separation of concerns
🧪 Comprehensive Testing - Multi-layer E2E testing (visual regression, accessibility, performance, responsive), Bun tests for TypeScript, Foundry tests for Solidity
🎨 Biome Linting - Fast, Bun-native linting and formatting (10-100x faster than ESLint)
🔧 Forge Formatting - Built-in Solidity formatting and linting
📋 Taskfile - Powerful command orchestration
💎 Full TypeScript - Type safety from contracts to UI

🚀 Quick Start

Using the CLI (Recommended)

bunx create-bun-eth@latest my-dapp
cd my-dapp
task setup

The CLI will:

Download the latest template (without git history)
Let you choose between Full-Stack or Backend-Only
Set up your project name
Initialize a fresh git repository

Using as GitHub Template

Click the "Use this template" button at the top of the repository to create your own copy.

Then:

git clone https://github.com/YOUR_USERNAME/your-project.git
cd your-project
task setup

Manual Clone

git clone https://github.com/Bun-Eth-Community/bun-eth.git my-dapp
cd my-dapp
task setup

The setup task will:

Create .env from .env.example
Install all dependencies
Compile smart contracts
Run all tests to verify everything works

📋 Prerequisites

Bun >= 1.1.0
Foundry (for smart contracts)
Docker (for local Ethereum node)
Task (optional, for orchestration)

Install Task

# macOS
brew install go-task

# Linux
sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b ~/.local/bin

# Or use bunx
bunx @go-task/cli

🏗️ Project Structure

bun-eth/
├── apps/
│   ├── api/                         # Elysia backend API
│   │   ├── src/
│   │   │   ├── index.ts            # API entry point
│   │   │   ├── config.ts           # Configuration
│   │   │   ├── provider.ts         # Ethereum provider setup
│   │   │   └── routes/             # API routes
│   │   └── Dockerfile
│   └── web/                         # Next.js frontend
│       ├── src/
│       │   ├── app/                # App router pages
│       │   ├── components/         # Local components
│       │   └── lib/                # Utilities & wagmi config
│       └── package.json
├── packages/
│   ├── contracts/                   # Smart contracts (Foundry)
│   │   ├── contracts/              # Solidity files
│   │   ├── script/                 # Deploy scripts
│   │   ├── test/                   # Foundry tests
│   │   ├── deployedContracts.ts    # 🔥 Auto-generated (hot reload!)
│   │   └── foundry.toml
│   ├── hooks/                       # 🎣 React hooks for Web3
│   │   └── src/
│   │       ├── useScaffoldContract.ts
│   │       ├── useScaffoldReadContract.ts
│   │       ├── useScaffoldWriteContract.ts
│   │       └── ...                 # 10+ hooks
│   ├── components/                  # 🧱 Web3 UI components
│   │   └── src/
│   │       ├── Address.tsx
│   │       ├── Balance.tsx
│   │       ├── Faucet.tsx
│   │       └── ...                 # 10+ components
│   ├── foundry-deployer/            # 🔥 Hot reload system
│   │   └── src/
│   │       ├── generator.ts        # Generates deployedContracts.ts
│   │       └── cli.ts              # CLI tool
│   ├── core/                        # Shared utilities
│   ├── sdk/                         # TypeScript SDK for API
│   └── create-bun-eth/              # Scaffolding CLI
├── tooling/
│   └── task/
│       └── Taskfile.yml            # Task definitions
└── docker/
    └── docker-compose.yml          # Anvil + API + Web

🛠️ Development

Start Development Stack

task dev:up

This starts:

Anvil local Ethereum node on http://localhost:3002
Bun-Eth API on http://localhost:3001

Start Web UI

task web:dev

This starts the Next.js frontend on http://localhost:3000

Stop Development Stack

task dev:down

View Logs

# All services
task dev:logs

# API only
task dev:logs:api

# Anvil node only
task dev:logs:anvil

📜 Smart Contracts

Compile Contracts

task contracts:compile

Deploy Contracts

# Deploy to local network
task contracts:deploy

# Deploy to Sepolia
task contracts:deploy:sepolia

Test Contracts

task contracts:test

🌐 API Endpoints

Base URL: http://localhost:3001

Health Check

GET /health

Response:

{
  "status": "ok",
  "timestamp": 1234567890,
  "version": "0.1.0",
  "network": {
    "chainId": 31337,
    "blockNumber": 42
  }
}

Get Wallet Info

GET /wallet/:address

Response:

{
  "address": "0x...",
  "balance": "10.5",
  "nonce": 5
}

Send Transaction

POST /wallet/send
Content-Type: application/json

{
  "to": "0x...",
  "value": "1.0",
  "data": "0x..."
}

Call Contract (Read)

POST /contract/call
Content-Type: application/json

{
  "contractAddress": "0x...",
  "method": "retrieve",
  "args": []
}

Send Contract Transaction (Write)

POST /contract/send
Content-Type: application/json

{
  "contractAddress": "0x...",
  "method": "store",
  "args": [42],
  "value": "0"
}

🌐 Frontend Development

The Next.js frontend includes:

shadcn/ui - Beautiful, accessible components built on Radix UI
wagmi - React Hooks for Ethereum
viem - TypeScript Ethereum library
Tailwind CSS - Utility-first CSS framework

Web Tasks

# Start development server
task web:dev

# Build for production
task web:build

# Start production server
task web:start

Wallet Integration

The frontend supports:

MetaMask and other injected wallets
WalletConnect for mobile wallets
Automatic network switching
Real-time blockchain data updates

🧪 Testing

Run All Tests

task test

Run Tests by Package

# Contract tests
task test:contracts

# API tests
task test:api

# SDK tests
task test:sdk

# Core tests
task test:core

End-to-End Tests

The template includes a comprehensive E2E testing suite covering multiple quality dimensions:

Complete Test Suite

# Run complete E2E test suite (all layers)
task test:e2e:complete

# View results
cd apps/web && bunx playwright show-report

Individual Test Layers

# Visual regression testing (screenshot comparison)
task test:e2e:visual

# Accessibility testing (WCAG 2.1 AA compliance)
task test:e2e:accessibility

# Performance testing (load times, bundle sizes)
task test:e2e:performance

# Responsive design testing (multiple viewports)
task test:e2e:responsive

# Generate UI screenshots for documentation
task test:e2e:screenshots

Standard E2E Tests

# Web app e2e tests (with webServer)
task test:e2e

# Run e2e tests in UI mode
task test:e2e:ui

# Template creation e2e tests (validates the entire CLI workflow)
task test:e2e:template

# Run all tests (unit + contracts + e2e + template e2e)
task test:all

E2E Testing Features

Visual Regression - Automatic screenshot comparison to detect UI changes
Accessibility - WCAG 2.1 AA compliance testing with axe-core
Performance - Load time metrics, bundle size analysis, LCP/FCP tracking
Responsive Design - Cross-device testing (mobile, tablet, desktop)
RPC Mocking - Test contract states without real transactions
Time Manipulation - Test time-dependent contracts with Anvil

Test Results:

Screenshots saved to docs/screenshots/
Test reports saved to docs/test-results/
Accessibility violations logged with actionable fixes
Performance metrics tracked over time

Documentation:

See docs/E2E_TESTING_GUIDE.md for detailed guide
Examples of all test types included
Integration with CI/CD pipelines

Watch Mode

task test:watch

Coverage

task test:coverage

🎨 Code Quality & Linting

The project uses Biome for TypeScript/JavaScript linting and Forge for Solidity formatting.

Why Biome?

Biome is a fast, Bun-native linter and formatter that replaces ESLint and Prettier:

⚡ 10-100x faster than ESLint
🦀 Rust-based - Native performance
🎯 Zero config - Works out of the box
🔧 Auto-fix - Automatically fixes issues
📦 Single tool - Replaces ESLint + Prettier

Linting Commands

# Lint all packages (TypeScript + Solidity)
task lint

# Lint and auto-fix TypeScript issues
task lint:fix

# Lint Solidity contracts
task contracts:lint

# Format Solidity contracts
task contracts:format

Manual Linting

# Lint specific package
cd packages/core
bun run lint

# Auto-fix issues
bunx biome check --write .

# Unsafe auto-fix (includes recommended changes)
bunx biome check --write --unsafe .

Solidity Formatting

# Check Solidity formatting
cd packages/contracts
forge fmt --check

# Format Solidity files
forge fmt

CI/CD Integration

All linting is enforced in GitHub Actions:

Biome checks all TypeScript/JavaScript files
Forge checks all Solidity files
Pull requests must pass linting to merge

Configuration

Biome: biome.json at project root
Forge: packages/contracts/foundry.toml (see [fmt] section)

📦 Using the SDK

Install in your project:

bun add @bun-eth/sdk

Usage:

import { createClient } from "@bun-eth/sdk";

const client = createClient({
  baseUrl: "http://localhost:3001",
  timeout: 30000,
});

// Check health
const health = await client.health();

// Get wallet info
const wallet = await client.getWallet("0x...");

// Send transaction
const tx = await client.sendTransaction({
  to: "0x...",
  value: "1.0",
});

// Call contract
const result = await client.contractCall({
  contractAddress: "0x...",
  method: "retrieve",
  args: [],
});

🔧 Configuration

Environment Variables

Copy .env.example to .env and configure:

# Port Configuration (consecutive ports for easy management)
WEB_PORT=3000
API_PORT=3001
ANVIL_PORT=3002

# API Configuration
PORT=3001
NODE_ENV=development

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

# Network Configuration
CHAIN_ID=31337

# Frontend (Optional)
NEXT_PUBLIC_WC_PROJECT_ID=  # WalletConnect Project ID

Foundry Networks

Edit packages/contracts/foundry.toml:

[rpc_endpoints]
localhost = "http://127.0.0.1:8545"
sepolia = "${SEPOLIA_RPC_URL}"

🚀 Quick Start Example

After running task dev:up and task contracts:deploy, use the new packages:

// In your component
import { useScaffoldReadContract, useScaffoldWriteContract } from "@bun-eth/hooks";
import { Address, Balance, FaucetButton, BurnerWalletInfo } from "@bun-eth/components";
import { useAccount } from "wagmi";

function MyDApp() {
  const { address } = useAccount();

  // Read contract state - auto-refreshes on new blocks
  const { data: value } = useScaffoldReadContract({
    contractName: "SimpleStorage",
    functionName: "retrieve",
    watch: true,
  });

  // Write to contract - includes notifications
  const { writeContractAsync, isMining } = useScaffoldWriteContract("SimpleStorage");

  const handleStore = async () => {
    await writeContractAsync("store", [42]);
  };

  return (
    <div>
      {/* Show burner wallet info if using burner */}
      <BurnerWalletInfo />

      {/* Display address with ENS */}
      <Address address={address} format="short" />

      {/* Balance with USD toggle */}
      <Balance address={address} usdMode />

      {/* Faucet for test ETH */}
      <FaucetButton />

      {/* Contract interaction */}
      <p>Stored Value: {value?.toString()}</p>
      <button onClick={handleStore} disabled={isMining}>
        {isMining ? "Mining..." : "Store 42"}
      </button>
    </div>
  );
}

📚 Available Commands

Run task --list to see all available commands.

Essential Commands

# Setup - Complete local setup with tests
task setup

# Start - Quick start dev stack (install, compile, start services)
task start

# Development
task dev:up              # Start local development stack (Anvil + API + Web)
task dev:down            # Stop local development stack
task dev:logs            # View logs from all services

# Frontend
task web:dev             # Start Next.js dev server
task web:build           # Build Next.js for production
task web:start           # Start Next.js production server

# Contracts
task contracts:compile   # Compile smart contracts
task contracts:deploy    # Deploy to local network + generate types (🔥 hot reload)
task contracts:generate  # Generate TypeScript from deployed contracts
task contracts:test      # Run contract tests
task contracts:lint      # Check Solidity formatting
task contracts:format    # Format Solidity files

# Testing
task test                # Run all tests
task test:core           # Run core utility tests only
task test:sdk            # Run SDK tests only
task test:contracts      # Run contract tests only

# Code Quality
task lint                # Lint all packages (TypeScript + Solidity)
task lint:fix            # Lint and auto-fix TypeScript issues

# Other
task clean               # Clean build artifacts
task status              # Show development stack status
task check:health        # Check API health

🚢 Deployment

Deploy Contracts to Testnet

See DEPLOYMENT_GUIDE.md for detailed instructions.

Quick start for Sepolia:

Configure .env:

cp .env.example .env
# Add SEPOLIA_RPC_URL, PRIVATE_KEY, and ETHERSCAN_API_KEY

Deploy:

task contracts:deploy:sepolia

Deploy API to Production

Build and run with Docker:

docker build -f apps/api/Dockerfile -t bun-eth-api .
docker run -p 3001:3001 --env-file .env bun-eth-api

🤝 Contributing

Contributions are welcome! Please follow these steps:

Fork the repository
Create a feature branch: git checkout -b feature/my-feature
Commit your changes: git commit -m 'feat: add my feature'
Push to the branch: git push origin feature/my-feature
Open a Pull Request

📚 Documentation

E2E_TESTING_GUIDE.md - Comprehensive E2E testing guide
IMPROVEMENTS_SUMMARY.md - Latest improvements and features
DEPLOYMENT_GUIDE.md - Deploy to testnets and mainnet
FEATURES.md - Complete feature list and comparisons
ARCHITECTURE.md - System design and architecture
packages/hooks/README.md - Custom hooks documentation
packages/components/README.md - UI components guide
packages/foundry-deployer/README.md - Hot reload system
packages/burner-connector/README.md - Burner wallet connector

🎓 Learn More

Foundry Book - Learn Foundry
Viem Docs - TypeScript Ethereum library
Wagmi Docs - React Hooks for Ethereum
RainbowKit Docs - Wallet connection UI
Scaffold-ETH 2 - Original inspiration

📄 License

MIT License - see LICENSE file for details

🙏 Acknowledgments

Bun - The blazingly fast JavaScript runtime
Elysia - Fast and ergonomic TypeScript web framework
Foundry - Blazing fast Ethereum development toolkit
scaffold-eth-2 - Inspiration for features
wagmi + viem - Modern Ethereum libraries
RainbowKit - Beautiful wallet UX

📞 Support

Built with ⚡ by the Bun-Eth community

Name		Name	Last commit message	Last commit date
Latest commit History 31 Commits
.changeset		.changeset
.claude		.claude
.github/workflows		.github/workflows
apps		apps
docker		docker
docs		docs
packages		packages
scripts		scripts
tooling		tooling
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
TEMPLATE_PROPOSAL.md		TEMPLATE_PROPOSAL.md
Taskfile.yml		Taskfile.yml
biome.json		biome.json
bun.lock		bun.lock
package.json		package.json
tsconfig.json		tsconfig.json
turbo.json		turbo.json

Folders and files

Latest commit

History

Repository files navigation

Bun-Eth

✨ Features

🚀 Quick Start

Using the CLI (Recommended)

Using as GitHub Template

Manual Clone

📋 Prerequisites

Install Task

🏗️ Project Structure

🛠️ Development

Start Development Stack

Start Web UI

Stop Development Stack

View Logs

📜 Smart Contracts

Compile Contracts

Deploy Contracts

Test Contracts

🌐 API Endpoints

Health Check

Get Wallet Info

Send Transaction

Call Contract (Read)

Send Contract Transaction (Write)

🌐 Frontend Development

Web Tasks

Wallet Integration

🧪 Testing

Run All Tests

Run Tests by Package

End-to-End Tests

Complete Test Suite

Individual Test Layers

Standard E2E Tests

E2E Testing Features

Watch Mode

Coverage

🎨 Code Quality & Linting

Why Biome?

Linting Commands

Manual Linting

Solidity Formatting

CI/CD Integration

Configuration

📦 Using the SDK

🔧 Configuration

Environment Variables

Foundry Networks

🚀 Quick Start Example

📚 Available Commands

Essential Commands

🚢 Deployment

Deploy Contracts to Testnet

Deploy API to Production

🤝 Contributing

📚 Documentation

🎓 Learn More

📄 License

🙏 Acknowledgments

📞 Support

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages