67 lines
2.2 KiB
Markdown
67 lines
2.2 KiB
Markdown
---
|
|
name: tg-miniapp
|
|
description: 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.
|
|
---
|
|
|
|
# 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
|