Telegram Mini App открывает новые возможности для разработчиков, позволяя создавать интерактивные приложения прямо внутри мессенджера. В этом материале мы покажем, как с нуля собрать рабочий Mini App на React с использованием Vite и настроить ngrok-туннель для тестирования в реальном времени. Такой подход позволяет быстро видеть результаты, работать с пользовательскими данными и интегрировать функционал Telegram SDK без сложного деплоя на сервер.
Мы пройдем весь процесс пошагово: от создания стартового React-приложения, через настройку туннеля ngrok, до привязки к боту, чтобы вы получили полностью рабочий Telegram Mini App, готовый к развитию и кастомизации.
Этап 1: Создаем стартовое React-приложение
Для разработки Telegram Mini App используем современный и быстрый Vite, который отлично подходит для React. Сначала открываем терминал и создаем проект, например:
npm create vite@latest mini-app
Где mini-app — имя проекта, можно выбрать любое. После этого Vite предложит выбрать фреймворк и вариант проекта. Мы выбираем React и JavaScript, но если нужен строгий контроль типов, можно сразу подключить TypeScript. Затем переходим в папку проекта:
cd mini-app
npm install
После установки зависимостей окружение готово к разработке.
Следующий шаг — интеграция Telegram Mini App SDK:
npm install @twa-dev/sdk
В App.jsx подключаем библиотеку и настраиваем базовый функционал:
import WebApp from '@twa-dev/sdk'
import { useEffect, useState } from 'react'
import './App.css'
function App() {
const [tab, setTab] = useState("home")
useEffect(() => {
WebApp.ready()
WebApp.expand()
}, [])
const user = WebApp.initDataUnsafe?.user
return (
<div>
<h1>Мое первое Mini App для Telegram!</h1>
<p>Добро пожаловать, {user?.first_name}!</p>
<button onClick={() => setTab("home")}>Главная</button>
<button onClick={() => setTab("diary")}>Дневник</button>
{tab === "home" && <div>Главная</div>}
{tab === "diary" && <div>Дневник</div>}
</div>
)
}
export default App
Таким образом мы создаем минимальный шаблон Telegram Mini App, который уже может работать внутри мессенджера и распознавать пользователя.
Чтобы проверить проект, запускаем его командой:
npm run dev
В терминале появится локальный адрес, обычно http://localhost:5173/. Открыв его в браузере, увидим стартовый экран с заголовком. На этом этапе мы получаем рабочий шаблон для дальнейшей разработки и подготовки к подключению туннеля ngrok, чтобы тестировать приложение напрямую в Telegram.
Этап 2: Настройка ngrok туннеля
Чтобы тестировать Telegram Mini App напрямую в мессенджере, нам нужен туннель, который откроет локальный сервер в интернете. Для этого отлично подходит ngrok. Сначала скачиваем ngrok с официального сайта — для Windows это https://ngrok.com/download, для Linux можно использовать snap install ngrok.
После установки важно авторизовать ngrok через токен. Для этого регистрируемся на https://dashboard.ngrok.com/signup, копируем Auth Token и добавляем его в терминале:
ngrok config add-authtoken ТВОЙ_ТОКЕН
Теперь можем запускать туннель к локальному серверу, на котором работает наше React-приложение. Если проект стартует на порту 5173, команда будет такой:
ngrok http 5173
После запуска в терминале появится уникальный адрес вида:
Forwarding: https://subuncinated-shiftless-gertie.ngrok-free.dev -> http://localhost:5173
Эта ссылка позволяет открывать наше приложение из любого браузера и, главное, из Telegram.
Однако есть нюанс: Vite по умолчанию защищает проект от “неизвестных хостов”, и ngrok-башка может быть заблокирована. Чтобы это исправить, открываем vite.config.js в корне проекта и добавляем разрешение для хоста:
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
export default defineConfig({
plugins: [react()],
server: {
host: true, // разрешаем все хосты
strictPort: true,
allowedHosts: [
'subuncinated-shiftless-gertie.ngrok-free.dev'
]
}
})
Теперь наше React-приложение доступно по HTTPS через ngrok, и мы можем использовать ссылку для тестирования внутри Telegram.
После этих шагов локальный проект превращается в полноценный тестовый Telegram Mini App, который можно открыть на телефоне или в веб-версии Telegram и проверить работу интерфейса и SDK прямо в реальных условиях. Это крайне удобно, потому что все изменения сразу видны, а процесс разработки становится быстрым и прозрачным.
Этап 3: Создание Telegram-бота и привязка к туннелю
После того как наше React-приложение работает через ngrok, следующий шаг — создать Telegram-бота и связать его с туннелем, чтобы тестировать Telegram Mini App прямо в мессенджере.
Сначала открываем @BotFather и создаем нового бота командой:
/start
/newbot
Даем ему имя и уникальный username, который обязательно должен оканчиваться на _bot. После этого BotFather выдаст нам TOKEN — это ключ для работы с API бота, его нужно сохранить, чтобы использовать в будущем.
Теперь подключаем Mini App к боту. Заходим в BotFather, выбираем созданного бота:
/mybots → твой бот → Bot Settings → Menu Button
Выбираем Configure Menu Button и задаем параметры:
- Text: Открыть Mini App
- URL: ссылка на наш ngrok-туннель, например
https://subuncinated-shiftless-gertie.ngrok-free.dev
Важно, чтобы ссылка была HTTPS, иначе Telegram не позволит открыть приложение.
После этих настроек кнопка меню бота будет запускать наше React-приложение через туннель ngrok, превращая локальный проект в полноценный Telegram Mini App. Теперь можно тестировать интерфейс, взаимодействие с пользователем и любые функции SDK прямо в Telegram.
Благодаря такому подходу мы получаем полностью рабочий цикл разработки: сначала создаем проект на React с подключением Telegram SDK, затем настраиваем ngrok для внешнего доступа, и наконец — привязываем приложение к боту. Всё это позволяет быстро разрабатывать и тестировать Mini App без необходимости деплоя на реальный сервер.