Telegram Mini App: полный гайд по созданию Web App с нуля

Вас обманывают с первых строк: как на самом деле заставляют платить за создание Telegram Mini App?

Покров спал. Notcoin и Hamster Kombat доказали простую истину: в криптобуме зарабатывают не те, кто стирает пальцы о экран, а те, кто эти приложения создаёт.

Заработали единицы. Слили всё — тысячи. Но часть таперов сделала «умный» вывод: тапать за копейки больше не хочется, пора запускать свой Mini App. И моментально превратилась в мамонтов второй волны.

И тут сценарий стандартный...

Заказать у студии. Простой бот без базы данных — 5–15 тысяч рублей. Mini App с бэкендом и минимальной логикой — от 30 до 100+ тысяч. Хотите TON-платежи, реферальную систему и красивый UI — готовьте 150–300 тысяч. Вам продают не технологическую магию, а стеклянные бусы с наценкой в 500% за умные слова в договоре — потому что 80% этого кода Джун сгенерировал в ChatGPT за два вечера.

Идти на конструктор. Подсесть на иглу абонентской платы. Конструктор — это съёмная квартира с правом выселения за пять минут: завтра хозяин поднимет тариф, и вы поймёте, что проект вам даже не принадлежит.

Открыть Гугл или Ютуб. Забить «как создать Mini App бесплатно» и послушно завести аккаунты в десяти сервисах по партнёркам автора.

Во всех трёх случаях в вас видят не будущего фаундера, а дойную корову на новом витке всё той же игры.

Бесплатный только сыр

Забейте в поиск «как создать Telegram Mini App». Увидите десятки глянцевых гайдов: «С нуля», «Бесплатно», «Без опыта».

Бесплатен там только текст.

Вам сразу предлагают арендовать VPS за пару тысяч рублей в месяц для скрипта на три строчки. Зачем? Потому что облачный провайдер платит автору гайда 20–30% комиссии с каждого вашего платежа. Каждый месяц.

Автору гайда побоку, взлетит ваш «хомяк» или сдохнет через неделю. Вы ещё не получили ни одного пользователя, а он уже гарантированно получает пассивный доход с вашей доверчивости.

Умножьте это на десять тысяч таких же новичков, как вы, — и окажется, что инструкция по созданию приложения куда прибыльнее самого приложения. Ваш Mini App может вообще не взлететь. Сервисы вокруг него уже заработали.

Вам продают не приложение. Вам продают список подписок

Вам внушают, что даже для примитивного приложения нужны: домен, облачная база, Redis, CDN, сервисы авторизации и аналитики.

Интересы автора инструкции и ваши не совпадают. Вам нужен работающий Mini App. Ему нужно, чтобы вы кликнули по пяти реферальным ссылкам.

«Бесплатно» — самое лживое слово в нише

Диалог новичка с типичной инструкцией выглядит так.

— Зачем мне база данных именно этого сервиса?

— Так правильно.

— А хостинг обязательно платный?

— Так делают все.

— А без Redis точно никак?

— Он нужен для производительности.

Это не ответы, это заговаривание зубов. В вас запихивают чужие сервисы просто потому, что вы не знаете разницы между хостингом и доменом. Доверие новичка — самый дешёвый в добыче и самый дорогой в продаже ресурс.

Сколько это стоит на самом деле

Для запуска Mini App на первые 1 000 пользователей нужно ровно четыре вещи: код приложения, который пишется с помощью нейросетей за вечер; бесплатный тариф любого Node.js-хостинга; база SQLite в одном файле вместо отдельного PostgreSQL-сервера; память процесса вместо Redis.

Итоговая стоимость запуска — 0 рублей.

Тот же проект по «экспертному» гайду — абонентская плата за кучу сервисов ещё до первого реального юзера. За воздух.

Вам продают маркетинговый булшит

Вам впаривают «промышленную архитектуру» под проект, в котором зарегистрирована ваша мама и три тестовых бота. Redis, кластер PostgreSQL, CDN и rate limiting на старте — это не золотой стандарт. Это способ вытащить из вас деньги до того, как вы поймёте, что идея не работает.

«Поставь Node.js и запусти бота» — звучит просто и не продаётся.

«Настройте production-ready инфраструктуру с PostgreSQL и Redis» — звучит солидно и позволяет обвешать вас реферальными ссылками.

За железо и трафик нужно платить только тогда, когда появляется реальный трафик. Платить за инфраструктуру до первого юзера — это клиника.

Хороший разработчик решает проблему. Инфопаразит — продаёт список чужих подписок под видом решения.

