Telegram Mini App на React собирается за один вечер, если взять готовый стек: Vite, TypeScript и библиотеку @telegram-apps/sdk-react. Ниже — пошаговый путь от регистрации бота у BotFather до рабочего деплоя на Vercel, с адаптацией темы, навигацией че…
10+ лет в маркетинге, 300+ клиентских проектов: сайты, реклама, боты. Создатель GoBanana (228K+ пользователей, 11.6 млн ₽ выручки) и VibeCoderz. Делаю AI-продукты сам через Claude Code, Cursor, Windsurf и консультирую тех, кто хочет так же.
Об авторе →Claude Code: новый CLI-агент от Anthropic
Anthropic выпустила Claude Code — терминальный AI-агент для разработчиков. Инструмент работает прямо в командной строке и умеет писать, редактировать и запускать код.
Zcode AI: Полный гид по визуальному интерфейсу для Claude Code и AI-агентов
Узнайте, как использовать Zcode для управления Claude Code, Gemini и Codex в едином GUI. Настройка провайдеров, MCP-серверов и визуальный вайбкодинг.
YouTube-канал с монетизацией из любой точки мира: Пошаговый гайд 2026
Инструкция по созданию YouTube-канала: обход блокировок SMS, настройка расширенных функций через виртуальные номера и правила безопасности для монетизации.
Windsurf Code Maps: Как глубоко понимать архитектуру проекта перед написанием кода
Полный гайд по Windsurf Code Maps, модели Sway 1.5 и Sway Grep. Узнайте, как визуализировать архитектуру кода и ускорить разработку в 13 раз.
Vk Fast Cash Strategy
Аудитория ВКонтакте — это те же люди, что и в Instagram, но 'социальный контракт' площадки другой. Если Instagram — это 'дорогой ресторан' с демонстрацией успеха, то VK — это 'душевная шашлычная'. Здесь не работает глянцевый 'успешный успех
Telegram Mini App на React собирается за один вечер, если взять готовый стек: Vite, TypeScript и библиотеку @telegram-apps/sdk-react. Ниже — пошаговый путь от регистрации бота у BotFather до рабочего деплоя на Vercel, с адаптацией темы, навигацией через BackButton и haptic feedback.
В статье: регистрация бота и Mini App через BotFather, сборка проекта на Vite с telegram-apps sdk-react, адаптация темы под Telegram, навигация без кастомных костылей, вибро-отклик на нажатия и деплой на Vercel или Netlify с обязательным HTTPS-доменом.
Реальный таймлайн для простого Mini App без сложной бизнес-логики, несколько экранов, авторизация через Telegram — 3-5 часов. Это касается регистрации бота, вёрстки экранов и деплоя вместе.
Mini App — это веб-приложение, открытое внутри Telegram через WebView, с доступом к данным пользователя, теме оформления и нативным функциям вроде вибрации и кнопки "назад".
Telegram передаёт в приложение объект window.Telegram.WebApp сразу после инициализации скрипта telegram-web-app.js. Через него доступны имя, аватар, язык и цветовая тема пользователя, а также акселерометр, гироскоп и геолокация на совместимых клиентах. Официальная документация Telegram фиксирует этот список методов и обновляет его почти каждый месяц, добавляя новые возможности вроде эмодзи-статусов и Stars-подписок.
По сути это Single Page Application: страница не перезагружается при переходах, а перерисовывает контент через роутинг React. Разница с обычным сайтом одна, но принципиальная: Mini App живёт в контексте Telegram и без него не получит данные пользователя. Открыть его напрямую в браузере можно, но initData будет пустым.
Регистрация занимает 5-7 минут: команда /newbot создаёт бота и токен, команда /newapp привязывает к нему Mini App с иконкой и коротким описанием.
Без этого шага дальнейшая разработка бессмысленна — Telegram не откроет приложение без привязанного бота и домена. BotFather — единственная официальная точка входа, и пропустить её нельзя даже для локального тестирования полной функциональности.
Порядок действий:
@BotFather, отправь /newbot, задай имя и username бота (должен заканчиваться на bot)./newapp, выбери созданного бота, загрузи иконку (512×512, PNG) и короткое описание Mini App./mybots → выбранный бот → Bot Settings → Menu Button привяжи финальный URL, когда он появится.Без пункта 5 приложение не появится в интерфейсе бота, даже если деплой прошёл успешно.
Оптимальный стек 2026 года: Vite как сборщик, React 18 с TypeScript и @telegram-apps/sdk-react для доступа к API Telegram через хуки вместо сырого JavaScript.
Vite стартует за секунды и не требует конфигурации webpack, в отличие от Create React App, который к тому же официально не поддерживается командой React. Для Mini App это особенно важно: время сборки напрямую влияет на скорость итераций внутри Telegram, где приходится постоянно перезапускать WebView для проверки изменений.
Библиотека @telegram-apps/sdk-react на момент публикации имеет актуальную версию 3.3.9 и даёт React-хуки поверх нативного Telegram Web App API — useLaunchParams, useRawInitData, useBackButton и другие, без ручной работы с window.Telegram.WebApp. Стоит держать в голове честную оговорку: часть внутренних пакетов экосистемы (bridge, transformers, types) команда постепенно переносит под неймспейс @tma.js/*, так что при апдейте зависимостей проверяй changelog перед npm update.
| Инструмент | Роль в стеке | Почему именно он |
|---|---|---|
| Vite | Сборщик и dev-сервер | Запуск за секунды, HMR из коробки |
| React 18 + TypeScript | UI и типобезопасность | Готовые хуки под Mini App, меньше runtime-ошибок |
| @telegram-apps/sdk-react | Обёртка над Telegram Web App API | React-хуки вместо сырого JS SDK |
| Tailwind CSS (опционально) | Стилизация | Классы прямо в разметке, быстрее кастомного CSS |
Создаёшь проект через Vite-шаблон React + TypeScript, ставишь SDK одной командой и подключаешь провайдер в точке входа приложения.
Официальный шаблон организации Telegram-Mini-Apps на GitHub уже содержит настроенный HTTPS для локальной разработки — Telegram требует защищённое соединение даже в dev-режиме, и без плагина vite-plugin-mkcert браузер будет ругаться на сертификат.
npm create vite@latest my-mini-app -- --template react-ts
cd my-mini-app
npm install @telegram-apps/sdk-react
npm run devВ main.tsx инициализация SDK выглядит так:
import { SDKProvider, useLaunchParams } from '@telegram-apps/sdk-react';
function Root() {
const launchParams = useLaunchParams();
return <App theme={launchParams.tgWebAppThemeParams} />;
}
createRoot(document.getElementById('root')!).render(
<SDKProvider acceptCustomStyles>
<Root />
</SDKProvider>
);Один нюанс из практики: если переменная объявлена, но нигде не используется, TypeScript в строгом режиме выдаст ошибку сборки, а не предупреждение — удаляй неиспользуемый импорт сразу, иначе npm run build упадёт прямо перед деплоем.
Telegram передаёт цветовую схему пользователя через CSS-переменные вроде --tg-theme-bg-color, и приложение подхватывает светлую или тёмную тему без дополнительной логики.
Это тот момент, где Mini App отличается от обычного сайта визуально: пользователь ожидает, что интерфейс будет выглядеть как часть Telegram, а не как встроенный iframe стороннего сервиса. Хук useThemeParams из SDK возвращает объект с цветами, которые можно прокинуть в CSS-переменные корневого элемента.
import { useThemeParams } from '@telegram-apps/sdk-react';
function ThemeSync() {
const theme = useThemeParams();
useEffect(() => {
document.documentElement.style.setProperty('--bg', theme.bgColor);
document.documentElement.style.setProperty('--text', theme.textColor);
}, [theme]);
return null;
}Если в проекте уже используется Tailwind, цвета из темы удобно завести как CSS-переменные в tailwind.config и обращаться к ним классами вроде bg-[var(--bg)]. Так тема меняется на лету при переключении пользователем светлого и тёмного режима прямо в Telegram, без перезагрузки.
Вместо своей кнопки "назад" используй встроенный BackButton API через хук useBackButton — Telegram сам покажет системную кнопку и синхронизирует её с навигацией внутри React Router.
Кастомная реализация кнопки назад выглядит чужеродно и требует лишнего кода. Системная кнопка BackButton встроена в интерфейс Telegram, появляется в шапке автоматически и работает одинаково на iOS, Android и десктопе.
import { useBackButton } from '@telegram-apps/sdk-react';
import { useNavigate, useLocation } from 'react-router-dom';
function BackButtonSync() {
const backButton = useBackButton();
const navigate = useNavigate();
const location = useLocation();
useEffect(() => {
if (location.pathname === '/') {
backButton.hide();
return;
}
backButton.show();
const off = backButton.on('click', () => navigate(-1));
return () => off();
}, [location.pathname]);
return null;
}На главном экране кнопку прячешь, на всех остальных — показываешь и вешаешь обработчик клика на navigate(-1). Работает предсказуемо, если маршруты в React Router организованы плоско, без глубокой вложенности через несколько уровней модалок.
Хук useHapticFeedback вызывает вибрацию на устройстве через один метод — impactOccurred, notificationOccurred или selectionChanged в зависимости от типа действия.
Вибро-отклик — деталь, которая на практике сильнее всего отличает Mini App от "веб-страницы в рамке". Без него интерфейс ощущается плоским, даже если анимации сделаны идеально.
import { useHapticFeedback } from '@telegram-apps/sdk-react';
function SubmitButton() {
const haptic = useHapticFeedback();
const handleClick = () => {
haptic.impactOccurred('medium');
// основная логика кнопки
};
return <button onClick={handleClick}>Отправить</button>;
}Для успешных действий (оплата прошла, форма отправлена) уместнее notificationOccurred('success'), для ошибок — notificationOccurred('error'). Перебарщивать не стоит: вибрация на каждый клик утомляет пользователя за пару минут использования.
Оба сервиса дают бесплатный тариф с HTTPS "из коробки" — обязательное требование Telegram, без которого Mini App не откроется по кнопке меню.
Здесь легко потерять час на невидимую с первого взгляда деталь: собранный и задеплоенный фронтенд ещё не значит рабочий Mini App. Пока в BotFather не указан финальный HTTPS-домен через Menu Button, Telegram будет открывать заглушку или вообще ничего.
Шаги для Vercel:
npm run build — Vite создаст папку dist.npm install -g vercel, авторизуйся через vercel login.vercel, выбери Create New Project, подтверди путь к dist.my-mini-app.vercel.app./mybots → бот → Bot Settings → Menu Button → вставь домен.Если в проекте есть серверная часть (например, для валидации initData или работы с базой), деплоить нужно отдельно: backend как самостоятельный Vercel-проект с обработчиком в vercel.json, frontend — как второй проект. Переменные окружения вроде BOT_TOKEN и SERVER_URL добавляются в панели Vercel через Environment Variables или командой vercel env add.
| Параметр | Vercel | Netlify |
|---|---|---|
| Бесплатный HTTPS-домен | Да | Да |
| CLI-деплой одной командой | Да (vercel) | Да (netlify deploy) |
| Serverless-функции на бесплатном тарифе | Да | Да, с ограничением по времени выполнения |
| Автодеплой из GitHub | Да | Да |
Netlify подходит так же хорошо, если проект чисто фронтендовый — разницы в итоговом результате для простого Mini App почти нет, выбор часто сводится к личной привычке.
Максим: «Веб-версию GoBanana мы собрали за 3 часа после выхода модели. 6-8 часов суммарно ушло на продукт, который принёс 12 миллионов рублей без рубля рекламы.»
С Mini App похожая логика: сам React-компонент и хуки из SDK пишутся быстро, если стек знаком. Основное время в вечере уходит не на код, а на пошаговую настройку BotFather и проверку, что домен действительно подхватился.
Для простого приложения без сложной бизнес-логики — 3-5 часов, включая регистрацию бота, вёрстку 2-3 экранов и деплой с проверкой в самом Telegram.
Разбивка по этапам примерно такая: 15-20 минут на BotFather, час-полтора на настройку проекта и базовую вёрстку, 30-40 минут на интеграцию темы, навигации и haptic feedback, ещё 30-40 минут на деплой и финальную проверку домена. Если добавляется серверная часть с авторизацией через initData и базой данных, таймлайн стоит закладывать на вечер плюс следующее утро — валидация подписи Telegram на бэкенде обычно съедает больше времени, чем ожидаешь заранее.
React остаётся разумным выбором для Mini App, если команда уже пишет на нём фронтенд и хочет переиспользовать компоненты. Для одностраничных лендингов внутри бота иногда проще обойтись Vanilla JS или Svelte — меньше зависимостей, быстрее первая отрисовка. Но как только в приложении появляется больше двух-трёх экранов с состоянием, React с готовым SDK экономит время именно за счёт хуков вместо ручной синхронизации с window.Telegram.WebApp.
Можно ли открыть Mini App просто в браузере, без Telegram?
Технически страница откроется, но initData и данные пользователя будут пустыми. Для полноценного тестирования нужен реальный запуск через Telegram — десктопную или мобильную версию.
Обязательно ли делать бэкенд для Mini App на React?
Нет, если приложению не нужна валидация пользователя на сервере или хранение данных. Для визиток, калькуляторов и простых интерфейсов достаточно фронтенда без бэкенда.
Почему Telegram не открывает Mini App после деплоя?
Чаще всего домен в BotFather не обновлён или указан без https://. Проверь Menu Button в настройках бота — там должен быть точный HTTPS-адрес.
Какая версия @telegram-apps/sdk-react актуальна сейчас?
На момент публикации — 3.3.9. Библиотека активно развивается, часть внутренних пакетов переезжает под неймспейс @tma.js, стоит сверяться с changelog перед обновлением.
Nужен ли Tailwind CSS для Mini App или хватит обычного CSS?
Не обязателен. Tailwind ускоряет вёрстку за счёт классов прямо в разметке, но для маленького приложения на 2-3 экрана обычный CSS-модуль справится не хуже.
Работает ли haptic feedback на десктопной версии Telegram?
Нет, вибрация доступна только на мобильных устройствах с соответствующим железом. На десктопе вызов метода просто не даст эффекта, ошибки при этом не будет.
Сколько стоит деплой на Vercel для такого проекта?
Бесплатный тариф Vercel покрывает и фронтенд, и простую серверную функцию для валидации initData. Платный план понадобится только при заметном росте трафика или необходимости кастомных доменов сверх лимита.
Если тема Mini App только начинается для тебя — сначала загляни в гайд по Telegram Mini Apps без App Store, там разобраны форматы запуска и ограничения платформы. Для самой разработки часть команды VibeCoderz пишет код в связке с Cursor — автодополнение по хукам SDK экономит минуты на каждом экране. Полный список инструментов для вайбкодинга — в каталоге AI IDE.
Источники: официальная документация Telegram Mini Apps, страница пакета @telegram-apps/sdk-react на npm, шаблон Telegram-Mini-Apps/reactjs-template на GitHub.
Если нужна помощь с архитектурой конкретного продукта на React или деплоем — запишись на консультацию к Максиму.
Обновлено: август 2026.