Вы пишете Telegram Mini App неправильно. Вот доказательство

Если вы когда-нибудь пытались разобраться с @telegram-apps/sdk-react по официальной документации — вы знаете, как это бывает. Половина примеров устарела, TypeScript ругается на типы, а в чате поддержки советуют «почитать исходники».

Эта статья — то, что хотелось бы иметь при первом знакомстве с SDK. Разбираем всё по порядку: установка, инициализация, работа с UI-компонентами Telegram, получение данных пользователя и типичные ошибки, которые встречаются почти в каждом проекте.

Что такое @telegram-apps/sdk-react и зачем он нужен

Telegram Mini Apps работают через WebApp API — набор методов, которые Telegram встраивает в JavaScript-окружение браузера. Напрямую работать с window.Telegram.WebApp можно, но неудобно: нет типов, нет реактивности, код быстро превращается в кашу.

@telegram-apps/sdk-react — это обёртка над WebApp API с React-хуками, TypeScript-типами и удобными компонентами. Он берёт на себя инициализацию и даёт вам чистый декларативный интерфейс.

Основные возможности:

• Хуки для работы с MainButton, BackButton, SettingsButton
• Реактивный доступ к данным пользователя (initDataUnsafe)
• Управление Viewport и цветовой схемой
• Работа с CloudStorage
• Поддержка платежей через Invoice

Установка и настройка проекта

Создаём проект. Рекомендуется Vite + React + TypeScript:

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

Устанавливаем SDK:

npm install @telegram-apps/sdk-react @telegram-apps/sdk

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

npm install -D @telegram-apps/telegram-mock

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

src/
├── components/
├── hooks/
├── App.tsx
├── main.tsx
└── mockEnv.ts   # для разработки

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

Это первое, что нужно сделать до любого использования хуков. Инициализация должна произойти до монтирования React-дерева.

// src/main.tsx
import React from "react";
import ReactDOM from "react-dom/client";
import { init, isTMA } from "@telegram-apps/sdk-react";
import App from "./App";

async function bootstrap() {
  // В dev-режиме эмулируем окружение Telegram
  if (import.meta.env.DEV) {
    const { mockTelegramEnv, parseInitData } =
      await import("@telegram-apps/telegram-mock");

    mockTelegramEnv({
      themeParams: {
        accentTextColor: "#6ab2f2",
        bgColor: "#17212b",
        buttonColor: "#5288c1",
        buttonTextColor: "#ffffff",
        headerBgColor: "#17212b",
        hintColor: "#708499",
        linkColor: "#6ab3f3",
        secondaryBgColor: "#232e3c",
        sectionBgColor: "#17212b",
        sectionHeaderTextColor: "#6ab3f3",
        subtitleTextColor: "#708499",
        textColor: "#f5f5f5",
      },
      initDataRaw: new URLSearchParams([
        [
          "user",
          JSON.stringify({
            id: 123456789,
            first_name: "Иван",
            last_name: "Петров",
            username: "ivan_petrov",
            language_code: "ru",
          }),
        ],
        ["hash", "test_hash"],
      ]).toString(),
    });
  }

  // Проверяем, что мы внутри Telegram
  if (isTMA("simple")) {
    await init();
  }

  ReactDOM.createRoot(document.getElementById("root")!).render(
    <React.StrictMode>
      <App />
    </React.StrictMode>
  );
}

bootstrap();

Важный момент: init() — асинхронная функция. Не вызывайте хуки SDK до её завершения, иначе получите ошибку SDK is not initialized.

SDKProvider — оборачиваем приложение

// src/App.tsx
import { SDKProvider } from "@telegram-apps/sdk-react";
import { MainScreen } from "./components/MainScreen";

export default function App() {
  return (
    <SDKProvider acceptCustomStyles debug={import.meta.env.DEV}>
      <MainScreen />
    </SDKProvider>
  );
}

acceptCustomStyles — позволяет Telegram применять свои CSS-переменные для темизации. Рекомендуется включать всегда.

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

Это самый частый вопрос в поиске — initDataUnsafe @telegram-apps/sdk. Разбираем подробно.

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

function UserProfile() {
  const initData = useInitData();

  if (!initData) {
    return <div>Загрузка...</div>;
  }

  const { user } = initData;

  if (!user) {
    return <div>Пользователь не определён</div>;
  }

  return (
    <div>
      <p>
        Имя: {user.firstName} {user.lastName}
      </p>
      <p>Username: @{user.username}</p>
      <p>ID: {user.id}</p>
      <p>Язык: {user.languageCode}</p>
    </div>
  );
}

Почему "Unsafe"? Потому что данные из initDataUnsafe не верифицированы на клиенте. Для продакшена обязательно проверяйте initData.hash на бэкенде:

# Пример верификации на Python (бэкенд)
import hashlib
import hmac

