Based House Heads

An interactive NFT minting carousel built as a Farcaster Mini App, showcasing a portrait collection created during Based House Devconnect. This project demonstrates modern Web3 development with React, TypeScript, and blockchain integration on the Base network.

Artist: @qabqabqab | Developer: @mattlee

Overview

Based House Heads is a touch-enabled carousel that allows users to browse through 18 unique portrait NFTs and mint them directly on the Base blockchain. The application integrates with Farcaster's social graph, providing a seamless social minting experience with wallet connection and transaction handling.

Technical Stack

Frontend

React 18.3 with TypeScript 5.8 (strict mode)
Vite 5.2 for fast development and optimized builds
TanStack React Query 5.45 for data fetching and caching
Touch gesture handling with swipe detection

Web3 Integration

Wagmi (latest) - Type-safe Ethereum hooks and wallet connection
Viem (latest) - Low-level Ethereum client library
Farcaster Mini App SDK - Social integration and wallet connector
Base Chain (Chain ID: 8453) - L2 deployment for low gas fees

Smart Contracts

Zora Creator 1155 - ERC-1155 NFT standard implementation
Zora ETH Minter - Decentralized minting protocol
Mint price: 0.000777 ETH per NFT

Developer Tools

Biome.js 1.8 - Fast linting and formatting (zero config)
TypeScript strict mode - Maximum type safety
Vercel Edge Functions - Serverless OG image generation with @vercel/og

Key Features

1. Interactive Carousel

Touch-enabled swipe navigation with momentum tracking
Keyboard navigation (arrow keys)
Responsive image loading with fallbacks
Smooth transitions and visual feedback

2. NFT Minting

One-click minting with transaction status tracking
Gas estimation and error handling
Post-mint success state with transaction links
Ownership detection (prevents re-minting same NFT)

3. Wallet Integration

Farcaster-native wallet connection
Balance checking (NFT ownership + ETH balance)
Multi-state UI (disconnected, connected, minting, success, error)
Automatic wallet reconnection

4. Metadata Fetching

On-chain token URI resolution
IPFS gateway support with fallbacks
Client-side metadata caching
Error boundaries and loading states

5. Social Features

Farcaster user profile display
Open Graph meta tags for rich link previews
Dynamic OG image generation per NFT
Frame embed support for Farcaster feeds

Architecture Highlights

Custom Hooks

useMint - Encapsulates minting logic, transaction handling, and state management
useNftMetadata - Handles on-chain URI resolution and IPFS metadata fetching
useFarcasterContext - Provides Farcaster SDK context throughout the app

Configuration Management

Centralized constants in src/config/constants.ts
Type-safe ABI definitions in src/config/abi.ts
Environment-based RPC configuration

Component Structure

src/
├── components/
│   ├── App.tsx              # Main carousel logic
│   ├── MintButton.tsx       # State machine for minting UI
│   ├── ConnectWallet.tsx    # Wallet connection flow
│   ├── LoadingSpinner.tsx   # Animated loading states
│   └── UserProfile.tsx      # Farcaster profile display
├── hooks/
│   ├── useFarcasterContext.ts
│   ├── useMint.ts
│   └── useNftMetadata.ts
└── config/
    ├── constants.ts         # 18 NFT configurations
    └── abi.ts              # Smart contract ABIs

Local Development

Prerequisites

Node.js 18+ (or compatible runtime)
pnpm (recommended) or npm
Git

Setup

Clone the repository

git clone https://github.com/mattleesounds/based-house-heads.git
cd based-house-heads

Install dependencies

pnpm install
# or
npm install --legacy-peer-deps

Configure environment variables

Create a .env file in the root directory:
```
cp .env.example .env
```
Edit .env and add your Coinbase Developer Platform RPC URL:
```
VITE_BASE_RPC_URL=https://api.developer.coinbase.com/rpc/v1/base/YOUR_API_KEY_HERE
```
Get your API key at: https://portal.cdp.coinbase.com/
Start development server
```
pnpm dev
# or
npm run dev
```
Open http://localhost:5173 in your browser.

Testing Locally

1. Test Carousel Navigation

Swipe left/right on touch devices
Use arrow keys on desktop
Verify smooth transitions between all 18 NFTs
Check that metadata loads for each NFT

2. Test Wallet Connection

Click "Connect Wallet" button
Connect a wallet (MetaMask, WalletConnect, etc.)
Verify your address displays correctly
Check that your Farcaster profile appears (if logged in)

3. Test Minting Flow

Navigate to any NFT
Click "Mint" button
Approve the transaction in your wallet
Verify transaction success and block explorer link
Check that the NFT appears as "Owned" after minting

