Introduction
# Telegram Mini App Development
Battle-tested solutions for common Telegram Mini App issues.
## Quick Reference
### Safe Area (Fullscreen Mode) ```typescript // 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`: ```tsx import { createPortal } from 'react-dom'; createPortal(<Modal />, document.body); ```
### BackButton Not Firing Use `@telegram-apps/sdk`, not raw WebApp: ```typescript 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 ```tsx // WRONG: renders literal "0" {count && <span>{count}</span>}
// CORRECT {count > 0 && <span>{count}</span>} ```
## Detailed Guides
- **[references/KNOWLEDGE.md](references/KNOWLEDGE.md)** — Full knowledge base with all gotchas and solutions - **[references/hooks.ts](references/hooks.ts)** — Copy-paste React hooks (useSafeAreaInset, useFullscreen, etc.) - **[references/components.tsx](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