Telegram Mini App开发指南：集成TON区块链、Web App API与React框架构建应用

telegram-mini-app by davila7/claude-code-templates

229 周安装量

24,100 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/davila7/claude-code-templates --skill telegram-mini-app

社交网络区块链 Web应用

🇨🇳中文介绍

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 设置

### 基本结构
```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();

    // 用户数据
    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>你好，{user?.first_name}</div>;
}

广告位招租

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

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

联系我们

相关 Skills

浏览器自动化策略指南：何时及如何使用实时浏览器会话进行网页调试与研究

39,100 周安装

Grimoire Polymarket 技能：Polymarket 市场发现、CLOB 数据与订单管理 CLI 工具

11,400 周安装

FluxA Agent Wallet：AI代理安全支付钱包，支持USDC转账与x402支付

7,800 周安装

Solidity 智能合约安全指南：防范重入攻击、溢出漏洞与访问控制

7,800 周安装

// Bot 发送 Mini App
bot.command('app', (ctx) => {
  ctx.reply('打开应用：', {
    reply_markup: {
      inline_keyboard: [[
        { text: '🚀 打开应用', web_app: { url: 'https://your-app.com' } }
      ]]
    }
  });
});


### TON Connect 集成

用于 TON 区块链的钱包连接

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

```python
## TON Connect 集成

### 设置
```bash
npm install @tonconnect/ui-react

import { TonConnectUIProvider, TonConnectButton } from '@tonconnect/ui-react';

// 包装应用
function App() {
  return (
    <TonConnectUIProvider manifestUrl="https://your-app.com/tonconnect-manifest.json">
      <MainApp />
    </TonConnectUIProvider>
  );
}

// 在组件中使用
function WalletSection() {
  return (
    <TonConnectButton />
  );
}

{
  "url": "https://your-app.com",
  "name": "你的 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 转换为纳吨
      }]
    };

    await tonConnectUI.sendTransaction(transaction);
  };

  return <button onClick={handlePay}>支付 {amount} TON</button>;
}


### Mini App 盈利模式

通过 Mini Apps 赚钱

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

```javascript
## Mini App 盈利模式

### 收入来源
| 模式 | 示例 | 潜力 |
|-------|---------|-----------|
| TON 支付 | 高级功能 | 高 |
| 应用内购买 | 虚拟商品 | 高 |
| 广告 (Telegram Ads) | 展示广告 | 中 |
| 推荐 | 分享赚取 | 中 |
| NFT 销售 | 数字收藏品 | 高 |

### Telegram Stars (新功能！)
```javascript
// 在你的机器人中
bot.command('premium', (ctx) => {
  ctx.replyWithInvoice({
    title: '高级访问权限',
    description: '解锁所有功能',
    payload: 'premium',
    provider_token: '', // 对于 Stars 留空
    currency: 'XTR', // Telegram Stars
    prices: [{ label: '高级版', amount: 100 }], // 100 Stars
  });
});

病毒式传播机制

// 推荐系统
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=看看这个！`
    );
  };

  return <button onClick={share}>邀请朋友 (+10 金币)</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

183

Repository

davila7/claude-…emplates

GitHub Stars

23.4K

First Seen

Jan 25, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

opencode164

gemini-cli158

codex152

cursor150

github-copilot147

claude-code126

Solana开发技能指南：dApp开发、钱包连接、交易构建、链上程序与安全审计

4,500 周安装

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

Telegram Mini App开发指南：集成TON区块链、Web App API与React框架构建应用

🇨🇳中文介绍

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