Generalized Mini App Template (Internal)

Production-ready, multi-platform mini app template built by Builders Garden. Supports Farcaster, Worldcoin, MiniPay, and browser environments with multi-method authentication (SIWF, SIWE, Worldcoin MiniKit), dual-platform notifications, webhook handling, OG image generation, and a minimal example UI.

Tech stack

• Next.js 16 (App Router, Turbopack, typed routes) + React 19 + TypeScript 5.9
• Tailwind CSS 4 + shadcn/ui (base-maia style)
• Biome 2 + Ultracite for linting/formatting
• Better Auth with SIWF, SIWE, and Worldcoin MiniKit plugins
• Neynar API client for Farcaster
• @worldcoin/minikit-js for Worldcoin Mini App support
• Drizzle ORM + PostgreSQL (Turso/libSQL compatible)
• Wagmi 3 + Viem 2 for Web3 wallet interactions
• Farcaster Mini App SDK/Core/Node
• @tanstack/react-query for server state
• LiFi SDK for multi-chain wallet balances and token prices

Requirements

• Node >= 20.18.0
• pnpm >= 10.0.0

Quick start

1. Install dependencies

pnpm install

2. Configure environment variables

cp .env.example .env

Fill in the values described in the Environment section below.

3. Run the dev server

pnpm dev

4. Expose localhost via a tunnel for Warpcast debugging Use your preferred tunneling tool and follow this guide: https://dtech.vision/farcaster/miniapps/theultimatefarcasterminiappdebuggingguide/#warpcast-debugger

5. Generate your Farcaster manifest values

• Read: https://miniapps.farcaster.xyz/docs/guides/publishing
• Use Warpcast Manifest Tool: https://warpcast.com/~/developers/mini-apps/manifest
• Paste your tunnel domain and copy the manifest header/payload/signature into .env

Environment

Server-side (required):

• DATABASE_URL: PostgreSQL/Turso connection string
• BETTER_AUTH_SECRET: Session encryption secret (generate: openssl rand -base64 32)
• NEYNAR_API_KEY: Neynar API key
• NOTIFICATION_SECRET: Secret to authorize POST /api/notify (generate: openssl rand -base64 32)
• WORLD_NOTIFICATION_API_KEY: Worldcoin Developer API notification key

Client-side:

