telegram-mini-app
BeliebtExpert in building Telegram Mini Apps (TWA) - web apps that run inside Telegram with native-like experience. Covers the TON ecosystem, Telegram Web App API, payments, user authentication, and building viral mini apps that monetize. Use when: telegram mini app, TWA, telegram web app, TON app, mini app.
"Expert in building Telegram Mini Apps (TWA) - web apps that run inside Telegram with native-like experience. Covers the TON ecosystem, Telegram Web App API, payments, user authentication, and building viral mini apps that monetize. Use when: telegram mini app, TWA, telegram web app, TON app, mini app."
Telegram Mini App
Role: Telegram Mini App Architect
You build apps where 800M+ Telegram users already are. You understand
the Mini App ecosystem is exploding - games, DeFi, utilities, social
apps. You know TON blockchain and how to monetize with crypto. You
design for the Telegram UX paradigm, not traditional web.
Capabilities
- Telegram Web App API
- Mini App architecture
- TON Connect integration
- In-app payments
- User authentication via Telegram
- Mini App UX patterns
- Viral Mini App mechanics
- TON blockchain integration
Patterns
Mini App Setup
Getting started with Telegram Mini Apps
When to use: When starting a new Mini App
## Mini App Setup
### Basic Structure
```html
<!DOCTYPE html>
<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<script src="https://telegram.org/js/telegram-web-app.js"></script>
</head>
<body>
<script>
const tg = window.Telegram.WebApp;
tg.ready();
tg.expand();
// User data
const user = tg.initDataUnsafe.user;
console.log(user.first_name, user.id);
</script>
</body>
</html>
React Setup
// hooks/useTelegram.js
export function useTelegram() {
const tg = window.Telegram?.WebApp;
return {
tg,
user: tg?.initDataUnsafe?.user,
queryId: tg?.initDataUnsafe?.query_id,
expand: () => tg?.expand(),
close: () => tg?.close(),
ready: () => tg?.ready(),
};
}
// App.jsx
function App() {
const { tg, user, expand, ready } = useTelegram();
useEffect(() => {
ready();
expand();
}, []);
return <div>Hello, {user?.first_name}</div>;
}
Bot Integration
// Bot sends Mini App
bot.command('app', (ctx) => {
ctx.reply('Open the app:', {
reply_markup: {
inline_keyboard: [[
{ text: '🚀 Open App', web_app: { url: 'https://your-app.com' } }
]]
}
});
});
### TON Connect Integration
Wallet connection for TON blockchain
**When to use**: When building Web3 Mini Apps
```python
## TON Connect Integration
### Setup
```bash
npm install @tonconnect/ui-react
React Integration
import { TonConnectUIProvider, TonConnectButton } from '@tonconnect/ui-react';
// Wrap app
function App() {
return (
<TonConnectUIProvider manifestUrl="https://your-app.com/tonconnect-manifest.json">
<MainApp />
</TonConnectUIProvider>
);
}
// Use in components
function WalletSection() {
return (
<TonConnectButton />
);
}
Manifest File
{
"url": "https://your-app.com",
"name": "Your Mini App",
"iconUrl": "https://your-app.com/icon.png"
}
Send TON Transaction
import { useTonConnectUI } from '@tonconnect/ui-react';
function PaymentButton({ amount, to }) {
const [tonConnectUI] = useTonConnectUI();
const handlePay = async () => {
const transaction = {
validUntil: Math.floor(Date.now() / 1000) + 60,
messages: [{
address: to,
amount: (amount * 1e9).toString(), // TON to nanoton
}]
};
await tonConnectUI.sendTransaction(transaction);
};
return <button onClick={handlePay}>Pay {amount} TON</button>;
}
### Mini App Monetization
Making money from Mini Apps
**When to use**: When planning Mini App revenue
```javascript
## Mini App Monetization
### Revenue Streams
| Model | Example | Potential |
|-------|---------|-----------|
| TON payments | Premium features | High |
| In-app purchases | Virtual goods | High |
| Ads (Telegram Ads) | Display ads | Medium |
| Referral | Share to earn | Medium |
| NFT sales | Digital collectibles | High |
### Telegram Stars (New!)
```javascript
// In your bot
bot.command('premium', (ctx) => {
ctx.replyWithInvoice({
title: 'Premium Access',
description: 'Unlock all features',
payload: 'premium',
provider_token: '', // Empty for Stars
currency: 'XTR', // Telegram Stars
prices: [{ label: 'Premium', amount: 100 }], // 100 Stars
});
});
Viral Mechanics
// Referral system
function ReferralShare() {
const { tg, user } = useTelegram();
const referralLink = `https://t.me/your_bot?start=ref_${user.id}`;
const share = () => {
tg.openTelegramLink(
`https://t.me/share/url?url=${encodeURIComponent(referralLink)}&text=Check this out!`
);
};
return <button onClick={share}>Invite Friends (+10 coins)</button>;
}
Gamification for Retention
- Daily rewards
- Streak bonuses
- Leaderboards
- Achievement badges
- Referral bonuses
## Anti-Patterns
### ❌ Ignoring Telegram Theme
**Why bad**: Feels foreign in Telegram.
Bad user experience.
Jarring transitions.
Users don't trust it.
**Instead**: Use tg.themeParams.
Match Telegram colors.
Use native-feeling UI.
Test in both light/dark.
### ❌ Desktop-First Mini App
**Why bad**: 95% of Telegram is mobile.
Touch targets too small.
Doesn't fit in Telegram UI.
Scrolling issues.
**Instead**: Mobile-first always.
Test on real phones.
Touch-friendly buttons.
Fit within Telegram frame.
### ❌ No Loading States
**Why bad**: Users think it's broken.
Poor perceived performance.
High exit rate.
Confusion.
**Instead**: Show skeleton UI.
Loading indicators.
Progressive loading.
Optimistic updates.
## ⚠️ Sharp Edges
| Issue | Severity | Solution |
|-------|----------|----------|
| Not validating initData from Telegram | high | ## Validating initData |
| TON Connect not working on mobile | high | ## TON Connect Mobile Issues |
| Mini App feels slow and janky | medium | ## Mini App Performance |
| Custom buttons instead of MainButton | medium | ## Using MainButton Properly |
## Related Skills
Works well with: `telegram-bot-builder`, `frontend`, `blockchain-defi`, `viral-generator-builder`You Might Also Like
Related Skills
cache-components
Expert guidance for Next.js Cache Components and Partial Prerendering (PPR). **PROACTIVE ACTIVATION**: Use this skill automatically when working in Next.js projects that have `cacheComponents: true` in their next.config.ts/next.config.js. When this config is detected, proactively apply Cache Components patterns and best practices to all React Server Component implementations. **DETECTION**: At the start of a session in a Next.js project, check for `cacheComponents: true` in next.config. If enabled, this skill's patterns should guide all component authoring, data fetching, and caching decisions. **USE CASES**: Implementing 'use cache' directive, configuring cache lifetimes with cacheLife(), tagging cached data with cacheTag(), invalidating caches with updateTag()/revalidateTag(), optimizing static vs dynamic content boundaries, debugging cache issues, and reviewing Cache Component implementations.
vercel
component-refactoring
Refactor high-complexity React components in Dify frontend. Use when `pnpm analyze-component --json` shows complexity > 50 or lineCount > 300, when the user asks for code splitting, hook extraction, or complexity reduction, or when `pnpm analyze-component` warns to refactor before testing; avoid for simple/well-structured components, third-party wrappers, or when the user explicitly wants testing without refactoring.
langgenius
web-artifacts-builder
Suite of tools for creating elaborate, multi-component claude.ai HTML artifacts using modern frontend web technologies (React, Tailwind CSS, shadcn/ui). Use for complex artifacts requiring state management, routing, or shadcn/ui components - not for simple single-file HTML/JSX artifacts.
anthropicsfrontend-design
Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics.
anthropics
react-modernization
Upgrade React applications to latest versions, migrate from class components to hooks, and adopt concurrent features. Use when modernizing React codebases, migrating to React Hooks, or upgrading to latest React versions.
wshobsontailwind-design-system
Build scalable design systems with Tailwind CSS v4, design tokens, component libraries, and responsive patterns. Use when creating component libraries, implementing design systems, or standardizing UI patterns.
wshobson