Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Miniapp Template

A Farcaster Frame mini-app with React, database, and Neynar API integration.

jack new my-miniapp -t miniapp

What You Get

  • React + Vite - Fast frontend development
  • Hono API - Backend routes on the same deployment
  • D1 Database - SQLite database included
  • Neynar API - Farcaster data integration
  • Tailwind CSS - Styling ready to go

Project Structure

my-miniapp/
├── src/
│   ├── App.tsx
│   ├── main.tsx
│   ├── worker.ts
│   ├── wagmi.ts
│   ├── hooks/
│   ├── lib/
│   └── index.css
├── schema.sql
├── package.json
├── vite.config.ts
├── wrangler.jsonc
└── AGENTS.md
  • src/App.tsx — React application
  • src/main.tsx — Entry point
  • src/worker.ts — Hono API routes
  • src/wagmi.ts — Wallet configuration
  • src/hooks/ — React hooks
  • src/lib/ — Utilities
  • src/index.css — Styles
  • schema.sql — Database schema
  • wrangler.jsonc — Deployment config
  • AGENTS.md — AI context

Requirements

This template requires a Neynar API key for Farcaster integration.

  1. Get a free key at neynar.com
  2. jack will prompt for it on first deploy

Database Schema

The template includes a guestbook example:

CREATE TABLE IF NOT EXISTS guestbook (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  fid INTEGER NOT NULL,
  username TEXT NOT NULL,
  display_name TEXT,
  pfp_url TEXT,
  message TEXT NOT NULL CHECK(length(message) <= 140),
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

API Routes

The backend includes working examples:

// GET /api/notifications?fid=123
// Proxies to Neynar API with your API key
 
// GET /api/guestbook
// Fetch recent guestbook entries from D1
 
// POST /api/guestbook
// Add a new entry { fid, username, message }

Frontend

The React app uses the Farcaster Miniapp SDK:

import { useMiniAppContext } from "@farcaster/miniapp-react";
 
function App() {
  const { context } = useMiniAppContext();
 
  // context.user contains the current Farcaster user
  // context.client contains frame information
}

Deploying

jack ship

After deploy, jack will:

  1. Copy the URL to your clipboard
  2. Open the Farcaster manifest signing tool
  3. Prompt you to paste the signed accountAssociation JSON into public/.well-known/farcaster.json
  4. Link to the Farcaster preview tool

The manifest file lives at public/.well-known/farcaster.json and is served as a static asset at /.well-known/farcaster.json after deploy. Use the miniapp key (not frame).

Development

Run locally with hot reload:

bun run dev

The frontend runs on localhost:5173, proxying API requests to the worker.

Resources