• NEXT_PUBLIC_APP_ENV: development | staging | production (default production)
• NEXT_PUBLIC_URL: Public base URL (e.g. https://your-app.vercel.app or tunnel URL)
• NEXT_PUBLIC_WORLD_APP_ID: Worldcoin app ID (from https://developer.worldcoin.org/)
• NEXT_PUBLIC_FARCASTER_APP_ID: Farcaster app ID
• NEXT_PUBLIC_FARCASTER_HEADER: From Warpcast Manifest Tool
• NEXT_PUBLIC_FARCASTER_PAYLOAD: From Warpcast Manifest Tool
• NEXT_PUBLIC_FARCASTER_SIGNATURE: From Warpcast Manifest Tool
• NEXT_PUBLIC_BASE_APP_ID: Base chain app ID
• NEXT_PUBLIC_BASE_BUILDER_ADDRESS: Base chain builder address (app-specific)
• NEXT_PUBLIC_APPLICATION_NAME: App display name
• NEXT_PUBLIC_APPLICATION_DESCRIPTION: App description

Scripts

pnpm dev           # Start dev server (Turbopack)
pnpm build         # Lint then build
pnpm start         # Start production server
pnpm lint          # Biome checks
pnpm format        # Biome format --write
pnpm typecheck     # TypeScript noEmit
pnpm pre-build     # Lint + typecheck

# Drizzle / Database
pnpm db:generate   # Generate migrations
pnpm db:migrate    # Apply migrations
pnpm db:push       # Push schema
pnpm db:pull       # Pull schema from DB
pnpm db:studio     # Drizzle Studio

Features

Authentication (Better Auth — 3 methods)

Three auth methods auto-selected based on environment:

1. Farcaster SIWF — Quick Auth via @farcaster/miniapp-sdk → better-auth-siwf plugin → Neynar user resolution
2. Worldcoin MiniKit — Wallet auth via @worldcoin/minikit-js → better-auth-minikit plugin
3. Browser SIWE — Wagmi wallet connection → better-auth-siwe plugin (fallback for browsers)

• Server config in src/lib/auth/index.ts
• Client in src/lib/auth/auth.client.ts
• Auth context in src/contexts/auth-context.tsx auto-detects environment and selects the appropriate flow
• Trusted origin and cookie settings derived from NEXT_PUBLIC_URL

Environment detection

• Detects Farcaster Mini App, Worldcoin Mini App, or standard browser
• Context in src/contexts/environment-context.tsx
• All other contexts (auth, app) adapt behavior based on detected environment

API proxy/auth guard

• Middleware-like proxy in src/proxy.ts protects all /api/* endpoints by default
• Public APIs bypassed: /api/og/*, /api/webhook/farcaster, /api/notify, /api/auth/*

Farcaster Mini App metadata

• Dynamic miniapp metadata embedded in generateMetadata of src/app/profile/[userId]/page.tsx
• fc:miniapp points to a deep link back into the app
• Farcaster manifest at /.well-known/farcaster.json

Dynamic OG images

• Endpoint: GET /api/og/profile/[userId] with optional ?ar=3x2 for Farcaster aspect ratio
• Components in src/components/og-image/*

Notifications (dual-platform)

• Farcaster — Token-based via Farcaster SDK, stored per user
• Worldcoin — Wallet-based via Worldcoin Developer API
• Farcaster webhook: POST /api/webhook/farcaster
  • Validates events via @farcaster/miniapp-node and Neynar app key
  • Persists notification details per user; sends welcome/confirmation notifications
• Broadcast notifications: POST /api/notify
  • Requires header x-notification-secret: ${NOTIFICATION_SECRET}
  • Body: { "title": string, "body": string, "targetUrl?": string }
  • Sends to both Farcaster and Worldcoin users in batches

Example pages

• Home and profile flows using src/components/pages/*
• Profile routes: src/app/profile/page.tsx (own profile), src/app/profile/[userId]/page.tsx (user profile)
• Website landing page for browser users: src/components/pages/website/

API overview

• GET/POST /api/auth/[...all]: Better Auth routes (SIWF, SIWE, MiniKit)
• POST /api/webhook/farcaster: Farcaster event handler (miniapp added/removed, notifications enabled/disabled)
• POST /api/notify: Broadcast notifications to Farcaster and Worldcoin users
• GET /api/og/profile/[userId]: Dynamic OG images
• GET /.well-known/farcaster.json: Farcaster manifest

Database

• Drizzle ORM with PostgreSQL dialect (Turso/libSQL compatible)
• Schema in src/database/db.schema.ts
  • Core tables: user, session, account, verification (Better Auth)
  • App tables: farcaster, walletAddress
• Queries in src/database/queries/*
• Common commands:

pnpm db:generate
pnpm db:migrate
pnpm db:studio

Deploy

• Recommended: Vercel
• Set all required env vars in the hosting provider
• Run pnpm db:migrate before first deployment
• Ensure NEXT_PUBLIC_URL matches the deployed public URL (affects cookies, auth, and frame security)

Notes

• This repository is intended for internal use as a generalized multi-platform Mini App template.
• Update copy, branding, and components under src/components to fit your app.

Links

• Farcaster Mini Apps: https://miniapps.farcaster.xyz/
• Worldcoin Developer Portal: https://developer.worldcoin.org/
• Next.js: https://nextjs.org/docs
• Tailwind CSS: https://tailwindcss.com/docs
• Neynar: https://neynar.com
• Biome: https://biomejs.dev/
• Better Auth: https://www.better-auth.com/