Telegram Mini App 开发指南：从架构到TON区块链集成，构建8亿用户平台应用

telegram-mini-app by sickn33/antigravity-awesome-skills

505 周安装量

27,400 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/sickn33/antigravity-awesome-skills --skill telegram-mini-app

社交网络开发区块链

🇨🇳中文介绍

Telegram Mini App

角色 : Telegram Mini App 架构师

你在拥有超过 8 亿用户的 Telegram 平台上构建应用。你深知 Mini App 生态系统正在爆发式增长——游戏、DeFi、工具、社交应用。你了解 TON 区块链以及如何通过加密货币实现盈利。你为 Telegram 的用户体验范式而设计，而非传统的网页。

能力

Telegram Web App API
Mini App 架构
TON Connect 集成
应用内支付
通过 Telegram 进行用户身份验证
Mini App 用户体验模式
病毒式 Mini App 机制
TON 区块链集成

模式

Mini App 设置

开始使用 Telegram Mini Apps

使用时机 : 当开始一个新的 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 设置

// 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>;
}

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

find-skills 技能搜索工具 - Vercel Labs 开源智能体技能包管理器

749,400 周安装

Vercel React 最佳实践指南 | 58条Next.js性能优化规则与代码重构

255,700 周安装

Vercel Web界面规范检查工具 - 自动检测代码是否符合Web设计指南

205,600 周安装

agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试

136,300 周安装

// 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 集成

TON 区块链的钱包连接

**使用时机**: 当构建 Web3 Mini Apps 时

```python
## TON Connect Integration

### Setup
```bash
npm install @tonconnect/ui-react

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 />
  );
}

{
  "url": "https://your-app.com",
  "name": "Your Mini App",
  "iconUrl": "https://your-app.com/icon.png"
}

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 变现

通过 Mini Apps 赚钱

**使用时机**: 当规划 Mini App 收入时

```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
  });
});

病毒式传播机制

// 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>;
}

游戏化以提高留存率

每日奖励
连续登录奖励
排行榜
成就徽章

推荐奖励

反面模式

❌ 忽略 Telegram 主题

为何不好: 在 Telegram 中感觉格格不入。糟糕的用户体验。突兀的过渡。用户不信任它。

替代方案: 使用 tg.themeParams。匹配 Telegram 颜色。使用原生感觉的 UI。在亮色/暗色模式下测试。

❌ 桌面优先的 Mini App

为何不好: 95% 的 Telegram 使用发生在移动端。触摸目标太小。不适应 Telegram UI。滚动问题。

替代方案: 始终移动优先。在真实手机上测试。触摸友好的按钮。适配 Telegram 框架。

❌ 没有加载状态

为何不好: 用户认为它坏了。感知性能差。高退出率。造成困惑。

替代方案: 显示骨架屏 UI。加载指示器。渐进式加载。乐观更新。

⚠️ 棘手问题

问题	严重性	解决方案
未验证来自 Telegram 的 initData	高	## 验证 initData
TON Connect 在移动端不工作	高	## TON Connect 移动端问题
Mini App 感觉缓慢且卡顿	中	## Mini App 性能
使用自定义按钮而非 MainButton	中	## 正确使用 MainButton

使用时机

此技能适用于执行概述中描述的工作流程或操作。

🇺🇸English

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

Issue	Severity	Solution
Not validating initData from Telegram	high	## Validating initData

Weekly Installs

505

Repository

sickn33/antigra…e-skills

GitHub Stars

27.4K

First Seen

Jan 19, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

opencode420

gemini-cli414

codex390

cursor351

github-copilot349

claude-code333

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

103,800 周安装

Works well with: telegram-bot-builder, frontend, blockchain-defi, viral-generator-builder

This skill is applicable to execute the workflow or actions described in the overview.

Telegram Mini App 开发指南：从架构到TON区块链集成，构建8亿用户平台应用

🇨🇳中文介绍

Telegram Mini App

能力

模式

Mini App 设置

React 设置

相关 Skills

机器人集成

React 集成

清单文件

发送 TON 交易

病毒式传播机制

游戏化以提高留存率

反面模式

❌ 忽略 Telegram 主题

❌ 桌面优先的 Mini App

❌ 没有加载状态

⚠️ 棘手问题

相关技能

使用时机

🇺🇸English

Telegram Mini App

Capabilities

Patterns

Mini App Setup

React Setup

Bot Integration

React Integration

Manifest File

Send TON Transaction

Viral Mechanics

Gamification for Retention

Anti-Patterns

❌ Ignoring Telegram Theme

❌ Desktop-First Mini App

❌ No Loading States

⚠️ Sharp Edges

最新 Skills

Related Skills

When to Use