17 interactive demos · 50+ production-ready code snippets · Full TypeScript support
Building a Telegram Mini App shouldn't mean guessing how APIs work. This dev kit gives you a live, interactive reference for every Telegram WebApp API — from haptic feedback and biometric auth to Star payments and sensor access.
Whether you're building a Telegram bot, a Web3 dApp on TON, a clicker game, or a full-stack SaaS inside Telegram, this project shows you exactly how every feature works with copy-paste TypeScript code.
Perfect for:
- Developers building their first Telegram Mini App
- Teams evaluating Telegram as a distribution platform
- Hackathon participants who need working examples fast
- Anyone who learns best by reading real, working code
- Next.js 16 App Router — latest React Server Components architecture
- Full TypeScript — complete type definitions for the entire Telegram WebApp API
- Tailwind CSS 4 — utility-first styling with Telegram theme integration
- Zustand state management — lightweight, scalable global state
- Framer Motion animations — smooth, performant UI transitions
- Prism syntax highlighting — beautiful code blocks with copy-to-clipboard
- Hot module replacement — instant feedback during development
| Category | Features |
|---|---|
| Authentication | Init data validation, HMAC-SHA256 verification, user identity |
| UI Controls | Main Button, Secondary Button, Back Button, Settings Button |
| Payments | Telegram Stars (XTR), invoices, refunds, webhooks |
| Biometrics | Face ID, Touch ID, fingerprint authentication |
| Sensors | Accelerometer, gyroscope, device orientation, GPS location |
| Storage | Cloud Storage (cross-device sync), key-value persistence |
| Haptics | Impact feedback (5 styles), notification feedback (3 types) |
| Media | QR code scanner, file downloads, camera/microphone permissions |
| Sharing | Story sharing with widgets, inline queries, URL sharing |
| Theming | Dynamic header/background/bottom bar colors, dark mode |
| Game APIs | Fullscreen, orientation lock, vertical swipe control |
| Platform | Home screen install, emoji status, version detection |
Every demo is interactive — open the app in Telegram, tap a button, and see the API in action.
| # | Demo | Description |
|---|---|---|
| 1 | Init Data | Validate Telegram authentication with HMAC-SHA256 |
| 2 | Core API | Platform info, fullscreen, theme, clipboard, permissions |
| 3 | Buttons | Main, Secondary, Back, and Settings button management |
| 4 | Links | External links, Telegram deep links, Instant View, browser selection |
| 5 | Popups | Alerts, confirms, multi-button popups, safe nesting patterns |
| 6 | QR Scanner | Scan and parse URLs, contacts, WiFi, game codes |
| 7 | Storage | Cloud Storage CRUD with game save/load example |
| 8 | Haptics | All impact and notification feedback types with patterns |
| 9 | Sensors | Accelerometer, gyroscope, device orientation, GPS |
| 10 | Biometrics | Face ID / fingerprint auth flow with token management |
| 11 | Share Story | Share images/videos to Telegram Stories with widget links |
| 12 | Home Screen | Add-to-home-screen prompt with status checking |
| 13 | Emoji Status | Set custom emoji status with duration control |
| 14 | File Downloads | Trigger native file downloads (images, videos, PDFs) |
| 15 | Activity | Track app activate/deactivate lifecycle events |
| 16 | Game Features | Fullscreen, orientation lock, swipe control + tap game |
| 17 | Payments | Complete Telegram Stars payment flow with backend examples |
- Node.js 18+
- npm or yarn
- A Telegram account
- ngrok (free) for HTTPS tunneling during development
git clone https://github.com/nikandr-surkov/telegram-mini-app-dev-kit.git
cd telegram-mini-app-dev-kit
npm install- Open @BotFather in Telegram
- Send
/newbotand follow the prompts - Save your bot token
cp .env.example .env.local# .env.local
TELEGRAM_BOT_TOKEN=your_bot_token_herenpm run devTelegram requires HTTPS. In a separate terminal:
ngrok http 3000Copy the https:// URL from ngrok output.
- Go to @BotFather →
/mybots→ your bot - Bot Settings → Menu Button → Edit Menu Button
- Paste your ngrok HTTPS URL
- Open your bot in Telegram and tap the Menu button
├── app/
│ ├── api/telegram/validate/ # Init data validation endpoint
│ ├── globals.css # Telegram theme-aware styles
│ ├── layout.tsx # Root layout with WebApp script
│ └── page.tsx # Main app with tab navigation
├── components/
│ ├── demos/ # 17 interactive demo components
│ │ ├── InitDataDemo.tsx # Authentication & validation
│ │ ├── CoreApiDemo.tsx # Platform APIs & theming
│ │ ├── PaymentsDemo.tsx # Telegram Stars integration
│ │ ├── BiometricsDemo.tsx # Face ID / fingerprint auth
│ │ ├── SensorsDemo.tsx # Accelerometer, gyroscope, GPS
│ │ └── ... # 12 more demos
│ ├── CodeBlock.tsx # Syntax-highlighted code display
│ ├── ColorPicker.tsx # Theme color picker component
│ ├── DemoSection.tsx # Reusable demo layout wrapper
│ └── NavigationTabs.tsx # Horizontal scrollable tabs
├── hooks/
│ ├── useCloudStorage.ts # Async Cloud Storage wrapper
│ └── useHaptic.ts # Haptic feedback helper hook
├── providers/
│ └── TelegramProvider.tsx # React context for WebApp API
├── store/
│ └── telegram.ts # Zustand global state
├── types/
│ └── telegram.d.ts # Complete WebApp type definitions
└── utils/
└── telegram.ts # Validation & platform helpers
Every Telegram Mini App should validate init data on the backend. This project includes a working example:
// app/api/telegram/validate/route.ts
import { validate, parse } from '@telegram-apps/init-data-node'
export async function POST(request: NextRequest) {
const { initData } = await request.json()
validate(initData, process.env.TELEGRAM_BOT_TOKEN!)
const data = parse(initData)
return NextResponse.json({ valid: true, user: data.user })
}The @telegram-apps/init-data-node package handles HMAC-SHA256 signature verification against your bot token.
The Payments demo includes complete frontend and backend code for:
- Creating invoices via the Bot API
- Opening the native payment UI with
webApp.openInvoice() - Handling
pre_checkout_queryandsuccessful_paymentwebhooks - Processing refunds via
refundStarPayment - Testing strategies with minimal cost
All digital goods in Telegram Mini Apps must use Telegram Stars (XTR currency) per App Store and Play Store policies.
# Install Vercel CLI
npm i -g vercel
# Deploy
vercelOr connect your GitHub repo to vercel.com for automatic deployments on every push.
Set TELEGRAM_BOT_TOKEN in your Vercel project's environment variables.
After deploying, update your bot's Menu Button URL in BotFather to your production domain.
This is a standard Next.js 16 app — deploy anywhere that supports Node.js:
- Railway —
railway up - Render — connect GitHub repo
- Fly.io —
fly launch - Docker —
next build && next start - AWS Amplify, Google Cloud Run, Azure App Service
| Technology | Purpose |
|---|---|
| Next.js 16 | React framework with App Router |
| React 19 | UI library |
| TypeScript 5 | Type safety |
| Tailwind CSS 4 | Utility-first CSS |
| Zustand | Lightweight state management |
| Framer Motion | Animation library |
| Prism React Renderer | Syntax highlighting |
| react-qr-code | QR code generation |
| @telegram-apps/init-data-node | Server-side init data validation |
Contributions are welcome! Here's how you can help:
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Commit your changes:
git commit -m 'Add amazing feature' - Push to the branch:
git push origin feature/amazing-feature - Open a Pull Request
- Add new demo components for upcoming Telegram APIs
- Improve TypeScript type definitions
- Add unit tests with Vitest or Jest
- Create a dark/light theme toggle for the code blocks
- Add internationalization (i18n) support
- Write tutorials or blog posts about specific features
- Improve accessibility (a11y)
- Add E2E tests with Playwright
Telegram Documentation:
- Telegram Mini Apps Documentation
- Telegram Bot API
- Telegram Stars Payments
- @BotFather — create and manage bots
Community & Learning:
- 🌐 nikandr.com — tutorials and courses
- 📺 YouTube @NikandrSurkov — video guides
- 💬 Telegram @NikandrApps — community channel
- 💻 GitHub @nikandr-surkov — open source projects
Mini App not opening?
- Verify ngrok is running and the HTTPS URL is correct
- Check your bot token in
.env.local - Make sure you set the Menu Button URL in BotFather (not just the bot description)
"WebApp is not defined" error?
- The app must be opened through Telegram, not a regular browser
- The
telegram-web-app.jsscript loads only inside the Telegram client
Features not working?
- Some APIs require specific Telegram client versions (check the Version Check demo)
- Sensors require physical device — they won't work in Telegram Desktop
- Biometrics require device hardware support (Face ID, fingerprint scanner)
Payment invoice not opening?
- Ensure
provider_tokenis empty string""for Stars payments - Currency must be
"XTR"for Telegram Stars - Bot must have payment capability (check with BotFather)
This project is licensed under the MIT License — see the LICENSE file for details.
You are free to use, modify, and distribute this code in personal and commercial projects.
If this project helped you build your Telegram Mini App, please give it a ⭐ on GitHub — it helps other developers discover it!
Built by Nikandr Surkov