Создаём Telegram Mini App на React: пошаговый туториал

Введение: почему React — лучший выбор для Mini App

Telegram Mini Apps — это веб-приложения, работающие внутри мессенджера. А раз это веб, значит, для разработки подходят любые современные фреймворки. Но React остаётся самым популярным выбором: огромная экосистема библиотек, знакомый разработчикам синтаксис и отличная совместимость с Telegram WebApp SDK.

В этом туториале мы пройдём весь путь — от npm create до деплоя. Создадим Mini App с реальной функциональностью: авторизацией пользователя, адаптацией под тему Telegram, навигацией, платежами и haptic feedback. Общее представление о платформе Mini Apps можно получить в нашей обзорной статье.

1. Инициализация проекта: Vite + React + TypeScript

Для сборки используем Vite — он обеспечивает мгновенный hot reload и оптимальный продакшен-бандл.

Создание проекта

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

Структура проекта

Организуем код по функциональным модулям:

src/
├── components/       # UI-компоненты
│   ├── ui/          # Базовые элементы (Button, Input, Card)
│   └── layout/      # Layout-компоненты (Header, Page)
├── hooks/           # Кастомные хуки
│   ├── useTelegram.ts
│   └── useTheme.ts
├── pages/           # Страницы приложения
├── services/        # API-клиент и бизнес-логика
├── types/           # TypeScript-типы
├── utils/           # Утилиты
├── App.tsx
└── main.tsx

Такая структура масштабируется: при росте приложения добавляются новые модули, а не растут существующие файлы.

Настройка Vite

Для корректной работы Mini App нужно настроить несколько параметров Vite:

// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";

export default defineConfig({
  plugins: [react()],
  server: {
    host: true, // Доступ с мобильного устройства в локальной сети
    port: 3000,
  },
  build: {
    outDir: "dist",
    sourcemap: false,
    rollupOptions: {
      output: {
        manualChunks: {
          vendor: ["react", "react-dom"],
        },
      },
    },
  },
});

2. Подключение Telegram WebApp SDK

Установка SDK

Telegram предоставляет официальный npm-пакет:

npm install @telegram-apps/sdk-react

Этот пакет включает React-хуки для работы с Telegram API. Альтернативно можно использовать низкоуровневый @telegram-apps/sdk, но React-обёртка удобнее.

Инициализация SDK

Создадим провайдер, который инициализирует SDK при загрузке приложения:

// src/components/TelegramProvider.tsx
import {useEffect, useState, ReactNode} from 'react'
import {init, backButton, miniApp} from '@telegram-apps/sdk-react'

interface Props {
    children: ReactNode
}

export function TelegramProvider({children}: Props) {
    const [ready, setReady] = useState(false)

    useEffect(() => {
        const initApp = async () => {
            try {
                init()
                miniApp.ready()
                setReady(true)
            } catch (error) {
                console.error('Failed to init Telegram SDK:', error)
                // Fallback для разработки в браузере
                setReady(true)
            }
        }
        initApp()
    }, [])

    if (!ready) return <div>Loading
...
    </div>
    return <>{children} < />
}

Обёртка в main.tsx

// src/main.tsx
import React from 'react'
import ReactDOM from 'react-dom/client'
import {TelegramProvider} from './components/TelegramProvider'
import App from './App'
import './index.css'

ReactDOM.createRoot(document.getElementById('root')!).render(
    <React.StrictMode>
        <TelegramProvider>
            <App / >
    </TelegramProvider>
    < /React.StrictMode>,
)

3. Адаптация темы под Telegram

Одно из ключевых требований к Mini App — визуальная интеграция с Telegram. Приложение должно выглядеть как часть мессенджера, а не как чужеродная вставка.

CSS-переменные Telegram

Telegram передаёт цветовую схему через CSS-переменные. Основные переменные:

:root {
  --tg-theme-bg-color: #ffffff;
  --tg-theme-text-color: #000000;
  --tg-theme-hint-color: #999999;
  --tg-theme-link-color: #2481cc;
  --tg-theme-button-color: #5288c1;
  --tg-theme-button-text-color: #ffffff;
  --tg-theme-secondary-bg-color: #efeff3;
}

Глобальные стили

/* src/index.css */
* {
  margin: 0;
  padding: 0;
  box-sizing: border-box;
}