4. Test Error Handling

Try minting with insufficient ETH balance
Try minting an NFT you already own
Verify appropriate error messages display

5. Test Responsive Design

Test on mobile viewport (375px width)
Test on tablet viewport (768px width)
Test on desktop viewport (1920px width)
Verify touch and mouse interactions work correctly

Building for Production

pnpm build
# or
npm run build

Preview the production build:

pnpm preview
# or
npm run preview

Deployment

This project is configured for Vercel deployment with:

Edge Functions for OG image generation (/api/og-image)
Serverless functions for dynamic meta tags (/api/og)
Automatic HTTPS and CDN distribution
Environment variable management

Deploy to Vercel

Install Vercel CLI:
```
npm i -g vercel
```
Deploy:
```
vercel
```
Set environment variables in Vercel dashboard:
- VITE_BASE_RPC_URL - Your Coinbase RPC endpoint

Farcaster Configuration

The /.well-known/farcaster.json file configures this app as a Farcaster Mini App. To use this for your own Farcaster account:

Update /.well-known/farcaster.json with your domain and FID
Generate account association signature using Farcaster SDK
Deploy to your domain
Verify at https://yourdomain.com/.well-known/farcaster.json

Code Quality

Linting & Formatting

# Check code style
pnpm check
# or
npm run check

# Fix auto-fixable issues
pnpm check:fix
# or
npm run check:fix

Type Checking

# Run TypeScript compiler
pnpm tsc
# or
npm run tsc

Project Structure

based-house-heads/
├── api/                    # Vercel serverless functions
│   ├── og.ts              # Dynamic OG meta tags
│   └── og-image.tsx       # OG image generation (Edge Runtime)
├── public/                # Static assets
│   ├── assets/
│   │   ├── heads/         # 18 NFT portrait images
│   │   ├── icons/         # UI icons
│   │   └── fonts/         # Custom fonts (TT Firs Neue)
│   └── .well-known/
│       └── farcaster.json # Farcaster app configuration
├── src/                   # React application
│   ├── components/        # React components
│   ├── hooks/            # Custom React hooks
│   ├── config/           # Constants and ABIs
│   ├── App.tsx           # Main app component
│   ├── main.tsx          # Entry point
│   └── wagmi.ts          # Wagmi configuration
├── .env.example          # Environment variable template
├── vercel.json           # Vercel deployment config
├── vite.config.ts        # Vite bundler config
└── package.json          # Dependencies and scripts

Smart Contract Details

Zora Creator 1155 Contract

Network: Base (Chain ID: 8453)
Standard: ERC-1155 (multi-token)
Minter: Zora ETH Minter (0x04E2516A2c207E84a1839755675dfd8eF6302F0a)

Each of the 18 NFTs has its own contract address configured in src/config/constants.ts.

Development Techniques Demonstrated

This project showcases:

Type-safe Web3 development with Wagmi + Viem + TypeScript
Modern React patterns (hooks, context, composition)
State management with React Query (server state) and React state (UI state)
Custom hook design for reusable blockchain logic
Error boundary patterns and graceful degradation
IPFS integration with fallback strategies
Touch gesture detection and custom event handling
Responsive design with mobile-first approach
Edge Functions for dynamic OG image generation
Monorepo-ready structure with clear separation of concerns

License

MIT

Links

Live App: based-house-heads.vercel.app
Farcaster Documentation: miniapps.farcaster.xyz
Zora Documentation: docs.zora.co
Base Network: base.org

Name		Name	Last commit message	Last commit date
Latest commit History 34 Commits
api		api
public		public
src		src
.env.example		.env.example
.gitignore		.gitignore
.npmrc		.npmrc
README.md		README.md
biome.json		biome.json
index.html		index.html
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
vercel.json		vercel.json
vite.config.ts		vite.config.ts

Folders and files

Latest commit

History

Repository files navigation

Based House Heads

Overview

Technical Stack

Frontend

Web3 Integration

Smart Contracts

Developer Tools

Key Features

1. Interactive Carousel

2. NFT Minting

3. Wallet Integration

4. Metadata Fetching

5. Social Features

Architecture Highlights

Custom Hooks

Configuration Management

Component Structure

Local Development

Prerequisites

Setup

Testing Locally

1. Test Carousel Navigation

2. Test Wallet Connection

3. Test Minting Flow

4. Test Error Handling

5. Test Responsive Design

Building for Production

Deployment

Deploy to Vercel

Farcaster Configuration

Code Quality

Linting & Formatting

Type Checking

Project Structure

Smart Contract Details

Zora Creator 1155 Contract

Development Techniques Demonstrated

License

Links

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages