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

Ivan Shevtsov — Sat, 01 Aug 2026 21:02:41 +0000

😤 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.

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

💡 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.

⚡ 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.).

☁️ 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.

🧰 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.

🔗 Links

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

Live Demo (if available) — add your link or a screenshot.

👋 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).

⭐️ 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! 🚀

I Built a DevTools for Telegram Mini Apps So You Don't Have to Debug on Your Phone

Ivan Shevtsov — Sat, 25 Jul 2026 22:09:09 +0000

While building a Telegram Mini App recently, I hit the same wall every TMA developer knows:

Code your app locally.
Spin up ngrok (hope it doesn't crash).
Go to @botfather, set the web_app URL to the tunnel.
Grab your phone, launch the app, console.log() and pray.
Repeat for every theme / platform / user combination you need to test.

There's no official Telegram Mini Apps emulator. The workflow is stuck in 2015. Developers in the Russian TMA community have been complaining about it publicly:

"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

So I built TMA DevKit — an open-source local emulator and bridge inspector for Telegram Mini Apps. Think Redux DevTools, but for window.Telegram.WebApp.

How it works (one sentence): you paste your Mini App URL into a local panel, and it runs inside an iframe against a faithful mock of the Telegram client — no phone, no ngrok, no BotFather.

What it gives you:

🔧 Real mock, not a stub. Full window.Telegram.WebApp API surface with cryptographically valid initData (HMAC-SHA-256 signed against your dev bot token). Backend validation passes. Compatible with @telegram-apps/sdk v3 out of the box.

⚡ 5 one-click Quick Scenarios. Premium iOS user → Free Android user → New user with referral param → Group chat launch → Desktop wide viewport. Switch contexts without touching a single input field.

📊 Bridge event inspector. Every web_app_* call appears in real-time. Group by event type, filter, pause, export logs as .txt. Plus an emit console to fire client→app events (theme_changed, main_button_pressed, etc.) back into your app.

☁️ CloudStorage editor. Visual key-value editor — no more guessing what's stored or manually manipulating localStorage.

💾 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.

🖥️ Panel UX. Drag-resize panels (like VS Code), zoomable device stage (25%–200%), mobile notch and desktop traffic lights that react to your platform selection. Import/export config as JSON.

Stack: React 19, TypeScript, Vite, Tailwind CSS, shadcn/ui. Mock script is ~90 KB of zero-dependency vanilla JS.

Testing: 22 Vitest tests covering the base64url codec, config model, wire protocol, and bridge message discrimination.

MIT licensed. Would love some honest feedback — and stars if you find it useful ⭐

🔗 github.com/Deus-org/tma-devkit

DEV Community: Ivan Shevtsov

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

I Built a DevTools for Telegram Mini Apps So You Don't Have to Debug on Your Phone