body {
  font-family:
    -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
  background-color: var(--tg-theme-bg-color, #ffffff);
  color: var(--tg-theme-text-color, #000000);
  -webkit-font-smoothing: antialiased;
}

a {
  color: var(--tg-theme-link-color, #2481cc);
}

Кастомный хук для темы

Создадим хук, который удобно предоставляет цвета темы в компонентах:

// src/hooks/useTheme.ts
import { useMemo } from "react";
import { useThemeParams } from "@telegram-apps/sdk-react";

export function useAppTheme() {
  const themeParams = useThemeParams();

  return useMemo(
    () => ({
      bgColor: themeParams.bgColor || "#ffffff",
      textColor: themeParams.textColor || "#000000",
      hintColor: themeParams.hintColor || "#999999",
      linkColor: themeParams.linkColor || "#2481cc",
      buttonColor: themeParams.buttonColor || "#5288c1",
      buttonTextColor: themeParams.buttonTextColor || "#ffffff",
      secondaryBgColor: themeParams.secondaryBgColor || "#efeff3",
      isDark: themeParams.bgColor
        ? parseInt(themeParams.bgColor.slice(1), 16) < 0x808080
        : false,
    }),
    [themeParams]
  );
}

Теперь компоненты автоматически подстраиваются под светлую и тёмную тему Telegram. Если вас интересуют продвинутые приёмы адаптивной вёрстки, рекомендуем нашу статью про адаптивный дизайн с Tailwind CSS.

4. Навигация в Mini App

Выбор подхода

В Mini App есть нативная кнопка «Назад» в шапке Telegram. Это значит, что навигация должна быть интегрирована с этой кнопкой. Используем react-router-dom:

npm install react-router-dom

Настройка роутера

// src/App.tsx
import {BrowserRouter, Routes, Route, useNavigate, useLocation} from 'react-router-dom'
import {useEffect} from 'react'
import {backButton} from '@telegram-apps/sdk-react'
import {HomePage} from './pages/HomePage'
import {ProductPage} from './pages/ProductPage'
import {CartPage} from './pages/CartPage'

function NavigationHandler() {
    const navigate = useNavigate()
    const location = useLocation()

    useEffect(() => {
        if (location.pathname !== '/') {
            backButton.show()
        } else {
            backButton.hide()
        }

        const off = backButton.onClick(() => {
            navigate(-1)
        })

        return () => off()
    }, [location, navigate])

    return null
}

export default function App() {
    return (
        <BrowserRouter>
            <NavigationHandler / >
        <Routes>
            <Route path = "/"
    element = { < HomePage / >
}
    />
    < Route
    path = "/product/:id"
    element = { < ProductPage / >
}
    />
    < Route
    path = "/cart"
    element = { < CartPage / >
}
    />
    < /Routes>
    < /BrowserRouter>
)
}

Важные нюансы навигации

Несколько моментов, которые часто упускают:

• Не используйте хеш-роутинг — BrowserRouter лучше работает с Telegram
• Кнопка «Назад» должна быть предсказуемой — пользователь ожидает, что она вернёт на предыдущий экран
• Глубина навигации — старайтесь не делать более 3–4 уровней вложенности
• Анимации переходов — добавляют ощущение нативности, используйте framer-motion

5. Аутентификация пользователя

Как работает initData

При запуске Mini App Telegram передаёт подписанную строку initData, содержащую информацию о пользователе. Эту строку нужно проверить на бэкенде — чтобы убедиться, что данные подлинные.

Получение initData на фронте

// src/hooks/useAuth.ts
import { useLaunchParams } from "@telegram-apps/sdk-react";

export function useAuth() {
  const launchParams = useLaunchParams();

  const initData = launchParams.initDataRaw;
  const user = launchParams.initData?.user;

  return {
    initData,
    user,
    isAuthenticated: !!user,
    userId: user?.id,
    firstName: user?.firstName,
    lastName: user?.lastName,
    username: user?.username,
    isPremium: user?.isPremium,
    languageCode: user?.languageCode,
    photoUrl: user?.photoUrl,
  };
}

Валидация на бэкенде (Node.js)

// server/auth.ts
import crypto from "crypto";

function validateInitData(initData: string, botToken: string): boolean {
  const params = new URLSearchParams(initData);
  const hash = params.get("hash");
  params.delete("hash");

  const dataCheckString = Array.from(params.entries())
    .sort(([a], [b]) => a.localeCompare(b))
    .map(([key, value]) => `${key}=${value}`)
    .join("\n");

  const secretKey = crypto
    .createHmac("sha256", "WebAppData")
    .update(botToken)
    .digest();

  const calculatedHash = crypto
    .createHmac("sha256", secretKey)
    .update(dataCheckString)
    .digest("hex");

  return calculatedHash === hash;
}

Эта проверка гарантирует, что данные пришли именно от Telegram и не были подменены. Без неё любой может подделать запрос к вашему API.

6. Взаимодействие с бэкендом

API-клиент

Создадим обёртку для fetch с автоматической передачей initData:

// src/services/api.ts
const API_URL = import.meta.env.VITE_API_URL || "https://api.example.com";

class ApiClient {
  private initData: string = "";

  setInitData(data: string) {
    this.initData = data;
  }

  async request<T>(path: string, options: RequestInit = {}): Promise<T> {
    const response = await fetch(`${API_URL}${path}`, {
      ...options,
      headers: {
        "Content-Type": "application/json",
        "X-Init-Data": this.initData,
        ...options.headers,
      },
    });

    if (!response.ok) {
      throw new Error(`API Error: ${response.status}`);
    }

    return response.json();
  }

  get<T>(path: string) {
    return this.request<T>(path);
  }

  post<T>(path: string, body: unknown) {
    return this.request<T>(path, {
      method: "POST",
      body: JSON.stringify(body),
    });
  }
}

export const api = new ApiClient();

Хук для загрузки данных

// src/hooks/useApi.ts
import { useState, useEffect } from "react";
import { api } from "../services/api";

export function useApi<T>(path: string) {
  const [data, setData] = useState<T | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    api
      .get<T>(path)
      .then(setData)
      .catch((e) => setError(e.message))
      .finally(() => setLoading(false));
  }, [path]);

  return { data, loading, error };
}

7. Платежи через Telegram Stars

Как работают Telegram Stars

Telegram Stars — внутренняя валюта платформы. Пользователи покупают Stars через Apple Pay или Google Pay, а затем тратят их в Mini Apps. Разработчик получает средства и может вывести их через Fragment.

Создание инвойса на бэкенде

// server/payments.ts
import { Bot } from "grammy";

const bot = new Bot(process.env.BOT_TOKEN!);

async function createInvoice(
  userId: number,
  title: string,
  description: string,
  amount: number
) {
  const invoiceLink = await bot.api.createInvoiceLink(
    title,
    description,
    JSON.stringify({ userId, amount }), // payload
    "", // provider_token (пусто для Stars)
    "XTR", // currency (XTR = Stars)
    [{ label: title, amount }] // prices
  );

  return invoiceLink;
}

Оплата на фронте

// src/hooks/usePayment.ts
import { miniApp } from "@telegram-apps/sdk-react";
import { api } from "../services/api";

export function usePayment() {
  const pay = async (productId: string) => {
    // Получаем ссылку на инвойс с бэкенда
    const { invoiceLink } = await api.post<{ invoiceLink: string }>(
      "/payments/create",
      { productId }
    );

    // Открываем окно оплаты Telegram
    const result = await miniApp.openInvoice(invoiceLink);

    if (result === "paid") {
      // Оплата успешна
      return true;
    }

    return false;
  };

  return { pay };
}

Обработка webhook

Telegram отправит webhook при успешной оплате. Бэкенд должен подтвердить получение:

// server/webhook.ts
bot.on("pre_checkout_query", async (ctx) => {
  // Проверяем, можем ли выполнить заказ
  await ctx.answerPreCheckoutQuery(true);
});

bot.on("message:successful_payment", async (ctx) => {
  const payment = ctx.message.successful_payment;
  const payload = JSON.parse(payment.invoice_payload);

  // Выдаём пользователю оплаченный товар/услугу
  await fulfillOrder(payload.userId, payload.amount);

  await ctx.reply("Оплата прошла успешно!");
});

8. Haptic Feedback и нативные функции

Haptic Feedback

Вибрационная обратная связь делает Mini App ощутимо нативнее. Telegram предоставляет три типа:

// src/hooks/useHaptic.ts
import { hapticFeedback } from "@telegram-apps/sdk-react";

export function useHaptic() {
  return {
    // Лёгкий тап — для нажатия кнопок
    impact: (
      style: "light" | "medium" | "heavy" | "rigid" | "soft" = "light"
    ) => {
      hapticFeedback.impactOccurred(style);
    },
    // Уведомление — для результатов действий
    notification: (type: "success" | "warning" | "error") => {
      hapticFeedback.notificationOccurred(type);
    },
    // Изменение выбора — для переключателей
    selectionChanged: () => {
      hapticFeedback.selectionChanged();
    },
  };
}

Пример использования в компоненте

function ProductCard({product}: { product: Product }) {
    const {impact, notification} = useHaptic()
    const {pay} = usePayment()

    const handleBuy = async () => {
        impact('medium')
        const success = await pay(product.id)
        notification(success ? 'success' : 'error')
    }

    return (
        <div className = "product-card" >
            <h3>{product.name} < /h3>
            < p > {product.price}
    Stars < /p>
    < button
    onClick = {handleBuy} > Купить < /button>
        < /div>
)
}

QR-сканер

import { qrScanner } from "@telegram-apps/sdk-react";

async function scanQR() {
  const result = await qrScanner.open({ text: "Наведите камеру на QR-код" });
  if (result) {
    console.log("Scanned:", result);
  }
  qrScanner.close();
}

Cloud Storage

import { cloudStorage } from "@telegram-apps/sdk-react";

// Сохранить данные
await cloudStorage.setItem("cart", JSON.stringify(cartItems));

// Загрузить данные
const saved = await cloudStorage.getItem("cart");
const cart = saved ? JSON.parse(saved) : [];

9. Тестирование и отладка

Локальная разработка

Для тестирования Mini App локально нужен HTTPS. Используем ngrok или Cloudflare Tunnel:

# Запускаем dev-сервер
npm run dev

# В другом терминале — туннель
npx cloudflared tunnel --url http://localhost:3000

Полученный HTTPS-URL указываем в @BotFather как URL Mini App.

Debug Mode

В Telegram Desktop можно включить Debug Mode: правый клик по Mini App и выбрать «Inspect Element». Откроется Chrome DevTools с полным доступом к консоли, сети и элементам.

На мобильных устройствах используйте eruda — встроенную консоль для мобильного веба:

npm install eruda

// Только для разработки!
if (import.meta.env.DEV) {
  import("eruda").then((eruda) => eruda.default.init());
}

Тестирование без Telegram

Для юнит-тестов и разработки в браузере создадим мок Telegram SDK:

// src/utils/mockTelegram.ts
export function mockTelegramEnv() {
  if (typeof window !== "undefined" && !window.Telegram) {
    window.Telegram = {
      WebApp: {
        initData: "mock_init_data",
        initDataUnsafe: {
          user: {
            id: 12345,
            first_name: "Test",
            last_name: "User",
            username: "testuser",
          },
        },
        ready: () => {},
        expand: () => {},
        close: () => {},
        // ... другие методы
      },
    } as any;
  }
}

10. Деплой Mini App

Вариант 1: Vercel

Самый простой способ задеплоить Mini App:

npm install -g vercel
vercel

Vercel автоматически определит Vite-проект, соберёт его и задеплоит. Вы получите HTTPS-URL, который можно сразу указать в @BotFather.

Вариант 2: Cloudflare Pages

Бесплатный хостинг с отличной производительностью:

npm install -g wrangler
wrangler pages deploy dist

Вариант 3: VPS с Nginx

Для полного контроля можно разместить Mini App на VPS:

server {
    listen 443 ssl;
    server_name mini-app.example.com;

    ssl_certificate /etc/letsencrypt/live/mini-app.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/mini-app.example.com/privkey.pem;

    root /var/www/mini-app/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }
}

Настройка бота в BotFather

После деплоя настройте бота:

1. Откройте @BotFather
2. Выберите бота: /mybots -> ваш бот
3. Bot Settings -> Menu Button -> укажите URL Mini App
4. Или Bot Settings -> Mini App -> укажите URL

CI/CD

Автоматизируйте деплой через GitHub Actions:

name: Deploy Mini App
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run build
      - uses: cloudflare/pages-action@v1
        with:
          apiToken: ${{ secrets.CF_API_TOKEN }}
          accountId: ${{ secrets.CF_ACCOUNT_ID }}
          projectName: my-mini-app
          directory: dist

Подробнее о настройке мониторинга и CI/CD для веб-приложений можно прочитать в нашей отдельной статье.

Архитектурные решения и рекомендации

Производительность

Mini App работает в WebView, поэтому каждый килобайт на счету:

• Минимизируйте бандл — используйте tree shaking, lazy loading для страниц
• Оптимизируйте изображения — WebP, lazy loading, правильные размеры
• Кэшируйте данные — используйте React Query или SWR для кэширования API-запросов
• Избегайте тяжёлых библиотек — date-fns вместо moment, zod вместо yup

Оффлайн-поддержка

Mini App может ограниченно работать офлайн через Service Worker. Кэшируйте статику и критичные данные.

Аналитика

Подключите аналитику для понимания поведения пользователей:

• Telegram предоставляет базовую статистику через @BotFather
• Для детальной аналитики используйте Amplitude или Mixpanel
• Отслеживайте воронку: открытие -> взаимодействие -> конверсия

Заключение

Мы прошли полный путь создания Telegram Mini App на React: от инициализации проекта до деплоя. Ключевые моменты:

1. Vite + React + TypeScript — оптимальный стек для Mini App
2. Telegram SDK — предоставляет всё необходимое для интеграции
3. Адаптация темы — обязательна для нативного ощущения
4. initData — безопасная аутентификация без регистрации
5. Telegram Stars — простой способ монетизации
6. Haptic feedback — мелочь, которая делает приложение живым

Если вам нужна помощь с разработкой Mini App — обращайтесь. Мы создаём Mini Apps на React с полным циклом: от проектирования до запуска и поддержки. Также можем подключить вашу IT-инфраструктуру для бесперебойной работы приложения.