Telegram Mini App: создание с нуля на React в 2025 году

Введение: Telegram Mini Apps в 2025 году

Telegram Mini Apps (ранее Web Apps) — это полноценные веб-приложения, работающие внутри мессенджера Telegram. Они позволяют создавать интерактивные сервисы, игры, боты с интерфейсом и многое другое, не требуя установки отдельного приложения. В 2025 году экосистема Telegram Mini Apps активно развивается, появляются новые возможности для монетизации и интеграции.

В этом полном гайде мы разберёмся, как создать функциональное Telegram Mini App на React с нуля, интегрировать платежи, получить данные пользователя и развернуть приложение в продакшене.

Подготовка: что нужно знать

Перед началом разработки убедитесь, что у вас есть:

Установленный Node.js 16+ и npm/yarn
Базовые знания React и JavaScript
Telegram аккаунт и доступ в Developer Portal
Сервер или хостинг для развёртывания приложения
Понимание как работает Telegram Bot API

Создание React приложения и установка зависимостей

Начните с создания React приложения через Vite (быстрее чем Create React App):

npm create vite@latest telegram-mini-app -- --template react
cd telegram-mini-app
npm install

Установите необходимые зависимости:

npm install @twa-dev/sdk axios react-router-dom

Зависимости:

@twa-dev/sdk — официальный SDK для Telegram Web Apps
axios — для HTTP запросов к вашему backend'у
react-router-dom — маршрутизация внутри приложения

Инициализация Telegram Web App SDK

Первый шаг — инициализировать Telegram SDK в вашем приложении. Отредактируйте main.jsx:

import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App'
import './index.css'

// Инициализируем Telegram SDK
const twa = window.Telegram?.WebApp
if (twa) {
  twa.ready()
  // Установим высоту на всю высоту экрана
  twa.expand()
  // Включим back button если это не стартовая страница
  if (window.history.length > 1) {
    twa.BackButton.show()
  }
}

ReactDOM.createRoot(document.getElementById('root')).render(
  
    
  ,
)

Получение данных пользователя из Telegram

Telegram автоматически передаёт информацию о пользователе через startParam:

// src/hooks/useTelegramData.js
import { useEffect, useState } from 'react'

export const useTelegramData = () => {
  const [user, setUser] = useState(null)
  const [loading, setLoading] = useState(true)

  useEffect(() => {
    const twa = window.Telegram?.WebApp

    if (twa) {
      const initData = twa.initData
      const initDataUnsafe = twa.initDataUnsafe

      setUser({
        id: initDataUnsafe?.user?.id,
        firstName: initDataUnsafe?.user?.first_name,
        lastName: initDataUnsafe?.user?.last_name,
        username: initDataUnsafe?.user?.username,
        photoUrl: initDataUnsafe?.user?.photo_url,
        isPremium: initDataUnsafe?.user?.is_premium,
        languageCode: initDataUnsafe?.user?.language_code,
        initData: initData
      })

      setLoading(false)
    }
  }, [])

  return { user, loading }
}

Создание основного компонента приложения

Создайте главный компонент App.jsx:

import { useEffect, useState } from 'react'
import { useTelegramData } from './hooks/useTelegramData'
import './App.css'

function App() {
  const { user, loading } = useTelegramData()
  const [theme, setTheme] = useState('light')

  useEffect(() => {
    // Получаем текущую тему Telegram
    const twa = window.Telegram?.WebApp
    if (twa) {
      setTheme(twa.colorScheme)

      // Слушаем изменение темы
      const handleThemeChange = () => {
        setTheme(twa.colorScheme)
      }

      twa.onEvent('themeChanged', handleThemeChange)
      return () => {
        twa.offEvent('themeChanged', handleThemeChange)
      }
    }
  }, [])

  if (loading) {
    return Загрузка...
  }

  return (
    
      
        Добро пожаловать!
        {user && Привет, {user.firstName}!}
      

      
        
          {user?.photoUrl && (
            
          )}
          {user?.firstName} {user?.lastName}
          {user?.username && @{user.username}}
          {user?.isPremium && Premium ⭐}
        

        
          
          
        
      
    
  )
}

function handleAction(action) {
  const twa = window.Telegram?.WebApp
  if (twa) {
    twa.HapticFeedback.impactOccurred('light')

    if (action === 'buy') {
      // Запустим платёж (см. следующий раздел)
    } else if (action === 'share') {
      // Поделимся приложением
    }
  }
}

export default App

Интеграция платежей Telegram Stars

Telegram Stars — это встроенная система платежей. Вот как её использовать:

// src/services/payments.js
import axios from 'axios'

