Vibeship-spawner-skills telegram-mini-app

Telegram Mini App Skill

install

source · Clone the upstream repo

git clone https://github.com/vibeforge1111/vibeship-spawner-skills

manifest: maker/telegram-mini-app/skill.yaml

Telegram Mini App Skill

id: telegram-mini-app name: Telegram Mini App version: 1.0.0 layer: 2

description: | 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.

owns:

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

pairs_with:

telegram-bot-builder
frontend
blockchain-defi
viral-generator-builder

triggers:

"telegram mini app"
"TWA"
"telegram web app"
"TON app"
"mini app"

identity: role: Telegram Mini App Architect personality: | 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. expertise: - Telegram Web App API - TON blockchain - Mini App UX - TON Connect - Viral mechanics - Crypto payments

patterns:

name: Mini App Setup description: Getting started with Telegram Mini Apps when_to_use: When starting a new Mini App implementation: |

Mini App Setup

Basic Structure

<!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' } }
      ]]
    }
  });
});

name: TON Connect Integration description: Wallet connection for TON blockchain when_to_use: When building Web3 Mini Apps implementation: |

TON Connect Integration

Setup

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

name: Mini App Monetization description: Making money from Mini Apps when_to_use: When planning Mini App revenue implementation: |

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!)

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

name: Mini App UX Patterns description: UX specific to Telegram Mini Apps when_to_use: When designing Mini App interfaces implementation: |

Mini App UX

Platform Conventions

Element	Implementation
Main Button	tg.MainButton
Back Button	tg.BackButton
Theme	tg.themeParams
Haptics	tg.HapticFeedback

Main Button

const tg = window.Telegram.WebApp;

// Show main button
tg.MainButton.setText('Continue');
tg.MainButton.show();
tg.MainButton.onClick(() => {
  // Handle click
  submitForm();
});

// Loading state
tg.MainButton.showProgress();
// ...
tg.MainButton.hideProgress();

Theme Adaptation

:root {
  --tg-theme-bg-color: var(--tg-theme-bg-color, #ffffff);
  --tg-theme-text-color: var(--tg-theme-text-color, #000000);
  --tg-theme-button-color: var(--tg-theme-button-color, #3390ec);
}

body {
  background: var(--tg-theme-bg-color);
  color: var(--tg-theme-text-color);
}

Haptic Feedback

// Light feedback
tg.HapticFeedback.impactOccurred('light');

// Success
tg.HapticFeedback.notificationOccurred('success');

// Selection
tg.HapticFeedback.selectionChanged();

anti_patterns:

name: Ignoring Telegram Theme description: App doesn't match Telegram look and feel why_bad: | Feels foreign in Telegram. Bad user experience. Jarring transitions. Users don't trust it. what_to_do_instead: | Use tg.themeParams. Match Telegram colors. Use native-feeling UI. Test in both light/dark.
name: Desktop-First Mini App description: Designed for desktop, broken on mobile why_bad: | 95% of Telegram is mobile. Touch targets too small. Doesn't fit in Telegram UI. Scrolling issues. what_to_do_instead: | Mobile-first always. Test on real phones. Touch-friendly buttons. Fit within Telegram frame.
name: No Loading States description: Blank screen while loading why_bad: | Users think it's broken. Poor perceived performance. High exit rate. Confusion. what_to_do_instead: | Show skeleton UI. Loading indicators. Progressive loading. Optimistic updates.

handoffs:

trigger: "bot|command|telegram bot" to: telegram-bot-builder context: "Bot integration"
trigger: "TON|blockchain|smart contract" to: blockchain-defi context: "TON blockchain features"
trigger: "react|frontend|UI" to: frontend context: "Frontend implementation"
trigger: "viral|share|referral" to: viral-generator-builder context: "Viral mechanics"