def verify_init_data(init_data: str, bot_token: str) -> bool:
    parsed = dict(item.split('=', 1) for item in init_data.split('&'))
    received_hash = parsed.pop('hash', '')

    data_check_string = '\n'.join(
        f'{k}={v}' for k, v in sorted(parsed.items())
    )

    secret_key = hmac.new(
        b'WebAppData',
        bot_token.encode(),
        hashlib.sha256
    ).digest()

    expected_hash = hmac.new(
        secret_key,
        data_check_string.encode(),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(received_hash, expected_hash)

MainButton — кнопка в нижней панели

MainButton — одна из самых используемых фич. Это кнопка, которая появляется в нижней части экрана Telegram.

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

function OrderForm() {
  const mainButton = useMainButton();

  useEffect(() => {
    mainButton.setParams({
      text: "Оформить заказ",
      isVisible: true,
      isEnabled: true,
      backgroundColor: "#bdfe52",
      textColor: "#000000",
    });

    const handleClick = () => {
      mainButton.showProgress(); // Показываем загрузку
      submitOrder().then(() => {
        mainButton.hideProgress();
        mainButton.setParams({ text: "✓ Заказ оформлен", isEnabled: false });
      });
    };

    mainButton.on("click", handleClick);

    return () => {
      mainButton.off("click", handleClick);
      mainButton.hide(); // Скрываем при размонтировании
    };
  }, [mainButton]);

  return <form>{/* Поля формы */}</form>;
}

Типичная ошибка: не скрывать MainButton при размонтировании компонента. Кнопка останется видимой на других экранах.

BackButton — навигация назад

import { useBackButton } from "@telegram-apps/sdk-react";
import { useEffect } from "react";
import { useNavigate } from "react-router-dom";

function ProductPage() {
  const backButton = useBackButton();
  const navigate = useNavigate();

  useEffect(() => {
    backButton.show();

    const handleBack = () => navigate(-1);
    backButton.on("click", handleBack);

    return () => {
      backButton.off("click", handleBack);
      backButton.hide();
    };
  }, [backButton, navigate]);

  return <div>{/* Содержимое страницы */}</div>;
}

Совет: выделите логику BackButton в кастомный хук, если используете роутинг:

// hooks/useTelegramBackButton.ts
import { useBackButton } from "@telegram-apps/sdk-react";
import { useEffect } from "react";
import { useNavigate } from "react-router-dom";

export function useTelegramBackButton() {
  const backButton = useBackButton();
  const navigate = useNavigate();

  useEffect(() => {
    backButton.show();
    const handleBack = () => navigate(-1);
    backButton.on("click", handleBack);

    return () => {
      backButton.off("click", handleBack);
      backButton.hide();
    };
  }, [backButton, navigate]);
}

Viewport и адаптация к размеру экрана

Mini App запускается во встроенном WebView, размер которого может меняться (например, при открытии клавиатуры). Используйте useViewport чтобы реагировать на изменения:

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

function ResponsiveLayout() {
  const viewport = useViewport();

  // Расширяем на весь экран при старте
  useEffect(() => {
    viewport?.expand();
  }, [viewport]);

  const height = viewport?.height ?? window.innerHeight;
  const isExpanded = viewport?.isExpanded ?? false;

  return (
    <div style={{ height: `${height}px`, overflow: "hidden" }}>
      {/* Контент */}
    </div>
  );
}

CloudStorage — хранение данных без бэкенда

CloudStorage позволяет хранить небольшие данные (до 1024 байт на ключ, до 1024 ключей) напрямую в Telegram. Удобно для настроек, корзины покупок или черновиков:

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

function CartStorage() {
  const cloudStorage = useCloudStorage();

  const saveCart = async (items: CartItem[]) => {
    await cloudStorage.set("cart", JSON.stringify(items));
  };

  const loadCart = async (): Promise<CartItem[]> => {
    const data = await cloudStorage.get("cart");
    return data ? JSON.parse(data) : [];
  };

  const clearCart = async () => {
    await cloudStorage.delete("cart");
  };

  return { saveCart, loadCart, clearCart };
}

Ограничение: CloudStorage — не замена базе данных. Данные привязаны к конкретному пользователю и конкретному боту, доступны только при открытой Mini App.

Типичные ошибки и как их избежать

За несколько лет разработки Mini Apps мы собрали список ошибок, которые встречаются почти в каждом проекте.

Ошибка 1: Вызов хуков до инициализации

// ❌ Неправильно
function App() {
  const initData = useInitData(); // SDK ещё не инициализирован!
  // ...
}

// ✅ Правильно — дождаться init() в main.tsx до рендера

Ошибка 2: Не проверять наличие данных

// ❌ Упадёт если user === undefined
const { user } = useInitData()!;
console.log(user.firstName);

// ✅
const initData = useInitData();
if (!initData?.user) return null;
console.log(initData.user.firstName);

Ошибка 3: Забыть про cleanup в useEffect

// ❌ Обработчик не снимается
useEffect(() => {
  mainButton.on("click", handleClick);
}, []);

// ✅
useEffect(() => {
  mainButton.on("click", handleClick);
  return () => mainButton.off("click", handleClick);
}, [mainButton]);

Ошибка 4: Тестировать только в браузере

Mini App в браузере и Mini App в Telegram — разные вещи. Обязательно тестируйте через ngrok или аналоги с реальным ботом. Как это настроить — в статье как создать Telegram Mini App.

Деплой и настройка бота

После разработки нужно:

1. Собрать проект: npm run build
2. Разместить dist/ на хостинге с HTTPS (например, Vercel, Netlify или собственный VDS)
3. В BotFather: /newapp или /editapp → установить URL вашего деплоя
4. Проверить через https://t.me/ваш_бот?startapp=

Telegram требует HTTPS — HTTP не работает.

Итог

@telegram-apps/sdk-react значительно упрощает разработку Mini Apps по сравнению с прямой работой через window.Telegram.WebApp. Основные выводы:

• Инициализируйте SDK до монтирования React-дерева
• Всегда верифицируйте initData на бэкенде — никогда не доверяйте клиентским данным
• Следите за cleanup в useEffect для MainButton и BackButton
• Используйте mockTelegramEnv для разработки без постоянного деплоя
• Тестируйте финальную версию в реальном Telegram-клиенте

Если хотите сэкономить время и запустить готовое Mini App без погружения в технические детали — расскажите нам о своём проекте, мы возьмём разработку на себя.

---

Читайте также

• Как создать Telegram Mini App: полная инструкция
• VK Mini Apps или Telegram: где бизнес зарабатывает больше в 2026
• Telegram Bot API 2026: новые возможности