Единый Next.js‑проект для Telegram-бота и мини‑приложения

В этой статье мы представим совершенно новый подход к разработке: использование одного проекта Next.js для одновременной реализации Telegram Bot и Mini App, достигая истинного единого кода, единого развертывания, бесшовной интеграции. Вы научитесь создавать полноценную систему игровых очков, включая ежедневные бонусы за вход, реальные платежи через Telegram Stars и функции мгновенных уведомлений.

Почему стоит выбрать Next.js для унифицированной разработки Bot и Mini App?

В традиционном режиме разработчикам необходимо:

• Отдельно развертывать серверную часть бота
• Отдельно развертывать фронтенд мини-приложения
• Настраивать взаимодействие между двумя проектами
• Поддерживать два набора переменных окружения и конфигураций

С унифицированным решением Next.js вы можете:

• Управлять всеми функциями из одной кодовой базы
• Общие API-маршруты для обработки команд бота, запросов мини-приложения и платежной логики
• Единое развертывание на платформах вроде Vercel, снижая операционные расходы
• Данные естественным образом связаны, не требуя дополнительных механизмов синхронизации

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

---

Демонстрация основных функций: что можно сделать с этим проектом?

Мы создадим систему игровых очков, которая будет обладать следующими функциями:

• Ежедневные бонусы за вход: Пользователи могут получать 100 очков каждые 24 часа с отображением таймера в реальном времени.
• Платежи через Telegram Stars: Пользователи покупают очки за реальные деньги с поддержкой тестирования мгновенного возврата средств.
• Обработка команд бота: Поддержка распространенных команд, таких как /start, /help, для запуска мини-приложения в один клик.
• Отправка уведомлений в реальном времени: Уведомления через бота будут приходить при успешной оплате, завершении возврата средств и других операциях.

Вся система будет работать в одном приложении Next.js, обеспечивая полное бесшовное взаимодействие между ботом и мини-приложением.

---

Подготовка перед началом работы

Перед началом разработки вам понадобятся следующие инструменты:

1. Аккаунт Telegram: для создания бота и тестирования мини-приложения.
2. Node.js 18+: если не установлен, скачайте с nodejs.org.
3. Ngrok: для создания HTTPS-туннеля во время локальной разработки, так как Telegram требует HTTPS для Webhook и Mini App.

Как получить Ngrok

• Зарегистрируйтесь на ngrok.com (бесплатный аккаунт).
• Скачайте версию для вашей операционной системы.
• Распакуйте в отдельную папку.
• Запустите ngrok config add-authtoken <ваш_токен> для привязки аккаунта.
• После завершения настройки вы сможете запускать ngrok http 3000 из этой папки.

---

Быстрая настройка проекта (доступно за 5 минут)

1. Получение кода проекта и установка зависимостей

Полный исходный код и подробную документацию можно найти в соответствующем Telegram-канале (ссылку можно найти в описании оригинального видео).

git clone <адрес_репозитория>
cd <директория_проекта>
npm install

2. Настройка переменных окружения

В корневой папке проекта создайте файл .env.local для хранения конфиденциальной информации:

TELEGRAM_BOT_TOKEN=ваш_токен_бота
NEXT_PUBLIC_APP_URL=адрес_вашего_ngrok

Важное примечание: Убедитесь, что .env.local добавлен в .gitignore, чтобы избежать утечки токена бота.

3. Создание Telegram Bot

• Откройте Telegram и найдите BotFather.
• Отправьте /newbot для создания нового бота.
• Установите имя и имя пользователя бота (имя пользователя должно заканчиваться на bot).
• Скопируйте сгенерированный токен бота и сохраните его в .env.local.

4. Запуск Ngrok и сервера разработки

# Терминал 1: Запуск Ngrok
ngrok http 3000

# Терминал 2: Запуск сервера разработки Next.js
npm run dev

# Терминал 3: Настройка Webhook
npm run webhook:setup

Если все настроено правильно, вы увидите сообщение "Webhook set successfully".

5. Настройка кнопки меню Mini App

• Вернитесь в BotFather, отправьте /mybots и выберите вашего бота.
• Нажмите Bot Settings → Menu Button.
• Укажите URL (используйте HTTPS-адрес, полученный от Ngrok) и текст кнопки (например, "Play Game").

Теперь, когда пользователи откроют вашего бота, они увидят кнопку для запуска игры, нажав на которую, они перейдут в интерфейс мини-приложения!

---

Анализ основного кода: как бот и мини-приложение работают вместе?

Webhook-эндпойнт: центр обработки сообщений бота

Все обновления, отправляемые Telegram (команды пользователя, уведомления о платежах и т. д.), передаются через Webhook в маршрут /api/telegram/webhook.

Основные типы обрабатываемых сообщений включают:

• Команды пользователя: /start, /help и т. д.
• Предварительное подтверждение платежа: предварительная проверка после нажатия пользователем кнопки оплаты.
• Уведомление об успешном платеже: подтверждение завершения транзакции и начисления очков.
• Запросы на возврат средств: для быстрого тестирования процесса возврата в процессе разработки.