Ниже — гайд, построенный вокруг результата, а не вокруг партнёрских отчислений.

Сначала разбираем, из чего состоит Mini App, и собираем его руками за ноль рублей. Подключать платные инструменты будете только тогда, когда бесплатные начнут трещать по швам.

И ещё один момент, пока не начали. То, что вы соберёте по этому гайду, — не «Hello World» и не голый каркас на десять строк, которые обычно раздают бесплатно, чтобы дальше продать вам «настоящую» версию. Это полноценная кликер-игра: очки, энергия, уровни, апгрейды, ежедневные награды, задания трёх типов, реферальная система и подключение TON-кошелька — всё уже работает. Вся игровая экономика — скорость восстановления энергии, стоимость улучшений, размер реферальных бонусов, пороги уровней — вынесена в один файл с настройками, отдельно от логики. Вам не нужно лезть в код компонентов, чтобы подкрутить баланс: меняете число — меняется экономика игры. И на этом же движке при желании можно собрать куда более сложную игру — база для этого уже заложена. Про настройку экономики и монетизацию — отдельно, в Шагах 12 и 18.

🖥️ ШАГ 1. Устанавливаем необходимые программы

Три программы, без которых дальше никуда. Ставим по порядку и ничего не пропускаем — половина проблем новичков на следующих шагах решается одной фразой «а вы точно перезапустили редактор после установки?».

1.1. Visual Studio Code

Что это и зачем?

Представьте очень умный текстовый редактор: подсвечивает ошибки в коде, подсказывает, что писать дальше, показывает файлы проекта деревом слева. Это и есть VS Code — бесплатный редактор от Microsoft. В нём будет происходить вообще всё: от правки текста до запуска команд.

Скачайте с официального сайта: code.visualstudio.com — кнопка Download for Windows (или для вашей ОС) на первом же экране.

Установите с настройками по умолчанию — просто нажимайте «Далее», ничего не переключая, — и запустите программу.

1.2. Устанавливаем Git

Что такое Git и зачем он новичку?

Git — это «машина времени» для кода. Каждое сохранённое изменение — это снимок проекта, к которому всегда можно вернуться. Именно через Git вы скачаете чужой проект себе на компьютер (это называется «клонировать»), сохраните свои изменения, отправите их на GitHub и, если что-то сломается, сможете откатиться на версию, которая ещё работала.

Без Git не получится ни скачать шаблон из этого гайда, ни задеплоить его на Vercel — это не опциональный инструмент для «продвинутых», а обязательный на каждом шаге дальше.

Скачайте: git-scm.com — кнопка Download for Windows на главной странице.

Установите с настройками по умолчанию — в мастере установки ничего переключать не нужно, все значения там уже осмысленные. После установки обязательно перезапустите VS Code, если он был открыт: программы, установленные во время его работы, редактор может не увидеть, пока его не перезапустить.

1.3. Проверяем Git

Здесь мы впервые открываем терминал. Это не «хакерский» инструмент — это просто способ давать компьютеру команды текстом вместо кликов мышкой.

