Skip to content
Get help

Getting Started with Mini Apps

Overview

Mini Apps are lightweight web applications that run natively within clients like Coinbase Wallet. Users instantly access mini apps without downloads, benefit from seamless wallet interactions, and discover apps directly in the social feed. This benefits app developers by creating viral loops for user acquisition and engagement.

A Mini App is composed of:

  • Your existing web application
  • <MiniKitProvider> wrapper component
  • farcaster.json manifest file
  • Standard deployment to any hosting platform (Vercel, Netlify, etc.)

No rebuilding, architectural changes, or complex integrations are required.

Code Implementation

Before (Standard Web Application)

function App() {
  return (
    <div>
      <MyExistingComponent />
      <AnotherComponent />
    </div>
  );
}

After (Mini App Implementation)

import { MiniKitProvider } from '@coinbase/onchainkit/minikit';
 
function App() {
  return (
    <MiniKitProvider projectId="your-id">
      <MyExistingComponent />  {/* Existing components unchanged */}
      <AnotherComponent />     {/* Existing components unchanged */}
    </MiniKitProvider>
  );
}

Changes Required: Two import lines and one wrapper component. All existing components remain unchanged.

Implementation Examples

Simple Example with MiniKit

npx create-onchain --mini
cd my-miniapp
npm run dev

Non-React Implementation (Vue, Svelte, Vanilla JS)

npm create @farcaster/mini-app
cd my-miniapp
npm run dev

Result: Functional Mini App with wallet integration, transaction capabilities, and social features.

Pre-Solved Development Challenges

Common Engineering Concerns

  • Complex wallet integration processes
  • Authentication flow implementation
  • Mobile responsiveness requirements
  • Cross-platform compatibility issues
  • User onboarding friction

MiniKit Automated Solutions

  • Mobile Optimization: Automatic handling of safe areas and responsive design
  • Platform Compatibility: Operates across Farcaster, Coinbase Wallet, and web browsers
  • User Context: Immediate access to user identification

Manifest File Configuration

Mini Apps require one configuration file located at /well-known/farcaster.json in your project root. This file instructs clients how to display your application.

Sample Manifest Structure

{
  "accountAssociation": {
    "header": "eyJmaWQiOjgxODAyNi...",
    "payload": "eyJkb21haW4iOiJleGFtcGxlLmNvbSJ9",
    "signature": "MHhmOGQ1YzQyMmU3ZTZlMWNhMzU1..."
  },
  "frame": {
    "version": "1",
    "name": "Your App Name",
    "subtitle": "Short tagline",
    "description": "Detailed description of what your app does",
    "iconUrl": "https://yourapp.com/icon.png",
    "homeUrl": "https://yourapp.com",
    "splashImageUrl": "https://yourapp.com/splash.png",
    "splashBackgroundColor": "#000000",
    "heroImageUrl": "https://yourapp.com/hero.png",
    "tagline": "One-line value proposition",
    "screenshotUrls": [
      "https://yourapp.com/screenshot1.png",
      "https://yourapp.com/screenshot2.png"
    ],
    "primaryCategory": "games",
    "tags": ["multiplayer", "strategy", "onchain"],
    "webhookUrl": "https://yourapp.com/api/webhook"
  }
}

Categories and Discovery

Primary Categories

  • games: Gaming and entertainment applications
  • social: Social networking and communication tools
  • finance: DeFi, trading, and payment applications
  • utility: Tools and productivity applications
  • productivity: Task management and organization tools
  • developer-tools: Development utilities
  • art-creativity: Creative and artistic applications

Account Association (Domain Verification)

Domain ownership verification is required. Generate your manifest using:

MiniKit Method: 
npx create-onchain --manifest
Alternative Farcaster Tool Process:

You can use the Farcaster manifest tool for generation.

Image Requirements

  • iconUrl: 200x200px PNG/JPG format
  • splashImageUrl: 200x200px PNG/JPG (displayed during app loading)
  • heroImageUrl: 1200x628px PNG/JPG (for featured placement)
  • screenshotUrls: App store screenshots in various sizes

Deployment Process

The deployment process remains identical to standard web applications:

  1. Build Application: npm run build (standard process)
  2. Add Configuration: public/.well-known/farcaster.json
  3. Deploy: Use any hosting platform (Vercel, Netlify, custom servers)
  4. Browser Testing: Functions as standard web application
  5. Farcaster Testing: You can test using the farcaster tools here.

No special hosting, new infrastructure, or complex setup procedures required.

Frequently Asked Questions

Do we need to rebuild our entire application?

No. Wrap your existing application in <MiniKitProvider>. Implementation complete.

Will this break our current web application?

No. Mini Apps function in regular browsers. The same codebase works across all platforms.

Do we need blockchain expertise?

No. Integration complexity is similar to Stripe implementation.

What about user data and privacy?

Maintain current practices. You control data, backend systems, and privacy policies.

What is the performance impact?

Minimal impact. MiniKit SDK is approximately 50KB. Application performance remains unchanged.

We don't use React/Next.js. Is this compatible?

Yes. The Farcaster SDK supports Vue, Angular, Svelte, and any web framework.

Result: Functional Mini App with wallet integration, transaction capabilities, and social features.

Technical Resources