Telegram Mini App Dev

Build Telegram Mini Apps without the pain. Includes solutions for safe areas, fullscreen mode, BackButton handlers, sharing with inline mode, position:fixed issues, and React gotchas. Use when building or debugging Telegram Mini Apps, or when encountering issues with WebApp API, safe areas, or sharing.

Security Scan

This is an instruction-only skill with copy-paste React hooks/components and documentation that align with its stated purpose of helping build Telegram Mini Apps; it asks for no credentials or installs and contains no obvious exfiltration or unrelated capabilities.

Purpose & Capability

Name/description match the included files (hooks, components, knowledge base). The referenced APIs (window.Telegram.WebApp, WebApp.shareMessage, bot.savePreparedInlineMessage, R2/CDN, resvg-wasm) are relevant to building Telegram Mini Apps.

Instruction Scope

SKILL.md and code only instruct reading Telegram WebApp state, handling UI issues, preparing inline messages, and server-side image generation patterns. No instructions ask the agent to read unrelated system files, environment variables, or transmit arbitrary data to unknown endpoints.

Install Mechanism

No install spec is provided (instruction-only), so nothing is downloaded or written to disk. References to libraries (e.g., @resvg/resvg-wasm, @telegram-apps/sdk) are typical dependencies for the documented tasks and would be installed by the user if needed.

Credentials

The skill declares no required environment variables or credentials. The documentation correctly separates client-side code from server-side needs (e.g., backend calling bot.savePreparedInlineMessage). No unexpected secret access is requested.

Persistence & Privilege

always is false and the skill is user-invocable; it does not request persistent/system-level privileges or modify other skills' configs. All code is client-side utilities meant to be copy/pasted into projects.

Assessment

This skill appears coherent and safe for its stated purpose: reusable React hooks/components and a knowledge base for Telegram Mini Apps. Before using, ensure you do not copy any server-side bot tokens or other secrets into client code — server-side calls that prepare inline messages must hold bot credentials on the server only. If you implement the suggested server-side image generation (resvg-wasm, R2/CDN), secure those services and credentials appropriately. Review any third-party packages (@telegram-apps/sdk, resvg) you add to your project for supply-chain risk, and verify behavior on actual iOS/Android Telegram clients as recommended in the testing checklist.

Telegram Mini App Development

Battle-tested solutions for common Telegram Mini App issues.

Quick Reference

Safe Area (Fullscreen Mode)

// Use reactive hook - values are async and context-dependent
const safeArea = useSafeAreaInset(); // from references/hooks.ts
<div style={{ paddingTop: safeArea.top }}>Header</div>

position:fixed Broken

Telegram applies transform to container. Use createPortal:

import { createPortal } from 'react-dom';
createPortal(<Modal />, document.body);

BackButton Not Firing

Use @telegram-apps/sdk, not raw WebApp:

import { onBackButtonClick, showBackButton } from '@telegram-apps/sdk';
onBackButtonClick(handleBack);

Sharing with Inline Mode

1. Enable inline mode: @BotFather → /setinline → select bot
2. Backend calls savePreparedInlineMessage → returns prepared_message_id
3. Frontend calls WebApp.shareMessage(prepared_message_id)

Note: prepared_message_id is single-use — prepare fresh for each share tap. For static content, consider caching images on R2/CDN and preparing per-tap.

React "0" Rendering

// WRONG: renders literal "0"
{count && <span>{count}</span>}

// CORRECT
{count > 0 && <span>{count}</span>}

Detailed Guides

• references/KNOWLEDGE.md — Full knowledge base with all gotchas and solutions
• references/hooks.ts — Copy-paste React hooks (useSafeAreaInset, useFullscreen, etc.)
• references/components.tsx — Ready-to-use components (SafeAreaHeader, DebugOverlay)

Testing Checklist

Before shipping, test:

• Open from folder (chat list)
• Open from direct bot chat
• iOS device
• Android device
• Share flow (tap → dismiss → tap again)
• Share to different chat types (user, group, channel)
• Back button
• Scroll with sticky header