При первом отправлении команды /start бот немедленно отправляет кнопку «Запустить игру», не требуя дополнительных инструкций.

Процесс оплаты через Telegram Stars

Ключевым элементом функции оплаты является маршрут /api/buy-points:

1. Пользователь нажимает «Купить очки» в мини-приложении.
2. Вызывается Telegram Bot API для создания счета (createInvoiceLink).
3. Счет отображается в нативном платежном интерфейсе Telegram.
4. После успешной оплаты пользователя Webhook получает уведомление.
5. Система обновляет очки пользователя и отправляет сообщение с квитанцией.

Ключевая конфигурация:

• provider_token оставляем пустым (режим Telegram Stars).
• currency устанавливаем в XTR.
• prices указываются в количестве звезд (не в центах).

Бонус для разработчиков: после каждой покупки возвращается идентификатор квитанции, который вы можете немедленно использовать для тестирования возврата средств с помощью команды /refund <ID_квитанции>, без необходимости ожидания подтверждения или ручной обработки. Это чрезвычайно эффективно для тестирования реального платежного процесса.

Система ежедневных бонусов

В маршруте /api/claim-daily реализован механизм поощрения, основанный на времени:

• Записывается время последнего получения бонуса каждым пользователем.
• Проверяется, прошло ли 24 часа.
• Если 24 часа не прошли, возвращается оставшееся время до следующего получения.
• При успешном получении начисляется 100 очков и отправляется уведомление в Telegram.

На фронтенде используется компонент таймера реального времени, который обновляется каждую секунду, информируя пользователя о том, когда он сможет получить следующий бонус. Этот шаблон может быть расширен для любых игровых механик, требующих ограничения по времени (например, восстановление энергии, охлаждение при розыгрыше и т. д.).

---

Важные моменты для развертывания в продакшене

Хотя в этой демонстрации используется хранение в памяти, перед запуском реального проекта необходимо внести следующие изменения:

• База данных: Вместо хранения в памяти используйте PostgreSQL или MongoDB.
• Проверка пользователя: Проверяйте подписи данных Telegram Web App для предотвращения поддельных запросов.
• Защита от флуда: Предотвращайте злонамеренное получение очков или злоупотребление платежными интерфейсами.
• Мониторинг логов: Подключите сервисы отслеживания ошибок, такие как Sentry.
• Безопасность Webhook: Проверяйте, что запросы действительно поступают с серверов Telegram.

Рекомендуемые платформы для развертывания:

• Vercel: развертывание с нулевой конфигурацией, автоматический HTTPS.
• Heroku / Railway: подходит для сценариев, требующих долговременных соединений.
• Cloudflare Workers: решение для периферийных вычислений, глобальное ускорение.

При развертывании не забудьте обновить URL Webhook и ссылку на кнопку меню Mini App на домен вашего продакшена.

---

Часто задаваемые вопросы (FAQ)

Зачем нужен Ngrok? Нельзя просто использовать localhost?

Telegram требует использования протокола HTTPS для Webhook и Mini App, что localhost не может обеспечить. Ngrok создает общедоступный HTTPS-туннель, перенаправляя запросы на ваш локальный сервер разработки.

Как протестировать реальные платежи, не тратя деньги?

На этапе разработки вы можете купить небольшое количество Telegram Stars (от нескольких центов), а затем использовать команду /refund для мгновенного возврата средств. Это позволит протестировать платежный процесс, обратные вызовы Webhook и логику возврата средств в реальном режиме, не нуждаясь в повторных пополнениях.

Можно ли продолжать использовать хранение в памяти в производственной среде?

Категорически нет. Хранение в памяти теряет все данные при перезагрузке сервера. Необходимо использовать постоянную базу данных (например, PostgreSQL) и иметь план резервного копирования и миграции.

Каковы основные преимущества унифицированного решения Next.js?

Главное преимущество — повышение эффективности разработки и снижение затрат на обслуживание. Вам не придется:

• Управлять двумя репозиториями кода
• Беспокоиться о несогласованности данных фронтенда и бэкенда
• Настраивать сложные междоменные запросы и API-интеграцию
• Развертывать и отслеживать два сервиса отдельно

Вся логика находится в одном проекте, повышая частоту повторного использования кода и ускоряя поиск ошибок.

Подходит ли такая архитектура для масштабных приложений?

Для MVP-продуктов и приложений среднего размера она вполне подходит. Если суточная аудитория достигает миллиона пользователей, рекомендуется разделить бэкенд бота и фронтенд мини-приложения, используя архитектуру микросервисов и специализированные очереди сообщений для обработки высоких нагрузок.

---

Заключение

В ходе практической демонстрации в этой статье вы освоили ключевые навыки создания унифицированного приложения Telegram Bot + Mini App на Next.js. Такой подход к разработке поможет вам быстро проверять идеи, снижать затраты на разработку и заложить прочный фундамент для дальнейшего расширения. Приступайте к практике прямо сейчас и создайте свою собственную Telegram-игру за минимальное время!