create-fedi-app — Scaffolding the Fedi mini app ecosystem

Role: Creator & lead developer
Stack: TypeScript, Next.js 16, Turborepo, Bun, Vercel, Playwright
Links: create-fedi-app.keeganfrancis.com · npm · GitHub · Live demo

---

Overview

Fedi is a Bitcoin wallet built on Fedimint. Mini apps run inside its in-app browser, where the host injects window.webln, window.nostr, and window.fediInternal. Outside Fedi, those APIs don't exist — so every mini app needs provider detection, graceful fallbacks, and a dev workflow that doesn't require opening the wallet on every refresh.

Before this project, there was no standard way to start. Developers had to wire Lightning hooks, Nostr identity, safe-area layout, and env validation by hand, often copying snippets from one-off demos.

create-fedi-app fills that gap: a published npm CLI (npx create-fedi-app@latest) that scaffolds a Next.js 16 app with Fedi APIs pre-wired, optional feature modules, mock providers for local development, and documentation for deployment into the Fedi catalog.

---

The problem

Building a Fedi mini app involves more than a typical web app:

• Host-injected APIs — WebLN for Lightning, Nostr for NIP-07 identity, and fediInternal for ecash balance. Code must detect availability and degrade cleanly in a normal browser.
• Mobile WebView constraints — Mini apps run inside a wallet WebView, not a desktop browser tab. Layout, safe areas, and connection states need wallet-specific UI patterns.
• Composable features — Payment-gated content, LNURL flows, Nostr feeds, and sat-priced AI chat are common patterns, but each adds dependencies, env vars, and API routes.
• No shared starting point — Without a scaffolder, every team reinvents providers, mocks, and project structure.

The goal was a developer experience comparable to create-next-app or create-t3-app, but tailored to the Fedi and Bitcoin stack.

---

The approach

The project is a Turborepo monorepo with three deliverables:

1. CLI package (apps/cli) — Interactive and non-interactive scaffolding via @clack/prompts, with flags for CI and demo automation.
2. Documentation site (apps/www) — Marketing landing page and Fumadocs reference at create-fedi-app.keeganfrancis.com.
3. Template system (templates/) — A base Next.js 16 scaffold plus pluggable modules merged at generation time.

Every generated project is standalone — no monorepo coupling. Shared packages (@create-fedi-app/webln, @create-fedi-app/nostr, @create-fedi-app/ui) are inlined into the output so developers get a normal npm project they can deploy anywhere.

---

What ships in every scaffold

Three modules are always included:

The base template also includes:

• Fedi-themed UI — shadcn primitives sized for mobile WebView: SatsAmount, ConnectionBadge, MiniAppLayout, safe-area helpers
• Dev toolbar — Toggle mock WebLN and Nostr in development without opening Fedi on every refresh
• Production defaults — App Router, TypeScript strict mode, Tailwind v4, env validation via @t3-oss/env-nextjs

---

Optional modules at scaffold time

Developers pick features during the CLI prompts (or via flags for automation):

• payment-gated-content — Lock content behind a Lightning invoice with HMAC-signed access cookies
• lnurl — LNURL-pay, LNURL-auth, and LNURL-withdraw with callback routes
• ai-chat-gated — Streaming AI chat where each message costs sats via WebLN
• ai-assistant — Free AI assistant via Vercel AI SDK (Anthropic, OpenAI, Groq, or Ollama)
• multispend-demo — Threshold spending UI with Nostr-signed approvals
• nostr-feed — Read, publish, and zap Nostr notes
• database — Drizzle ORM CRUD with Turso or Supabase
• ai-rules — Agent-readable .cursorrules / CLAUDE.md with Fedi API context

Each module is defined by a module.json manifest that declares files to copy, merge strategies, dependencies, env vars, and npm scripts. The CLI resolves dependency chains (e.g. payment-gated content requires webln-payments) and writes a complete .env.example.

---

Technical highlights

Module merge engine — Files can be added, appended, or merged into existing targets (e.g. demo route registry). The scaffold copies the base template, applies selected modules in order, merges package.json dependencies, and generates a demo routes index.

Mock-first development — Mock WebLN and Nostr providers simulate payment success (~600ms delay) and identity signing so UI flows can be built and tested in a normal browser before deploying to Fedi on Mutinynet.

Non-interactive mode — Full flag support (--project-name, --modules, --database, --package-manager) powers GitHub Actions that refresh the public demo repo on every semver tag.

Quality pipeline — Vitest unit tests, Playwright e2e against generated projects, typecheck/lint/build via Turborepo, and automated npm publish on tagged releases.

---

Developer workflow

npx create-fedi-app@latest
cd my-fedi-app && bun install && bun dev

The CLI walks through project name, database adapter (none / Turso / Supabase), optional modules, AI rules, and package manager. Next steps point to local mock testing (/demo/webln), LAN/tunnel testing inside Fedi, and Vercel deployment for catalog submission.

---

Outcomes

• Published npm package with semver releases and automated publishing
• Documentation site with quickstart, module reference, and deployment guide
• Live showcase demo regenerated from pinned scaffold options on each release
• Open-source MIT project with a contributor guide for adding new module templates

create-fedi-app turns Fedi mini app development from a collection of one-off integrations into a repeatable, documented path from npx to production.