export const initiateTelegramStarsPayment = async (userId, amount, description) => {
  const twa = window.Telegram?.WebApp

  if (!twa) {
    console.error('Telegram SDK не инициализирован')
    return
  }

  try {
    // Отправляем запрос на backend
    const response = await axios.post('/api/payments/create', {
      user_id: userId,
      amount: amount,
      description: description,
      currency: 'XTR' // Telegram Stars
    })

    const invoiceLink = response.data.invoice_link

    // Открываем платёж через Web App
    twa.openInvoice(invoiceLink, (status) => {
      if (status === 'paid') {
        console.log('Платёж успешен!')
        twa.showAlert('Спасибо за платёж! 🎉')
      } else if (status === 'cancelled') {
        console.log('Платёж отменён пользователем')
      } else if (status === 'failed') {
        console.log('Ошибка при платеже')
      }
    })
  } catch (error) {
    console.error('Ошибка при создании платежа:', error)
    twa.showAlert('Ошибка при обработке платежа')
  }
}

// Альтернативный способ через Bot API
export const openInvoice = (invoiceLink) => {
  const twa = window.Telegram?.WebApp
  if (twa) {
    twa.openInvoice(invoiceLink)
  }
}

Работа с кнопками и уведомлениями

Telegram предоставляет встроенные кнопки и уведомления:

// src/utils/telegramUI.js

export const showConfirmButton = (text, callback) => {
  const twa = window.Telegram?.WebApp
  if (twa) {
    twa.MainButton.setText(text)
    twa.MainButton.onClick(callback)
    twa.MainButton.show()
  }
}

export const hideConfirmButton = () => {
  const twa = window.Telegram?.WebApp
  if (twa) {
    twa.MainButton.hide()
  }
}

export const showAlert = (message) => {
  const twa = window.Telegram?.WebApp
  if (twa) {
    twa.showAlert(message)
  }
}

export const showConfirm = (message) => {
  return new Promise((resolve) => {
    const twa = window.Telegram?.WebApp
    if (twa) {
      twa.showConfirm(message, (isConfirmed) => {
        resolve(isConfirmed)
      })
    }
  })
}

export const showPopup = (title, buttons) => {
  return new Promise((resolve) => {
    const twa = window.Telegram?.WebApp
    if (twa) {
      twa.showPopup({
        title: title,
        buttons: buttons
      }, (buttonId) => {
        resolve(buttonId)
      })
    }
  })
}

export const hapticFeedback = (type = 'light') => {
  const twa = window.Telegram?.WebApp
  if (twa) {
    twa.HapticFeedback.impactOccurred(type)
  }
}

export const openTelegramLink = (username) => {
  const twa = window.Telegram?.WebApp
  if (twa) {
    twa.openTelegramLink(`https://t.me/${username}`)
  }
}

Пример: создание простого игрового приложения

Давайте создадим простую игру-кликер внутри Telegram:

// src/components/ClickerGame.jsx
import { useState, useEffect } from 'react'
import { useTelegramData } from '../hooks/useTelegramData'
import { hapticFeedback, showAlert } from '../utils/telegramUI'
import './ClickerGame.css'

export default function ClickerGame() {
  const { user } = useTelegramData()
  const [clicks, setClicks] = useState(0)
  const [level, setLevel] = useState(1)
  const [multiplier, setMultiplier] = useState(1)
  const [energy, setEnergy] = useState(100)
  const [maxEnergy, setMaxEnergy] = useState(100)

  // Автовосстановление энергии
  useEffect(() => {
    const interval = setInterval(() => {
      setEnergy(prev => Math.min(prev + 1, maxEnergy))
    }, 1000)

    return () => clearInterval(interval)
  }, [maxEnergy])

  const handleClick = () => {
    if (energy < 10) {
      showAlert('Недостаточно энергии!')
      return
    }

    hapticFeedback('light')
    const earnedClicks = 10 * multiplier
    setClicks(prev => prev + earnedClicks)
    setEnergy(prev => prev - 10)

    // Повышаем уровень каждые 1000 клик
    if (clicks > 0 && clicks % 1000 === 0) {
      setLevel(prev => prev + 1)
    }
  }

  const buyUpgrade = (cost, stateName, stateSetter, increase) => {
    if (clicks >= cost) {
      setClicks(prev => prev - cost)
      stateSetter(prev => prev + increase)
      hapticFeedback('medium')
      showAlert('Улучшение куплено!')
    } else {
      showAlert('Недостаточно денег!')
    }
  }

  return (
    
      🎮 Telegram Clicker

      
        
          Уровень:
          {level}
        
        
          Энергия:
          {energy}/{maxEnergy}
        
      

      
        
      

      
        Множитель: {multiplier}x
      

      
        🛍️ Улучшения
        
        
        
      
    
  )
}

Структурирование проекта

Рекомендуемая структура директорий для большого проекта:

