Farcaster Mini App Template
View on GitHubA clean, secure template for building Farcaster Mini Apps with Next.js, TypeScript, and Tailwind CSS. Demonstrates how to access and display user data from the Farcaster Mini App context without any external API dependencies.
Table of Contents
Overview
This template provides a secure foundation for building Farcaster Mini Apps. It demonstrates best practices for accessing Mini App context data, implementing user interfaces, and maintaining security throughout the development process.
Access Mini App Context
Shows how to get user data from Farcaster including name, username, FID, location, and profile picture.
Secure by Design
No hardcoded secrets, proper validation, error boundaries, and XSS protection built-in.
TypeScript Ready
Full TypeScript coverage with official Farcaster Mini App SDK type definitions.
Mini App Actions
Implements open URLs, share functionality, and proper loading states with error handling.
What This Template Shows
- • Accesses Mini App Context data including user info and FID
- • Displays user information with profile pictures and stats
- • Generates consistent user stats based on user's FID
- • Handles loading states and error conditions properly
- • Provides debug information for development
- • Implements Mini App actions like open URLs and sharing
Quick Start
Clone and Install
Get the template and install dependencies
git clone https://github.com/jumpboxtech/farcaster-miniapp-exampledemo cd farcaster-miniapp-exampledemo npm install
Start Development
Launches the development server on localhost:3000
npm run dev
Open and View
See your app running locally
http://localhost:3000
Test in Farcaster
Test the Mini App in the actual Farcaster environment
# Share your deployed URL in a Farcaster cast
Project Structure
├── app/ │ ├── components/ │ │ ├── ClientPage.tsx # Client wrapper component (DO NOT MODIFY) │ │ └── Demo.tsx # Main Mini App component (CUSTOMIZE THIS) │ ├── types/ │ │ └── frame.ts # Mini App SDK type definitions (DO NOT MODIFY) │ ├── globals.css # Global styles (MODIFY COLORS/FONTS) │ ├── layout.tsx # Root layout (CUSTOMIZE METADATA) │ └── page.tsx # Home page (DO NOT MODIFY) ├── public/ │ └── images/ # Add your images here (REQUIRED) ├── package.json # Dependencies (CUSTOMIZE NAME/DESCRIPTION) ├── LICENSE # MIT License (UPDATE COPYRIGHT) └── README.md # This file (CUSTOMIZE FOR YOUR PROJECT)
Safe to Modify
- •
Demo.tsx- Main component logic - •
layout.tsx- App metadata - •
globals.css- Styling - •
package.json- Project config - •
public/images/- Asset files
Do Not Modify
- •
ClientPage.tsx- SSR wrapper - •
frame.ts- Type definitions - •
page.tsx- Entry point - • Mini App SDK integration code
- • Core configuration files
Comprehensive Customization Guide
1. App Metadata & Branding (REQUIRED TO CHANGE)
Update these URLs in app/layout.tsx to match your deployed app:
const frameMetadata = {
imageUrl: 'https://your-domain.com/images/frame-preview.png',
button: {
title: 'View Profile',
action: {
name: 'Your App Name',
url: 'https://your-domain.com',
splashImageUrl: 'https://your-domain.com/images/splash.png',
splashBackgroundColor: '#000000'
}
}
};2. Main App Content (CUSTOMIZE EXTENSIVELY)
In app/components/Demo.tsx, update:
- • App title and branding elements
- • User stats system and metrics
- • Stat display labels and formulas
- • Welcome message and descriptions
- • Action buttons and their URLs
3. Visual Styling (OPTIONAL BUT RECOMMENDED)
Customize the visual appearance:
// Replace blue theme with your brand colors text-blue-600 → text-your-color-600 bg-blue-600 → bg-your-color-600 border-blue-600 → border-your-color-600 // Background gradient bg-gradient-to-br from-gray-900 to-black → bg-gradient-to-br from-your-color-900 to-your-color-800
Security Best Practices
What This Template Does Right
Common Security Mistakes to Avoid
1. Hardcoding API Keys
// ❌ NEVER commit API keys
const API_KEY = 'sk-1234567890abcdef';
// ✅ Use environment variables
const API_KEY = process.env.NEXT_PUBLIC_API_KEY;
2. Trusting User Input
// ❌ Direct interpolation
<div>Welcome {userData?.name}</div>// ✅ Validation and sanitization
<div>Welcome {sanitize(userData?.name) || 'User'}</div>Advanced Customization Examples
Example 1: NFT Profile App
interface NFTStats {
collectionsOwned: number;
totalNFTs: number;
rarityScore: number;
floorValue: number;
}
function generateNFTStats(fid: number): NFTStats {
const seed = fid;
const hash = (num: number) => Math.abs(Math.sin(num * 12.9898) * 43758.5453) % 1;
return {
collectionsOwned: Math.floor(hash(seed) * 20) + 1,
totalNFTs: Math.floor(hash(seed * 2) * 500) + 10,
rarityScore: Math.floor(hash(seed * 3) * 100),
floorValue: Math.floor(hash(seed * 4) * 50) + 5,
};
}Example 2: Gaming Profile App
interface GameStats {
level: number;
xp: number;
wins: number;
winRate: number;
}
function generateGameStats(fid: number): GameStats {
const seed = fid;
const hash = (num: number) => Math.abs(Math.sin(num * 12.9898) * 43758.5453) % 1;
const wins = Math.floor(hash(seed) * 1000);
const totalGames = wins + Math.floor(hash(seed * 2) * 500);
return {
level: Math.floor(hash(seed * 3) * 100) + 1,
xp: Math.floor(hash(seed * 4) * 100000),
wins,
winRate: Math.floor((wins / totalGames) * 100),
};
}Deployment & Production
Vercel (Recommended)
npm install -g vercel vercel --prod
Netlify
Build: npm run build Publish: .next
Railway
Dockerfile deployment supported
Production Checklist
- All URLs updated to production domain
- HTTPS certificate valid
- Images uploaded and accessible
- Environment variables configured
- Error monitoring setup
- Analytics configured
- CSP headers configured
- CORS headers configured
Resources & Support
Ready to build amazing Farcaster Mini Apps? This template gives you everything you need to get started safely and securely!