В VS Code откройте: Терминал → Новый терминал (или сочетание клавиш Ctrl+`). Внизу экрана появится тёмная полоса с курсором — это и есть терминал.

Напечатайте и нажмите Enter:

git --version

Вы должны увидеть что-то вроде git version 2.50.0 — конкретная версия у вас может отличаться, это нормально, важно, чтобы команда вообще ответила версией, а не ошибкой.

Если написано git is not recognized as an internal or external command... — это самая частая ошибка новичков ровно на этом шаге: Windows пока не видит установленный Git. Лечится одинаково — закройте VS Code полностью (не просто вкладку терминала, а саму программу), убедитесь, что установка Git действительно завершилась, откройте VS Code заново и повторите проверку.

1.4. Устанавливаем Node.js

Проект написан на JavaScript/TypeScript, а выполняется через Node.js — среду, которая умеет запускать такой код не в браузере, а прямо на компьютере (и позже — на сервере при деплое). Вместе с Node.js автоматически ставится npm — менеджер пакетов, программа, которая скачивает и устанавливает библиотеки, написанные другими людьми и используемые в проекте, чтобы вам не писать всё с нуля.

Скачать: nodejs.org — берите версию с пометкой LTS (Long Term Support, самая стабильная), а не «Current».

Установите с настройками по умолчанию и снова перезапустите VS Code.

1.5. Проверяем Node.js и npm

Снова откройте терминал VS Code и введите по очереди, нажимая Enter после каждой строки:

node --version
npm --version

Пример нормального ответа:

v20.14.0
10.7.0

Цифры версий у вас почти наверняка будут другими — это ожидаемо и не проблема. Важно, чтобы обе команды отработали без ошибок.

✅ Проверка первого этапа

На этом этапе без ошибок должны отвечать git --version, node --version, npm --version. Если хотя бы одна команда не работает — не идите дальше. Вернитесь к соответствующему подпункту и переустановите программу.

И важный момент для новичков: если у вас что-то не получилось — это не значит, что вы сделали что-то неправильно и тем более не значит, что инструкция не работает. У каждого компьютера могут быть свои особенности: версия Windows, права доступа, настройки системы, уже установленные программы и множество других мелочей.

Если получили ошибку, сразу ищите её текст в Google или отправьте ошибку в ChatGPT. Лучше всего просто скопировать сообщение об ошибке целиком, а не пытаться пересказать его своими словами.

Если ChatGPT предлагает выполнить какую-то команду — сначала убедитесь, что понимаете, что она делает. Если не понимаете, прямо спросите его: «Объясни мне, что делает эта команда и безопасно ли её выполнять».

И очень прошу: если вы застряли на каком-либо пункте, напишите об этом в комментариях под статьёй. Желательно указать:

• на каком шаге возникла проблема;
• какую команду вы выполняли;
• какой текст ошибки получили;
• какая у вас операционная система;
• как в итоге удалось решить проблему.

Это важно не только для вас. Я смотрю на эту инструкцию глазами человека, который профессионально работает с кодом и компьютером, поэтому некоторые очевидные для меня вещи могут оказаться совершенно неочевидными для человека, который впервые устанавливает Git или Node.js.

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

Поэтому не пропускайте проблему молча и не бросайте установку. Сначала разберитесь с ошибкой — и только потом переходите дальше.

Я бы даже оставил последнюю фразу отдельным акцентом:

Не существует «глупых» ошибок. Если вы застряли — скорее всего, этот момент просто недостаточно подробно объяснён. Напишите об этом.

🐙 ШАГ 2. Создаём свой GitHub

Теперь понадобится аккаунт на GitHub — это площадка, где хранится код проектов и где будет храниться ваша собственная копия этого приложения.

Если аккаунт уже есть — переходите к следующему пункту. Если нет — откройте github.com, нажмите Sign up, укажите почту, придумайте пароль и username, подтвердите почту письмом. Это бесплатно и займёт пару минут.

🔐 2.1. Почему ваш репозиторий должен быть Private

Это один из самых важных моментов всей инструкции — не пролистывайте его по диагонали.

Свою рабочую копию проекта вы будете создавать как Private Repository — закрытый репозиторий, видимый только вам. Дальше в проекте появятся ваши собственные секреты: BOT_TOKEN (это полный доступ к вашему боту), DATABASE_URL (доступ к вашей базе данных с пользователями), TONCENTER_API_KEY и другие настройки.

Я специально настроил для вас файл .gitignore — чтобы защитить вас от случайной отправки чего-то лишнего на GitHub. Он говорит Git: «файлы .env и .env.local никогда не отправляй в репозиторий, даже если тебя явно не попросят». Можете открыть этот файл в VS Code и посмотреть сами — там прямо прописаны .env и .env.local.

Но .gitignore — не повод расслабляться и забыть про безопасность. Новичок вполне может случайно создать другой файл с секретом и назвать его иначе, отредактировать .gitignore и что-то из него убрать, вставить ключ прямо в код вместо переменной окружения, выполнить Git-команду не в той папке. Поэтому нужна вторая, более грубая линия защиты — сам репозиторий должен быть закрыт для посторонних глаз в принципе, вне зависимости от того, что конкретно в нём лежит.

🔒 Ваш рабочий репозиторий должен быть Private. Даже если исходный шаблон лежит в открытом репозитории — ваша личная рабочая копия, где появятся реальные секреты, обязана быть закрытой.

📥 2.2. Создаём пустой приватный репозиторий

1. Откройте github.com/new
2. Repository name — любое имя, например my-telegram-app
3. Visibility — обязательно переключите на 🔒 Private
4. Ничего не добавляйте — ни README, ни .gitignore, ни лицензию. Репозиторий должен остаться полностью пустым, иначе первый пуш из локальной копии превратится в конфликт
5. Нажмите Create repository

GitHub откроет пустую страницу с инструкцией «…or push an existing repository from the command line» — она пригодится буквально через минуту, не закрывайте вкладку.

💻 ШАГ 3. Скачиваем проект на компьютер

3.1. Клонируем исходный проект

За основу возьмём готовый шаблон — открытый репозиторий с этим самым Mini App (кликер с очками, энергией, уровнями, апгрейдами, заданиями, рефералкой и TON Connect), на примере которого построен весь этот гайд:

https://github.com/Exclusiveprofox/taptap.git

Скачивать архивом ничего не нужно — именно для этого и существует Git: команда clone копирует репозиторий целиком, со всей структурой папок, прямо вам на диск, вместе с историей изменений.

Если позже захотите взять за основу какой-то другой публичный проект — принцип везде одинаковый: на странице репозитория на GitHub нажмите зелёную кнопку Code, вкладку HTTPS, и скопируйте адрес вида https://github.com/АВТОР/НАЗВАНИЕ.git.

Создайте на компьютере папку для проектов, например Документы/Projects, и откройте именно её в VS Code: Файл → Открыть папку.

В терминале VS Code выполните:

git clone https://github.com/Exclusiveprofox/taptap.git my-telegram-app
cd my-telegram-app

Первая строка скачивает проект в папку my-telegram-app, вторая — переводит терминал внутрь этой папки. Все следующие команды нужно выполнять именно оттуда.

3.2. Отвязываем от исходного репозитория и подключаем свой

У скачанной папки всё ещё «в памяти» исходный репозиторий — если запушить прямо сейчас, изменения улетят не туда (точнее, никуда: у вас просто нет туда прав на запись). Переключаем адрес на ваш собственный пустой приватный репозиторий из Шага 2.2:

git remote remove origin
git remote add origin https://github.com/ВАШ_USERNAME/my-telegram-app.git
git push -u origin main

Замените ВАШ_USERNAME на свой логин на GitHub, а my-telegram-app — на имя, которое вы дали репозиторию в Шаге 2.2.

Если Git ругается, что ветка называется не main, а master — используйте master вместо main в последней команде.

🎉 Что произошло?

Исходный публичный репозиторий (taptap)
            ↓ (git clone)
     Ваш компьютер
            ↓ (git push в новый пустой репозиторий)
   Ваш Private Repository на GitHub

История коммитов исходного проекта останется у вас локально — это не проблема, ей никто, кроме вас, не пользуется. А на GitHub теперь лежит только ваша приватная копия, никак не связанная с оригиналом.

С этого момента работаем со своей копией — исходный репозиторий вам больше не понадобится.

3.3. Проверяем проект

В левой части VS Code (панель Explorer) вы должны увидеть дерево файлов проекта: папки app, components, utils, prisma, файлы package.json, .gitignore и другие. Ничего пока не удаляйте и не переносите — просто убедитесь, что всё на месте.

📦 ШАГ 4. Устанавливаем зависимости

В терминале VS Code убедитесь, что вы находитесь внутри папки проекта (в строке терминала должно быть что-то вроде ...\my-telegram-app>), и выполните:

npm install

Что при этом происходит: команда открывает package.json, читает оттуда список библиотек, нужных проекту (Next.js, Prisma, TonConnect и другие), и скачивает их с серверов npm. Это может занять от 30 секунд до нескольких минут — зависит от скорости интернета.

После выполнения появится папка node_modules — в ней буквально сотни мегабайт чужого кода, который использует ваш проект. Не отправляйте её на GitHub: она создаётся автоматически командой npm install у любого, кто клонирует проект, и уже прописана в .gitignore, так что случайно она туда и не попадёт.

Если видите красный текст с npm error — чаще всего это либо проблема с интернетом (просто повторите команду), либо Node.js всё же не установился до конца (вернитесь к Шагу 1.5 и перепроверьте).

▶️ ШАГ 5. Первый запуск

Проверим, что проект вообще запускается, ещё до настройки базы данных:

npm run dev

Если всё в порядке, в терминале появится строка вида Local: http://localhost:3000 — это адрес, по которому получится открыть приложение в браузере на следующих шагах.

⚠️ Если приложение не запускается — не начинайте сразу менять код, сначала прочитайте текст ошибки в терминале целиком, обычно там прямо написано, чего не хватает. На этом этапе почти всегда дело в том, что мы ещё не настроили базу данных и переменные окружения — это нормально, мы как раз идём к этому в следующих шагах. Сейчас мы просто убеждаемся, что сам проект и Node.js в целом работают.

🗄️ ШАГ 6. Создаём базу данных (MongoDB Atlas)

Теперь нужна база данных — она будет хранить всё, что происходит в приложении: пользователей, их прогресс, энергию, уровни, задания, рефералов, начисленные очки. Без базы данных приложение — просто пустая оболочка, которая ничего не запоминает между заходами.

Используем MongoDB Atlas — облачную MongoDB с бесплатным тарифом, которого с запасом хватает на старт. Ничего ставить на компьютер не нужно, база будет жить в облаке.

6.1. Регистрируемся в MongoDB Atlas

Перейдите на mongodb.com/atlas и зарегистрируйтесь — быстрее всего через Google-аккаунт, в один клик.

[Скриншот: страница регистрации MongoDB Atlas — вставить новый]

6.2. Создаём кластер

Кластер — это, по сути, ваш личный «сервер» базы данных внутри MongoDB Atlas.

1. После регистрации нажмите Build a Database
2. Выберите бесплатный тариф M0 Free — этого достаточно для старта и первых тысяч пользователей, платить не нужно
3. Выберите регион ближе к вашей аудитории (для СНГ обычно подходит Frankfurt)
4. Нажмите Create

[Скриншот: создание кластера M0 Free — вставить новый]

6.3. Настраиваем доступ

MongoDB Atlas по умолчанию не пускает вообще никого — это защита по умолчанию, её нужно осознанно приоткрыть в двух местах.

1. Database Access → Add New Database User — задайте логин и пароль для доступа к базе (это не логин от самого Atlas, а отдельная учётка именно для подключения) и обязательно сохраните их куда-нибудь — они понадобятся буквально через минуту для строки подключения
2. Network Access → Add IP Address → Allow Access from Anywhere (добавит адрес 0.0.0.0/0) — точный IP-адрес serverless-хостинга (Vercel) заранее не известен и к тому же может меняться, поэтому проще разрешить доступ отовсюду; сама база при этом всё равно защищена логином и паролем из предыдущего пункта

[Скриншот: Network Access — Allow Access from Anywhere — вставить новый]

6.4. Получаем строку подключения

1. На странице кластера нажмите Connect → Drivers
2. Скопируйте строку вида:

mongodb+srv://username:password@cluster0.xxxxx.mongodb.net/?retryWrites=true&w=majority

1. Замените <password> на пароль пользователя базы из Шага 6.3 — угловые скобки < > тоже нужно убрать, оставить только сам пароль
2. Перед знаком ? допишите имя базы данных, например /my-telegram-app — получится ...mongodb.net/my-telegram-app?retryWrites=...

[Скриншот: копирование строки подключения — вставить новый]

Сохраните готовую строку — она понадобится буквально в следующем шаге.

⚙️ ШАГ 7. Настраиваем переменные окружения

Переменные окружения — это настройки и секреты проекта, которые хранятся не в самом коде, а в отдельных файлах рядом с ним. Смысл в том, что код одинаковый у всех, кто клонирует проект, а вот BOT_TOKEN и пароль от базы — у каждого свои, и вписывать их прямо в код нельзя: тогда они улетят на GitHub вместе с остальным кодом.

В проекте два таких файла: .env — секреты сервера, которые никогда не должны попасть в браузер пользователя, и .env.local — публичные настройки, к которым может обращаться клиентский код (браузер).

7.1. Файл .env

Создайте в корне проекта (там же, где лежит package.json) новый файл с именем .env:

DATABASE_URL="ваша строка подключения к MongoDB из Шага 6.4"
BOT_TOKEN="токен вашего Telegram-бота"      # получим в Шаге 8
BYPASS_TELEGRAM_AUTH=true                    # true — для тестов на компьютере, без реального Telegram
NODE_ENV=production                          # ставится только при деплое на Vercel, во время разработки не трогайте
TONCENTER_API_KEY=                           # получим в Шаге 11

7.2. Файл .env.local

Рядом создайте .env.local:

NEXT_PUBLIC_BYPASS_TELEGRAM_AUTH=true
NEXT_PUBLIC_BOT_USERNAME="username_бота_без_собаки"
NEXT_PUBLIC_APP_URL_SHORT_NAME="короткое_имя_приложения"

Обратите внимание на приставку NEXT_PUBLIC_ — именно она делает переменную видимой в браузере пользователя. Никогда не добавляйте её к паролям и токенам, только к тому, что действительно не страшно показать кому угодно.

Про NEXT_PUBLIC_BOT_USERNAME и NEXT_PUBLIC_APP_URL_SHORT_NAME не переживайте, если пока непонятно, откуда их взять — вы получите оба значения буквально через пару минут, в следующем шаге, когда будете создавать бота в BotFather.

🤖 ШАГ 8. Создаём Telegram-бота и Mini App

Здесь ничего не «скачивается» в привычном смысле — весь этот шаг делается внутри самого Telegram, через переписку со служебным ботом. Ни файлов, ни установщиков.

8.1. Создаём бота через BotFather

Всё начинается с одного бота — именно он станет «обёрткой», через которую Telegram будет открывать ваш Mini App.

1. Откройте Telegram (на телефоне или в десктопном приложении) и в поиске найдите @BotFather — это официальный служебный бот Telegram для создания других ботов, он уже есть внутри Telegram, отдельно ставить ничего не нужно.
2. Нажмите Start (или отправьте /start), затем отправьте команду /newbot.
3. BotFather спросит имя бота — то, что видят пользователи в чате (например «Мой Кликер»), можно на русском, с пробелами.
4. Затем спросит username — техническое имя для ссылки вида t.me/username, обязательно латиницей и обязательно заканчивается на bot, например my_clicker_bot.
5. В ответ придёт сообщение с токеном вида 123456789:AAExxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx — скопируйте его целиком и вставьте в BOT_TOKEN в .env.

⚠️ Токен бота — это пароль. У кого есть токен, тот полностью управляет ботом от вашего имени. Никогда не публикуйте его и не коммитьте в открытый репозиторий.

8.2. Создаём Mini App

Теперь превращаем обычного бота в бота с полноценным веб-приложением внутри — это отдельная привязка, которую тоже настраивает BotFather.

1. В том же чате с BotFather отправьте /newapp.
2. Выберите своего бота из списка (если бот один — вариант будет тоже один).
3. Title — заголовок приложения, который увидит пользователь при запуске.
4. Description — короткое описание в одно-два предложения: что делает приложение.
5. Photo — обложка, строго 640×360 пикселей, PNG или JPG. Готовой картинки под рукой может не быть — быстро собрать такую можно бесплатно в Canva или Figma под этот точный размер; при желании обложку всегда можно заменить позже через /myapps → выбрать приложение → Edit Photo.
6. GIF — короткая анимация-демо, необязательна, чтобы пропустить — отправьте /empty.
7. Web App URL — адрес, по которому будет открываться приложение. Задеплоенного сайта у нас пока нет (дойдём до этого в Шаге 14), поэтому сейчас впишите любую заглушку, например https://example.com — вернёмся сюда в Шаге 15 и подставим настоящий адрес с Vercel.
8. Short name — короткое имя латиницей (например app), из него собирается прямая ссылка вида t.me/имя_бота/short_name. Сохраните его в NEXT_PUBLIC_APP_URL_SHORT_NAME в .env.local.

Username бота (без @, то, что заканчивается на bot) сохраните в NEXT_PUBLIC_BOT_USERNAME — оно тоже понадобится в .env.local.

Как потом проверить, что всё сработало: в чате с ботом появится синяя кнопка меню рядом с полем ввода — по ней и открывается Mini App. Нажимать её сейчас ещё рано, ссылка временная — вернёмся к живой проверке в Шаге 10 (локальный запуск) и в Шаге 17, когда сайт уже будет задеплоен на настоящий адрес.

🧬 ШАГ 9. Готовим базу данных: Prisma

Prisma — это ORM: слой между вашим кодом и базой данных, который позволяет писать prisma.user.findUnique(...) вместо сырых запросов к MongoDB. Схема базы — какие поля есть у пользователя, у задания и так далее — описана в файле prisma/schema.prisma.

npx prisma generate

Эта команда читает схему в prisma/schema.prisma и генерирует Prisma Client — код, через который приложение общается с MongoDB. Без этой команды импорт @prisma/client в коде просто не заработает.

npx prisma db seed

Заполняет базу стартовыми данными — например, список заданий по умолчанию (подписаться на канал, посмотреть видео и так далее). Что именно засеивается и в каком количестве, можно посмотреть и изменить в файле prisma/seed.ts — там обычный массив объектов, редактируется как таблица.

[Скриншот: успешный вывод prisma generate и prisma db seed — вставить новый]

▶️ ШАГ 10. Запускаем локально

npm run dev

Откройте в браузере http://localhost:3000. Благодаря BYPASS_TELEGRAM_AUTH=true (и его паре NEXT_PUBLIC_BYPASS_TELEGRAM_AUTH=true) приложение запустится прямо в браузере, без необходимости открывать его через настоящий Telegram на каждый чих. Это сильно ускоряет разработку — не нужен ни ngrok, ни обновление ссылки в BotFather при каждом изменении кода.

⚠️ Важно. BYPASS_TELEGRAM_AUTH — это исключительно для разработки. Перед тем как выкладывать проект в продакшен, эта переменная должна быть выключена (false) или вовсе убрана из настроек на Vercel — иначе Telegram-авторизация не будет проверяться по-настоящему, и вашим приложением от имени случайного пользователя сможет пользоваться кто угодно.

Проверку в настоящем Telegram оставим на потом — она будет в Шаге 16, уже на задеплоенном сайте. Сейчас достаточно того, что всё работает в браузере.

💎 ШАГ 11. Подключаем TON: получаем API-ключ Toncenter

Чтобы приложение могло проверять TON-транзакции — например, платежи через TON Connect — ему нужен ключ доступа к Toncenter, сервису-«шлюзу» в блокчейн TON.

1. Откройте @tonapibot (или @toncenter) в Telegram

1. Запустите мини-приложение Toncenter, нажмите Create API Key

1. Укажите любое имя ключа, выберите сеть Mainnet (это основная, «настоящая» сеть TON, не тестовая), нажмите Create

1. Скопируйте ключ целиком и вставьте его в TONCENTER_API_KEY в .env

🔐 ШАГ 12. Админ-панель и настройка игровой экономики

В отличие от многих шаблонов, здесь админ-панель работает только локально — это осознанное решение ради безопасности: её физически нельзя случайно оставить открытой на проде, потому что на проде она попросту не собирается.

1. Добавьте в .env: ACCESS_ADMIN=true
2. Запустите проект локально (npm run dev)
3. Откройте http://localhost:3000/admin

Что можно делать в админке:

• экспортировать данные пользователей (Export User Data) — выбираете нужные поля и выгружаете users_export.json, экспорт постраничный, справляется с большими базами;
• управлять заданиями (Manage Tasks) — создавать и редактировать задания трёх типов: подписка на канал (TELEGRAM — бот должен быть админом или хотя бы участником канала, иначе проверка не сработает), переход по ссылке (VISIT — засчитывается по факту клика), приглашение нужного числа друзей (REFERRAL — засчитывается автоматически);
• добавлять новые картинки для заданий — файл кладётся в images/, импортируется в начале images/index.ts и добавляется в объект imageMap в конце этого же файла.

[Скриншот: админ-панель localhost:3000/admin — вставить новый]

⚠️ Админ-панель рассчитана на доверенного человека с полным доступом к системе — она специально работает только на localhost и недоступна на задеплоенном сайте.

12.1. Настраиваем игровую экономику без единой строчки логики

Отдельный и важный момент, который легко упустить: вся баланс-настройка игры вынесена из компонентов в один файл — utils/consts.ts. Не нужно лезть в код игрового цикла, чтобы что-то подкрутить — меняете число в этом файле, и экономика игры меняется сама, без риска что-то сломать в логике.

Что там можно менять:

• MAX_ENERGY_REFILLS_PER_DAY — сколько раз в сутки пользователь может бесплатно восполнить энергию (по умолчанию 6);
• ENERGY_REFILL_COOLDOWN — сколько времени должно пройти между такими восполнениями (по умолчанию час);
• REFERRAL_BONUS_BASE и REFERRAL_BONUS_PREMIUM — сколько очков получает пользователь за приглашённого друга, обычного и с Telegram Premium;
• DAILY_REWARDS — массив наград за ежедневный вход подряд, по порядку дней;
• LEVELS — пороги очков для каждого уровня и размер бонуса за друга на этом уровне;
• multitapUpgradeBasePrice, energyUpgradeBasePrice, mineUpgradeBasePrice и их коэффициенты — стартовая цена и то, насколько дорожает каждое следующее улучшение.

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

🚀 ШАГ 13. Заливаем на Vercel

13.1. Создаём проект

1. Зайдите на vercel.com, войдите через GitHub
2. Add New → Project → выберите ваш приватный репозиторий

1. Framework Preset определится сам (Next.js), остальные настройки сборки не трогайте

13.2. Добавляем переменные окружения

Добавьте все переменные из .env и .env.local — все, кроме NODE_ENV, который сам выставится в production.

1. Нажмите Deploy

13.3. Обновляем production-адрес

После первого деплоя скопируйте адрес вида https://your-app.vercel.app. Если в вашей копии проекта используется NEXT_PUBLIC_APP_URL — обновите его в настройках Vercel (Settings → Environment Variables) на этот адрес, без слэша в конце, и передеплойте (Deployments → ⋯ → Redeploy).

📱 ШАГ 14. Обновляем ссылку в BotFather

В BotFather:

/myapps
Выберите приложение
Edit Web App URL
Вставьте адрес с Vercel

Теперь Mini App открывается по кнопке в вашем боте и указывает на настоящий, задеплоенный сайт.

💳 ШАГ 15. TON Connect

Чтобы пользователи могли подключать TON-кошелёк, нужен манифест — файл, который описывает ваше приложение кошелькам вроде Tonkeeper при запросе подключения. Создайте public/tonconnect-manifest.json:

{
  "url": "https://your-app.vercel.app",
  "name": "Название вашего приложения",
  "iconUrl": "https://your-app.vercel.app/icon-128.png",
  "termsOfUseUrl": "https://your-app.vercel.app/terms",
  "privacyPolicyUrl": "https://your-app.vercel.app/privacy"
}

Не забудьте положить иконку 128×128 в public/icon-128.png, закоммитить и запушить изменения — Vercel передеплоит сайт автоматически:

git add .
git commit -m "Add TON Connect manifest"
git push

✅ ШАГ 16. Проверяем всё вместе

• Откройте бота в Telegram, нажмите кнопку запуска приложения
• Пройдите игровую механику, убедитесь что очки начисляются
• Проверьте, что задания выполняются и засчитываются
• Подключите TON-кошелёк через TON Connect
• Пригласите второй аккаунт по реферальной ссылке, проверьте начисление бонуса

[Скриншот: тестирование в настоящем Telegram — вставить новый]

💰 ШАГ 17. Как на этом зарабатывать

Раз уж приложение бесплатное и полностью ваше — стоит сразу понимать, как оно может приносить деньги, а не оставаться развлечением для десятка друзей.

Реклама за восполнение энергии. Самый очевидный и самый рабочий вариант в этой нише — показывать rewarded-рекламу (ролик, который пользователь смотрит добровольно за награду) в обмен на внеочередное восполнение энергии. В проекте уже есть готовая точка входа для этого — эндпоинт app/api/refill-energy/route.ts, который сейчас восполняет энергию бесплатно, ограничиваясь только MAX_ENERGY_REFILLS_PER_DAY и ENERGY_REFILL_COOLDOWN из Шага 12.1. Логика подключения конкретной рекламной сети зависит от того, с кем вы будете работать — у каждой сети свой SDK и своя проверка досмотра ролика, — но сам механизм «досмотрел ролик → получил дополнительное восполнение сверх дневного лимита» встраивается ровно в это место.

Откуда берётся реклама в Mini App. Здесь стоит сразу понимать специфику ниши: основная реклама в Telegram Mini App — это казино, букмекерские конторы и прочая «серая» тематика, которую не пускают в обычные мобильные сторы. Именно поэтому ставки за показ в этой нише заметно выше среднего по рынку мобильной рекламы — рекламодателям больше особо негде размещаться, и они готовы платить за это дороже.

Развитие движка. Ничего не мешает не останавливаться на кликере: уровни, апгрейды, задания, рефералка и TON-платежи — это уже полноценный игровой каркас, на котором можно достроить куда более сложную игру, не переписывая всё с нуля.

🧯 Если что-то не работает

• «Failed to connect to database» — проверьте DATABASE_URL целиком: правильный пароль без угловых скобок < >, правильное имя пользователя базы, и что в Network Access разрешён доступ отовсюду (0.0.0.0/0) — это самая частая причина именно у новичков, пропустивших Шаг 6.3
• git is not recognized или npm is not recognized — программа установлена, но VS Code её не видит; закройте VS Code полностью и откройте заново (см. Шаг 1.3)
• Приложение не открывается в Telegram, но работает на localhost — проверьте, что Web App URL в BotFather совпадает с реальным адресом на Vercel, а BYPASS_TELEGRAM_AUTH выключен в продакшене
• Ошибка сборки на Vercel — убедитесь, что добавлены все переменные окружения из .env и .env.local, и попробуйте собрать проект локально командой npm run build — там ошибка читается куда понятнее, чем в логах Vercel

Вот и всё. Никаких скрытых абонентских плат и ни рубля на инфраструктуру до первого реального пользователя — только код, бесплатный тариф MongoDB Atlas и ваш собственный кошелёк для TON. Дальше — ваше дело: хотите просто поиграть с друзьями — играйте, хотите зарабатывать на рекламе — подключайте её по Шагу 17, хотите свою игру — движок уже под рукой.