# Deploy a Farcaster Mini App: Complete Tutorial *Build Your First Farcaster Mini App in Under 30 Minutes* By [jumpbox](https://paragraph.com/@jumpbox) ยท 2025-08-21 farcaster, miniapp, vercel, github, examples, tutorial --- This comprehensive guide walks you through deploying a Farcaster mini application using the JumpboxTech template and Vercel hosting platform. Prerequisites ------------- Before starting, ensure you have: * Node.js installed (version 16 or higher) * Git installed on your system * A GitHub account * Basic command line knowledge Step 1: Clone the Repository ---------------------------- Download the Farcaster mini app template from GitHub: git clone https://github.com/jumpboxtech/farcaster-miniapp-exampledemo.git cd farcaster-miniapp-exampledemo Step 2: Prepare Required Images ------------------------------- Create two essential images for your mini app and place them in the `/public/images/` directory: ### App Preview Image (`frame-preview.png`) * **Dimensions**: Minimum 600x400px (recommended 1200x630px) * **Purpose**: Displayed when your mini app is shared in Farcaster * **Content**: Should clearly represent your app with high contrast * **Requirements**: Include your app name/logo for brand recognition ### Splash Screen Image (`splash.png`) * **Dimensions**: 512x512px (square format) * **Purpose**: Shown while your mini app is loading * **Content**: Your logo or app icon * **Requirements**: Simple design that works on both dark and light backgrounds Step 3: Set Up Vercel Account ----------------------------- 1. Visit [vercel.com](https://vercel.com) and create a free account 2. Connect your GitHub account for seamless deployment 3. Verify your email address to activate your account Step 4: Install Dependencies and Vercel CLI ------------------------------------------- Navigate to your project directory and install the required packages: Install the Vercel CLI globally for deployment: npm install -g vercel Step 5: Deploy to Vercel ------------------------ Run the deployment process with the Vercel CLI: During the interactive setup, you'll be prompted to configure: * **Deploy confirmation**: Select "yes" to proceed * **Scope selection**: Choose your personal account or team * **Project linking**: Select "no" to create a new project * **Project name**: Enter a descriptive name (e.g., "miniapp-exampledemo") * **Code directory**: Use "./" for the current directory * **Settings modification**: Select "no" to use auto-detected Next.js settings The CLI will automatically detect your Next.js configuration: * Build Command: `next build` * Development Command: `next dev --port $PORT` * Install Command: `npm install` * Output Directory: Next.js default Step 6: Production Deployment ----------------------------- After the initial deployment, push your app to production: vercel --prod This command will: * Build your application for production * Deploy to Vercel's global CDN * Provide you with a production URL Expected Output --------------- Your deployment process should look similar to this: Vercel CLI 37.4.0 ๐Ÿ”— Linked to [youraccount]-projects/miniapp-exampledemo (created .vercel) ๐Ÿ” Inspect: vercel.com/[youraccount]... โœ… Production: https://miniapp-exampledemo-[hash]-[youraccount]-projects.vercel.app ๐Ÿ“ Deployed to production. Run `vercel --prod` to overwrite later Step 7: Configure Your Mini App ------------------------------- Before your mini app is ready for use, update these critical files: ### Update Metadata (`app/layout.tsx`) Replace placeholder URLs with your production domain: const frameMetadata = { imageUrl: 'https://your-domain.vercel.app/images/frame-preview.png', button: { title: 'View Profile', action: { name: 'Your App Name', url: 'https://your-domain.vercel.app', splashImageUrl: 'https://your-domain.vercel.app/images/splash.png', splashBackgroundColor: '#000000' } } }; ### Customize Content (`app/components/Demo.tsx`) Personalize your app's branding:

Your App Name
Your Tagline

Step 8: Test Your Mini App -------------------------- ### Development Testing 1. Access your local development server: `npm run dev` 2. Open `http://localhost:3000` in your browser 3. Verify all components load correctly ### Production Testing 1. Visit your Vercel production URL 2. Share the URL in a Farcaster cast 3. Interact with the mini app to ensure proper functionality Step 9: Integration with Farcaster ---------------------------------- To make your mini app discoverable: 1. **Share in Farcaster**: Post your production URL in a cast 2. **Use Developer Tools**: Access Farcaster's mini app validation tools 3. **Test Interactions**: Verify buttons, data display, and user experience Security Considerations ----------------------- The template includes built-in security features: * **HTTPS enforcement**: All URLs must use HTTPS in production * **Input validation**: Frame context data is properly validated * **XSS protection**: No dangerous innerHTML usage * **Type safety**: Full TypeScript coverage prevents runtime errors Troubleshooting --------------- ### Common Issues **Mini app not loading** * Check browser console for SDK errors * Verify all URLs use HTTPS * Ensure images are publicly accessible **Images not displaying** * Confirm image dimensions meet requirements * Verify CORS headers are properly configured * Test image URLs directly in browser **Buttons not functioning** * Check mini app SDK initialization * Verify button URLs are valid and accessible * Review console logs for JavaScript errors Next Steps ---------- After successful deployment: 1. **Monitor Performance**: Use Vercel Analytics to track usage 2. **Customize Features**: Modify user stats, colors, and functionality 3. **Add Analytics**: Integrate tracking tools for user insights 4. **Scale Up**: Consider adding external APIs for dynamic content Conclusion ---------- You now have a fully functional Farcaster mini app deployed on Vercel. The template provides a secure foundation for building engaging Farcaster experiences. Continue customizing the design, functionality, and user experience to match your specific use case. --- *Originally published on [jumpbox](https://paragraph.com/@jumpbox/deploy-a-farcaster-mini-app-complete-tutorial)*