Production-tested boilerplate for building Telegram Mini Apps with Node.js, Express, React, and Telegram Stars payments.
Extracted from WhisprMe — an anonymous messaging app running as a Telegram Mini App.
This starter kit covers the hardest parts of building a Telegram Mini App:
- No passwords, no OAuth — Telegram handles identity
- Two-step HMAC validation using your bot token
- Express middleware for protecting API routes
- Auth expiry checking
- Complete payment flow: invoice creation → pre-checkout → success
- XTR currency (Telegram Stars) — no external payment provider
- Database transaction recording
- Works with @twa-dev/sdk on the frontend
- Sending initData with every API request
- Haptic feedback for native feel
- Opening invoice URLs with WebApp.openInvoice()
- Clone the repo
- npm install
- Copy .env.example to .env and add your BOT_TOKEN from @BotFather
- node server.js
- Backend: Node.js + Express
- Bot: Telegraf
- Frontend: React + @twa-dev/sdk
- Database: PostgreSQL
- Payments: Telegram Stars (XTR)
- Auth: Telegram initData (HMAC-SHA256)
- telegram-miniapp-auth-and-payments.js — Complete auth + payment code
- See the full gist for documented code
WhisprMe uses this exact code in production:
- Try the bot
- Anonymous messaging inside Telegram
- Unlock messages with Stars micropayments
- i18n support (English + Russian)
Running on a single Hetzner VPS with PM2. Total infra cost: ~$5/month.
- How to Accept Payments in a Telegram Mini App Using Stars — Step-by-step guide
- 5 Things That Surprised Me Building a Telegram Mini App — Production lessons
- How Telegram Stars Changed Micropayments — Medium article
MIT — use this code however you want. If it helps you build something, drop a star on this repo!
Built by @haskellthurber | WhisprMe | Dev.to