DEV Community

Cover image for 🚀 TMA DevKit v2: Local Emulator for Telegram Mini Apps + MCP AI Debugging
Ivan Shevtsov
Ivan Shevtsov

Posted on

🚀 TMA DevKit v2: Local Emulator for Telegram Mini Apps + MCP AI Debugging

#ai #webdev #telegram #opensource

😤 The Problem That Drives Everyone Crazy

Ever tried building a Telegram Mini App?

    Write your code.

    Spin up ngrok (and pray it doesn't crash).

    Go to @BotFather, paste the tunnel URL.

    Grab your phone, open the bot, type console.log() — and pray again.

    Repeat for every theme, platform, and user type you need to test.
Enter fullscreen mode Exit fullscreen mode

It's 2015, folks. And there's still no official emulator.

"The main difficulty is the inability to run a project as easily as in a browser via localhost — and the absence of a developer console."
— Habr, March 2025
Enter fullscreen mode Exit fullscreen mode

💡 Introducing: TMA DevKit

A local emulator and bridge inspector for Telegram Mini Apps. Think Redux DevTools, but for window.Telegram.WebApp.

In one sentence: paste your Mini App URL into the panel, and it runs inside an iframe with a full emulation of the Telegram client — no phone, no ngrok, no BotFather.
✨ What DevKit v2 Can Do (and Why It's Awesome)
🧠 MCP Server for AI-Powered Debugging — Brand New!

Connect any AI assistant (Claude, GPT, local models) via the Model Context Protocol. Ask questions about your app's state, event flow, or initData validation — and get instant debugging suggestions.
🔧 A Real Mock, Not a Stub

Full window.Telegram.WebApp API surface (all methods, properties, events).

Cryptographically valid initData generation with HMAC-SHA-256 signature using your bot token.

Backend validation passes as in production.

Compatible with @telegram-apps/sdk v3 out of the box.
Enter fullscreen mode Exit fullscreen mode

⚡ 5 One‑Click Quick Scenarios
Scenario Description
iOS Premium iPhone user with Premium subscription
Android Free Regular Android user
New User With referral parameter
Group Launch Emulates opening from a group chat
Desktop Wide viewport on computer

Switch contexts in seconds — no manual input.
📊 Bridge Event Inspector

All web_app_* calls displayed in real time.

Group by type, filter, pause, export logs as .txt.

emit console to fire client → app events (theme_changed, main_button_pressed, etc.).
Enter fullscreen mode Exit fullscreen mode

☁️ CloudStorage Editor

Visual key‑value editor. No more guessing what's stored or messing with localStorage manually.
💾 Saved Presets

Save your current config (platform, user, theme, viewport, bot token) as a named preset. Switch between them in one click — persists across sessions.
🖥️ Polished Panel UX

Resizable panels (like VS Code).

Zoomable device stage (25%–200%).

Mobile notch and desktop traffic lights react to platform selection.

Import/export config as JSON.
Enter fullscreen mode Exit fullscreen mode

🧰 Tech Stack
Component Technology
Frontend React 19, TypeScript, Vite
Styling Tailwind CSS, shadcn/ui
Mock Script ~90 KB of vanilla JS, zero dependencies
Testing 22+ Vitest tests (base64url, config, protocol, events)
License MIT
🎯 What's Next?

The project is under active development. Planned:

More scenario presets.

Enhanced MCP integration with pre‑built prompts.

VS Code plugin.
Enter fullscreen mode Exit fullscreen mode

🔗 Links

GitHub: github.com/Deus-org/tma-devkit

Live Demo (if available) — add your link or a screenshot.
Enter fullscreen mode Exit fullscreen mode

👋 Call to Action

If you've ever built a TMA, I'd really appreciate:

Feedback on the README (is it clear?).

Feature suggestions.

Bug reports (open an issue on GitHub).
Enter fullscreen mode Exit fullscreen mode

⭐️ Star the repo if you find it useful — it helps a ton!

Built by a developer who got tired of debugging on a phone.
Let's make TMA development better together! 🚀

Top comments (2)

Collapse
 
fern_eterna profile image
Bartek Bilicki •

Local emulator + signed initData is the missing piece for Mini App teams who were stuck bouncing between ngrok and a physical phone. HMAC validation against the real bot token before you ship is the right default.\n\nThe MCP debugging bridge is clever too: being able to ask an agent about event flow and WebApp state beats sprinkling console.logs inside Telegram.\n\nIf you are past the emulator and want a place for builders to list live Mini Apps / bots, tg.app is a public catalog, and Apps Father (@apps_father_bot) helps when someone needs a no-code first cut with Stars payments. How are you handling scenario presets for payment flows?

Collapse
 
dl1ar profile image
Ivan Shevtsov •

Thanks for the thoughtful feedback! Really glad the emulator + HMAC approach resonates — that was exactly the pain point we started from. 🙌

Quick clarification on the payment question, since it's a good one:

DevKit doesn't treat payment flows as a special case — because payments are part of the standard WebApp contract. The Mock implements WebApp.openInvoice() against Telegram's real spec (URL validation, slug parsing, web_app_open_invoice bridging), and the outcome is driven by the exact same client→app event a real Telegram client fires: invoice_closed.

So testing a Stars checkout flow is a two-step routine, like any other bridge interaction:

  1. The app calls openInvoice(url, cb) → you see web_app_open_invoice in the event inspector.
  2. You fire invoice_closed with {"slug": "...", "status": "paid"} from the panel's Emit console (or via MCP devkit_emit) → the callback receives the status and your app reacts — invoiceClosed handler, UI state, everything.

The backend part you validate exactly like production: the bot gets the charge webhook, and your server can cross-check it against initData's HMAC. Nothing to emulate there.

Why no dedicated "payment presets"? Because scenario presets are about environment (platform, user tier, theme, viewport, locale) — things that change how window.Telegram.WebApp is built at load. A checkout flow is behaviour, and behaviour is exercised through the bridge the same way for every feature: mock + events + inspector. Wrapping "payment: paid / failed / cancelled" into a preset would just be a cosmetic shortcut over the Emit console we already expose — no new capability.

That said, if you're past the emulator, tg.app sounds like a neat place for builders to list live Mini Apps — happy to chat if you ever want DevKit to hand off from emulated checkout to real Stars validation. Good luck with the catalog and @apps_father_bot! 🚀