src/
├── components/
│   ├── Header.jsx
│   ├── MainButton.jsx
│   ├── GameScreen.jsx
│   └── ProfileScreen.jsx
├── hooks/
│   ├── useTelegramData.js
│   └── useLocalStorage.js
├── services/
│   ├── api.js
│   ├── payments.js
│   └── database.js
├── utils/
│   ├── telegramUI.js
│   ├── validators.js
│   └── constants.js
├── pages/
│   ├── Home.jsx
│   ├── Profile.jsx
│   └── Shop.jsx
├── styles/
│   ├── index.css
│   ├── theme.css
│   └── components.css
├── App.jsx
└── main.jsx

Backend для Telegram Mini App

Вам нужен backend для обработки платежей и сохранения данных. Вот пример на Node.js:

// server.js (Node.js + Express)
import express from 'express'
import axios from 'axios'

const app = express()
app.use(express.json())

const TELEGRAM_BOT_TOKEN = 'your-bot-token'
const TELEGRAM_API = 'https://api.telegram.org'

// Создание счёта для платежа
app.post('/api/payments/create', async (req, res) => {
  const { user_id, amount, description } = req.body

  try {
    const response = await axios.post(
      `${TELEGRAM_API}/bot${TELEGRAM_BOT_TOKEN}/createInvoiceLink`,
      {
        title: description,
        description: `Платёж от пользователя ${user_id}`,
        payload: JSON.stringify({ user_id, timestamp: Date.now() }),
        provider_token: 'YOUR_PROVIDER_TOKEN',
        currency: 'XTR',
        prices: [
          { label: description, amount: amount * 100 }
        ]
      }
    )

    res.json({ invoice_link: response.data.result.invoice_link })
  } catch (error) {
    console.error('Ошибка при создании платежа:', error)
    res.status(500).json({ error: 'Failed to create invoice' })
  }
})

// Обработка webhook от Telegram
app.post('/webhook', express.json(), (req, res) => {
  const { message, pre_checkout_query, successful_payment } = req.body

  if (pre_checkout_query) {
    // Ответьте на pre-checkout запрос
    axios.post(
      `${TELEGRAM_API}/bot${TELEGRAM_BOT_TOKEN}/answerPreCheckoutQuery`,
      {
        pre_checkout_query_id: pre_checkout_query.id,
        ok: true
      }
    )
  }

  if (successful_payment) {
    console.log('Платёж успешен:', successful_payment)
    // Сохраните информацию о платеже в БД
  }

  res.sendStatus(200)
})

app.listen(3000, () => console.log('Server running on port 3000'))

Развёртывание Telegram Mini App

1. Подготовка к продакшену

npm run build

2. Загрузка на сервер

Загрузите содержимое папки dist/ на ваш сервер. Используйте Nginx или Apache для раздачи статических файлов.

3. Регистрация Mini App в Telegram

Отправьте команду боту через BotFather:

/newapp
Укажите название и URL вашего приложения

4. Запуск Mini App из бота

from telegram import Update, InlineKeyboardMarkup, InlineKeyboardButton, WebAppInfo
from telegram.ext import ContextTypes

async def start(update: Update, context: ContextTypes.DEFAULT_TYPE):
    keyboard = [
        [InlineKeyboardButton(
            "🚀 Открыть приложение",
            web_app=WebAppInfo(url="https://your-app.com")
        )]
    ]
    reply_markup = InlineKeyboardMarkup(keyboard)

    await context.bot.send_message(
        chat_id=update.effective_chat.id,
        text="Добро пожаловать! Нажмите кнопку ниже, чтобы открыть приложение.",
        reply_markup=reply_markup
    )

Лучшие практики разработки Telegram Mini App

Всегда проверяйте доступность Telegram SDK перед его использованием
Используйте кэширование для уменьшения нагрузки на сеть
Предусмотрите fallback для случаев, когда SDK недоступен
Тестируйте приложение на разных устройствах и разрешениях
Обрабатывайте ошибки сети и таймауты
Используйте HTTPS для всех запросов
Валидируйте initData на backend перед обработкой платежей
Сохраняйте состояние приложения в localStorage для быстрого восстановления

Заключение

Создание Telegram Mini App на React — это увлекательный способ построить пользовательскую аудиторию и получить доступ к встроенным платежам. В 2025 году это один из самых быстрорастущих способов разработки приложений благодаря огромной аудитории Telegram и простоте интеграции.

Начните с простого приложения, постепенно добавляйте функции, интегрируйте платежи и масштабируйте. Если вам нужна помощь с разработкой сложного Telegram Mini App, команда Nexora имеет опыт создания успешных приложений для этой платформы.

Ключевые поисковые запросы: Telegram Mini App разработка, создание Web App на Telegram, React Telegram App, Telegram платежи, TMA SDK, Telegram Stars интеграция, создание бота с интерфейсом, Web App API Telegram.