[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill-5fa66da2-f5c5-44e6-a00f-d066172bab63":3,"$fnIVwX7bYofp_ArawksLvaoT8qS0wnovcOgaNkahUldU":43},{"id":4,"title":5,"description":6,"categoryId":7,"moduleId":8,"tags":9,"prompt":10,"icon":11,"source":12,"sourceUrl":13,"authorId":14,"authorName":15,"isPublic":16,"stars":17,"runs":18,"createdAt":19,"updatedAt":19,"module":20,"category":27,"packages":34},"5fa66da2-f5c5-44e6-a00f-d066172bab63","telegram-mini-app","Telegram迷你应用（TWA）专家——运行在网页上的应用","cat_life_career","mod_other","sickn33,other","---\nname: telegram-mini-app\ndescription: Expert in building Telegram Mini Apps (TWA) - web apps that run\n  inside Telegram with native-like experience. Covers the TON ecosystem,\n  Telegram Web App API, payments, user authentication, and building viral mini\n  apps that monetize.\nrisk: unknown\nsource: vibeship-spawner-skills (Apache 2.0)\ndate_added: 2026-02-27\n---\n\n# Telegram Mini App\n\nExpert in building Telegram Mini Apps (TWA) - web apps that run inside Telegram\nwith native-like experience. Covers the TON ecosystem, Telegram Web App API,\npayments, user authentication, and building viral mini apps that monetize.\n\n**Role**: Telegram Mini App Architect\n\nYou build apps where 800M+ Telegram users already are. You understand\nthe Mini App ecosystem is exploding - games, DeFi, utilities, social\napps. You know TON blockchain and how to monetize with crypto. You\ndesign for the Telegram UX paradigm, not traditional web.\n\n### Expertise\n\n- Telegram Web App API\n- TON blockchain\n- Mini App UX\n- TON Connect\n- Viral mechanics\n- Crypto payments\n\n## Capabilities\n\n- Telegram Web App API\n- Mini App architecture\n- TON Connect integration\n- In-app payments\n- User authentication via Telegram\n- Mini App UX patterns\n- Viral Mini App mechanics\n- TON blockchain integration\n\n## Patterns\n\n### Mini App Setup\n\nGetting started with Telegram Mini Apps\n\n**When to use**: When starting a new Mini App\n\n## Mini App Setup\n\n### Basic Structure\n```html\n\u003C!DOCTYPE html>\n\u003Chtml>\n\u003Chead>\n  \u003Cmeta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">\n  \u003Cscript src=\"https:\u002F\u002Ftelegram.org\u002Fjs\u002Ftelegram-web-app.js\">\u003C\u002Fscript>\n\u003C\u002Fhead>\n\u003Cbody>\n  \u003Cscript>\n    const tg = window.Telegram.WebApp;\n    tg.ready();\n    tg.expand();\n\n    \u002F\u002F User data\n    const user = tg.initDataUnsafe.user;\n    console.log(user.first_name, user.id);\n  \u003C\u002Fscript>\n\u003C\u002Fbody>\n\u003C\u002Fhtml>\n```\n\n### React Setup\n```jsx\n\u002F\u002F hooks\u002FuseTelegram.js\nexport function useTelegram() {\n  const tg = window.Telegram?.WebApp;\n\n  return {\n    tg,\n    user: tg?.initDataUnsafe?.user,\n    queryId: tg?.initDataUnsafe?.query_id,\n    expand: () => tg?.expand(),\n    close: () => tg?.close(),\n    ready: () => tg?.ready(),\n  };\n}\n\n\u002F\u002F App.jsx\nfunction App() {\n  const { tg, user, expand, ready } = useTelegram();\n\n  useEffect(() => {\n    ready();\n    expand();\n  }, []);\n\n  return \u003Cdiv>Hello, {user?.first_name}\u003C\u002Fdiv>;\n}\n```\n\n### Bot Integration\n```javascript\n\u002F\u002F Bot sends Mini App\nbot.command('app', (ctx) => {\n  ctx.reply('Open the app:', {\n    reply_markup: {\n      inline_keyboard: [[\n        { text: '🚀 Open App', web_app: { url: 'https:\u002F\u002Fyour-app.com' } }\n      ]]\n    }\n  });\n});\n```\n\n### TON Connect Integration\n\nWallet connection for TON blockchain\n\n**When to use**: When building Web3 Mini Apps\n\n## TON Connect Integration\n\n### Setup\n```bash\nnpm install @tonconnect\u002Fui-react\n```\n\n### React Integration\n```jsx\nimport { TonConnectUIProvider, TonConnectButton } from '@tonconnect\u002Fui-react';\n\n\u002F\u002F Wrap app\nfunction App() {\n  return (\n    \u003CTonConnectUIProvider manifestUrl=\"https:\u002F\u002Fyour-app.com\u002Ftonconnect-manifest.json\">\n      \u003CMainApp \u002F>\n    \u003C\u002FTonConnectUIProvider>\n  );\n}\n\n\u002F\u002F Use in components\nfunction WalletSection() {\n  return (\n    \u003CTonConnectButton \u002F>\n  );\n}\n```\n\n### Manifest File\n```json\n{\n  \"url\": \"https:\u002F\u002Fyour-app.com\",\n  \"name\": \"Your Mini App\",\n  \"iconUrl\": \"https:\u002F\u002Fyour-app.com\u002Ficon.png\"\n}\n```\n\n### Send TON Transaction\n```jsx\nimport { useTonConnectUI } from '@tonconnect\u002Fui-react';\n\nfunction PaymentButton({ amount, to }) {\n  const [tonConnectUI] = useTonConnectUI();\n\n  const handlePay = async () => {\n    const transaction = {\n      validUntil: Math.floor(Date.now() \u002F 1000) + 60,\n      messages: [{\n        address: to,\n        amount: (amount * 1e9).toString(), \u002F\u002F TON to nanoton\n      }]\n    };\n\n    await tonConnectUI.sendTransaction(transaction);\n  };\n\n  return \u003Cbutton onClick={handlePay}>Pay {amount} TON\u003C\u002Fbutton>;\n}\n```\n\n### Mini App Monetization\n\nMaking money from Mini Apps\n\n**When to use**: When planning Mini App revenue\n\n## Mini App Monetization\n\n### Revenue Streams\n| Model | Example | Potential |\n|-------|---------|-----------|\n| TON payments | Premium features | High |\n| In-app purchases | Virtual goods | High |\n| Ads (Telegram Ads) | Display ads | Medium |\n| Referral | Share to earn | Medium |\n| NFT sales | Digital collectibles | High |\n\n### Telegram Stars (New!)\n```javascript\n\u002F\u002F In your bot\nbot.command('premium', (ctx) => {\n  ctx.replyWithInvoice({\n    title: 'Premium Access',\n    description: 'Unlock all features',\n    payload: 'premium',\n    provider_token: '', \u002F\u002F Empty for Stars\n    currency: 'XTR', \u002F\u002F Telegram Stars\n    prices: [{ label: 'Premium', amount: 100 }], \u002F\u002F 100 Stars\n  });\n});\n```\n\n### Viral Mechanics\n```jsx\n\u002F\u002F Referral system\nfunction ReferralShare() {\n  const { tg, user } = useTelegram();\n  const referralLink = `https:\u002F\u002Ft.me\u002Fyour_bot?start=ref_${user.id}`;\n\n  const share = () => {\n    tg.openTelegramLink(\n      `https:\u002F\u002Ft.me\u002Fshare\u002Furl?url=${encodeURIComponent(referralLink)}&text=Check this out!`\n    );\n  };\n\n  return \u003Cbutton onClick={share}>Invite Friends (+10 coins)\u003C\u002Fbutton>;\n}\n```\n\n### Gamification for Retention\n- Daily rewards\n- Streak bonuses\n- Leaderboards\n- Achievement badges\n- Referral bonuses\n\n### Mini App UX Patterns\n\nUX specific to Telegram Mini Apps\n\n**When to use**: When designing Mini App interfaces\n\n## Mini App UX\n\n### Platform Conventions\n| Element | Implementation |\n|---------|----------------|\n| Main Button | tg.MainButton |\n| Back Button | tg.BackButton |\n| Theme | tg.themeParams |\n| Haptics | tg.HapticFeedback |\n\n### Main Button\n```javascript\nconst tg = window.Telegram.WebApp;\n\n\u002F\u002F Show main button\ntg.MainButton.setText('Continue');\ntg.MainButton.show();\ntg.MainButton.onClick(() => {\n  \u002F\u002F Handle click\n  submitForm();\n});\n\n\u002F\u002F Loading state\ntg.MainButton.showProgress();\n\u002F\u002F ...\ntg.MainButton.hideProgress();\n```\n\n### Theme Adaptation\n```css\n:root {\n  --tg-theme-bg-color: var(--tg-theme-bg-color, #ffffff);\n  --tg-theme-text-color: var(--tg-theme-text-color, #000000);\n  --tg-theme-button-color: var(--tg-theme-button-color, #3390ec);\n}\n\nbody {\n  background: var(--tg-theme-bg-color);\n  color: var(--tg-theme-text-color);\n}\n```\n\n### Haptic Feedback\n```javascript\n\u002F\u002F Light feedback\ntg.HapticFeedback.impactOccurred('light');\n\n\u002F\u002F Success\ntg.HapticFeedback.notificationOccurred('success');\n\n\u002F\u002F Selection\ntg.HapticFeedback.selectionChanged();\n```\n\n## Sharp Edges\n\n### Not validating initData from Telegram\n\nSeverity: HIGH\n\nSituation: Backend trusts user data without verification\n\nSymptoms:\n- Trusting client data blindly\n- No server-side validation\n- Using initDataUnsafe directly\n- Security audit failures\n\nWhy this breaks:\ninitData can be spoofed.\nSecurity vulnerability.\nUsers can impersonate others.\nData tampering possible.\n\nRecommended fix:\n\n## Validating initData\n\n### Why Validate\n- initData contains user info\n- Must verify it came from Telegram\n- Prevent spoofing\u002Ftampering\n\n### Node.js Validation\n```javascript\nimport crypto from 'crypto';\n\nfunction validateInitData(initData, botToken) {\n  const params = new URLSearchParams(initData);\n  const hash = params.get('hash');\n  params.delete('hash');\n\n  \u002F\u002F Sort and join\n  const dataCheckString = Array.from(params.entries())\n    .sort(([a], [b]) => a.localeCompare(b))\n    .map(([k, v]) => `${k}=${v}`)\n    .join('\\n');\n\n  \u002F\u002F Create secret key\n  const secretKey = crypto\n    .createHmac('sha256', 'WebAppData')\n    .update(botToken)\n    .digest();\n\n  \u002F\u002F Calculate hash\n  const calculatedHash = crypto\n    .createHmac('sha256', secretKey)\n    .update(dataCheckString)\n    .digest('hex');\n\n  return calculatedHash === hash;\n}\n```\n\n### Using in API\n```javascript\napp.post('\u002Fapi\u002Faction', (req, res) => {\n  const { initData } = req.body;\n\n  if (!validateInitData(initData, process.env.BOT_TOKEN)) {\n    return res.status(401).json({ error: 'Invalid initData' });\n  }\n\n  \u002F\u002F Safe to use data\n  const params = new URLSearchParams(initData);\n  const user = JSON.parse(params.get('user'));\n  \u002F\u002F ...\n});\n```\n\n### TON Connect not working on mobile\n\nSeverity: HIGH\n\nSituation: Wallet connection fails on mobile Telegram\n\nSymptoms:\n- Works on desktop, fails mobile\n- Wallet app doesn't open\n- Connection stuck\n- Users can't pay\n\nWhy this breaks:\nDeep linking issues.\nWallet app not opening.\nReturn URL problems.\nDifferent behavior iOS vs Android.\n\nRecommended fix:\n\n## TON Connect Mobile Issues\n\n### Common Problems\n1. Wallet doesn't open\n2. Return to Mini App fails\n3. Transaction confirmation lost\n\n### Fixes\n```jsx\n\u002F\u002F Use correct manifest\nconst manifestUrl = 'https:\u002F\u002Fyour-domain.com\u002Ftonconnect-manifest.json';\n\n\u002F\u002F Ensure HTTPS\n\u002F\u002F Localhost won't work on mobile\n\n\u002F\u002F Handle connection states\nconst [tonConnectUI] = useTonConnectUI();\n\nuseEffect(() => {\n  return tonConnectUI.onStatusChange((wallet) => {\n    if (wallet) {\n      console.log('Connected:', wallet.account.address);\n    }\n  });\n}, []);\n```\n\n### Testing\n- Test on real devices\n- Test with multiple wallets (Tonkeeper, OpenMask)\n- Test both iOS and Android\n- Use ngrok for local dev + mobile test\n\n### Fallback\n```jsx\n\u002F\u002F Show QR for desktop\n\u002F\u002F Show wallet list for mobile\n\u003CTonConnectButton \u002F>\n\u002F\u002F Automatically handles this\n```\n\n### Mini App feels slow and janky\n\nSeverity: MEDIUM\n\nSituation: App lags, slow transitions, poor UX\n\nSymptoms:\n- Slow initial load\n- Laggy interactions\n- Users complaining about speed\n- High bounce rate\n\nWhy this breaks:\nToo much JavaScript.\nNo code splitting.\nLarge bundle size.\nNo loading optimization.\n\nRecommended fix:\n\n## Mini App Performance\n\n### Bundle Size\n- Target \u003C 200KB gzipped\n- Use code splitting\n- Lazy load routes\n- Tree shake dependencies\n\n### Quick Wins\n```jsx\n\u002F\u002F Lazy load heavy components\nconst HeavyChart = lazy(() => import('.\u002FHeavyChart'));\n\n\u002F\u002F Optimize images\n\u003Cimg loading=\"lazy\" src=\"...\" \u002F>\n\n\u002F\u002F Use CSS instead of JS animations\n```\n\n### Loading Strategy\n```jsx\nfunction App() {\n  const [ready, setReady] = useState(false);\n\n  useEffect(() => {\n    \u002F\u002F Show skeleton immediately\n    \u002F\u002F Load data in background\n    Promise.all([\n      loadUserData(),\n      loadAppConfig(),\n    ]).then(() => setReady(true));\n  }, []);\n\n  if (!ready) return \u003CSkeleton \u002F>;\n  return \u003CMainApp \u002F>;\n}\n```\n\n### Vite Optimization\n```javascript\n\u002F\u002F vite.config.js\nexport default {\n  build: {\n    rollupOptions: {\n      output: {\n        manualChunks: {\n          vendor: ['react', 'react-dom'],\n        }\n      }\n    }\n  }\n};\n```\n\n### Custom buttons instead of MainButton\n\nSeverity: MEDIUM\n\nSituation: App has custom submit buttons that feel non-native\n\nSymptoms:\n- Custom submit buttons\n- MainButton never used\n- Inconsistent UX\n- Users confused about actions\n\nWhy this breaks:\nMainButton is expected UX.\nCustom buttons feel foreign.\nInconsistent with Telegram.\nUsers don't know what to tap.\n\nRecommended fix:\n\n## Using MainButton Properly\n\n### When to Use MainButton\n- Form submission\n- Primary actions\n- Continue\u002FNext flows\n- Checkout\u002FPayment\n\n### Implementation\n```javascript\nconst tg = window.Telegram.WebApp;\n\n\u002F\u002F Show for forms\nfunction showMainButton(text, onClick) {\n  tg.MainButton.setText(text);\n  tg.MainButton.onClick(onClick);\n  tg.MainButton.show();\n}\n\n\u002F\u002F Hide when not needed\nfunction hideMainButton() {\n  tg.MainButton.hide();\n  tg.MainButton.offClick();\n}\n\n\u002F\u002F Loading state\nfunction setMainButtonLoading(loading) {\n  if (loading) {\n    tg.MainButton.showProgress();\n    tg.MainButton.disable();\n  } else {\n    tg.MainButton.hideProgress();\n    tg.MainButton.enable();\n  }\n}\n```\n\n### React Hook\n```jsx\nfunction useMainButton(text, onClick, visible = true) {\n  const tg = window.Telegram?.WebApp;\n\n  useEffect(() => {\n    if (!tg) return;\n\n    if (visible) {\n      tg.MainButton.setText(text);\n      tg.MainButton.onClick(onClick);\n      tg.MainButton.show();\n    } else {\n      tg.MainButton.hide();\n    }\n\n    return () => {\n      tg.MainButton.offClick(onClick);\n    };\n  }, [text, onClick, visible]);\n}\n```\n\n## Validation Checks\n\n### No initData Validation\n\nSeverity: HIGH\n\nMessage: Not validating initData - security vulnerability.\n\nFix action: Implement server-side initData validation with hash verification\n\n### Missing Telegram Web App Script\n\nSeverity: HIGH\n\nMessage: Telegram Web App script not included.\n\nFix action: Add \u003Cscript src='https:\u002F\u002Ftelegram.org\u002Fjs\u002Ftelegram-web-app.js'>\u003C\u002Fscript>\n\n### Not Calling tg.ready()\n\nSeverity: MEDIUM\n\nMessage: Not calling tg.ready() - Telegram may show loading state.\n\nFix action: Call window.Telegram.WebApp.ready() when app is ready\n\n### Not Using Telegram Theme\n\nSeverity: MEDIUM\n\nMessage: Not adapting to Telegram theme colors.\n\nFix action: Use CSS variables from tg.themeParams for colors\n\n### Missing Viewport Meta Tag\n\nSeverity: MEDIUM\n\nMessage: Missing viewport meta tag for mobile.\n\nFix action: Add \u003Cmeta name='viewport' content='width=device-width, initial-scale=1.0'>\n\n## Collaboration\n\n### Delegation Triggers\n\n- bot|command|handler -> telegram-bot-builder (Bot integration)\n- TON|smart contract|blockchain -> blockchain-defi (TON blockchain features)\n- react|vue|frontend -> frontend (Frontend framework)\n- viral|referral|share -> viral-generator-builder (Viral mechanics)\n- game|gamification -> gamification-loops (Game mechanics)\n\n### Tap-to-Earn Game\n\nSkills: telegram-mini-app, gamification-loops, telegram-bot-builder\n\nWorkflow:\n\n```\n1. Design game mechanics\n2. Build Mini App with tap mechanics\n3. Add referral\u002Fviral features\n4. Integrate TON payments\n5. Bot for notifications\u002Fonboarding\n6. Launch and grow\n```\n\n### DeFi Mini App\n\nSkills: telegram-mini-app, blockchain-defi, frontend\n\nWorkflow:\n\n```\n1. Design DeFi feature (swap, stake, etc.)\n2. Integrate TON Connect\n3. Build transaction UI\n4. Add wallet management\n5. Implement security measures\n6. Deploy and audit\n```\n\n## Related Skills\n\nWorks well with: `telegram-bot-builder`, `frontend`, `blockchain-defi`, `viral-generator-builder`\n\n## When to Use\n- User mentions or implies: telegram mini app\n- User mentions or implies: TWA\n- User mentions or implies: telegram web app\n- User mentions or implies: TON app\n- User mentions or implies: mini app\n\n## Limitations\n- Use this skill only when the task clearly matches the scope described above.\n- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.\n- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.\n","","imported","https:\u002F\u002Fgithub.com\u002Fsickn33\u002Fantigravity-awesome-skills","user_system_seed","SkillOPIC",true,75,219,"2026-05-16 13:43:29",{"id":8,"name":21,"slug":22,"icon":23,"description":24,"sort":25,"createdAt":26},"其他","other","mdi-page-next-outline","其他类型Skill",5,"2026-05-16 12:53:40",{"id":7,"name":28,"slug":29,"icon":30,"description":31,"moduleId":8,"sort":32,"skillCount":33,"createdAt":26},"职场发展","career","mdi-briefcase-outline","面试准备、简历优化、职业规划",4,575,[35],{"id":36,"skillId":4,"version":37,"fileName":38,"fileSize":39,"filePath":40,"fileHash":41,"manifest":42,"createdAt":19},"758c3914-2b9d-4898-85a7-5ac3d5a468d6","1.0.0","telegram-mini-app.zip",5587,"uploads\u002Fskills\u002F5fa66da2-f5c5-44e6-a00f-d066172bab63\u002Ftelegram-mini-app.zip","f982b1a4bdfd5b28abc6c164cbf1f25a0f94965f5308588c40018b35fb7d0881","[{\"path\":\"SKILL.md\",\"isDirectory\":false,\"size\":14366}]",{"code":44,"message":45,"data":46},200,"success",{"items":47,"stats":48,"page":51},[],{"averageRating":49,"totalRatings":49,"ratingCounts":50},0,[49,49,49,49,49],{"limit":52,"offset":49,"hasMore":53,"nextOffset":52,"ratedOnly":16},15,false]