Введение.

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

Ингредиенты.

• Vite с шаблоном React, TypeScript

• mkcert для генерации self-sign сертификата

• /etc/hosts

• @tma.js/sdk

Предусловия.

Я использую macOS для работы, так что в разных системах какие-то детали могут отличаться, если что их можно нагуглить, ну или спросить ChatGPT. Так же я использовал Bun, как пакетный менеджер (на свой страх и риск), но вы можете использовать любой другой. В остальном на процесс ничего не должно повлиять. Ну разве что убедитесь что у вас версия Telegram актуальна. Мало ли.

Создаем новый проект.

Открываем документацию Vite, и копируем команду для создания нового проекта из шаблона.

bunx create-vite tg-mini-app --template react-ts

Переходим в директорию проекта, устанавливаем зависимости, и давайте перейдем к следующему этапу.

Создаем self-sign сертификаты.

Самоподписанные сертификаты нужны нам для того, чтобы Vite мог работать через https. Это важное условие при разработке Telegram Mini App, так как домены на http не принимаются при конфигурировании бота и приложения.

Для этих целей будем использовать mkcert, утилиту для генерации локально-доверенных сертификатов с собственным центром сертификации. То есть сертификаты будут валидны и в Chrome, и в Telegram Mini App.

Я нашел неплохую инструкцию здесь на хабре, как его установить для разных ОС. Возможно что-то устарело с 2019 года, так что проверьте документацию на официальном сайте.

Кстати, тут пора определится с локальным доменом для проекта.

Я выберу: tg-mini-app.local

А тут я покажу как я делаю сертификат для этого домена. Остаемся в директории в командной строке, и запускаем команду:

mkdir -p .cert && mkcert -key-file ./.cert/localhost-key.pem -cert-file ./.cert/localhost.pem 'tg-mini-app.local'

У вас в проекте появиться директория .cert с файлами сертификатов.

Конфигурируем vite.config.ts

Вот тут начинается самое интересное, ради чего писалась эта статья. Как говорил Линус Торвальдс: "Покажи мне код". Показываю:

export default defineConfig({
  plugins: [react()],
  server: {
    port: 443,
    host: "0.0.0.0",
    hmr: {
        host: 'tg-mini-app.local',
        port: 443,
    },
    https: {
      key: fs.readFileSync('./.cert/localhost-key.pem'),
      cert: fs.readFileSync('./.cert/localhost.pem'),
    },
  },
})

Вы ожидали большего? Смотрите - react есть, основной сервер работает на https, и еще и HMR работает на https. Цель достигнута. Но есть еще несколько мелких деталей.

Открываем /etc/hosts с правами администратора. Я использовал:

sudo nano /etc/hosts

И добавил туда одну строчку:

127.0.0.1 tg-mini-app.local

Сохраняем и проверяем! Можно открыть в браузере https://tg-mini-app.local и посмотреть на результат. В браузере работает? Тогда давай настраивать бота!

Создаем и конфигурируем Telegram бота.

Создание ботов в Telegram начинается с общения с ботом BotFather. Вообще интересное название. Сразу на ум приходит доброе слово "батька". И возникают вопросы по типу - курица или яйцо. Ведь батька - это единственный бот, появившийся не от батьки. Короче закругляюсь, давайте ближе к делу.

Там все просто по инструкции. Отправляем ему команду /newbot. Указываем имя бота.

Дальше надо создать Web App для него. Отправляем команду /newapp. Выбираем нашего нового бота. Указываем заголовок, описание, загружаем картинку, дальше можно /empty для Gif изображения и вот тут он спрашивает ссылку на Mini App. Указываем нашу ссылку - https://tg-mini-app.local. И указываем уникальный идентификатор приложения, например app. Конфигурирование Web App закончено.

Теперь нужно настроить кнопку запуска Web App в боте. Для этого отправляем команду /mybots. Выбираем нашего бота. Нажимаем на кнопку Bot Settings. Кликаем на Menu Button. Если кнопка не активирована, вам предложат активировать, нажимаем Configure Menu Button, и действуем по инструкции. Если уже активировали, будет три пункта: disable button, edit title, edit url.

С этим кажется все, поправьте меня в комментариях, если я что-то упустил, или вдруг очень нужны скриншоты.

Наслаждаемся.

Ну всё, пора запускать бота. Но для начала запустим наш девелопмент режим.

bun run dev

Открываем бота, и видим слева внизу кнопку запуска Web App. Нажимаем, и открывается окно с нашим приложением. Если все сделали верно. Попробуйте отредактировать текст в компоненте /src/App.tsx. По хорошему, вы должны увидеть изменения сразу после сохранения.

Заключение

Чтобы статья не была слишком большой, я решил опустить раздел с установкой и настройкой @tma.js/sdk. К тому же вы можете захотеть пойти другим путем, и например подключить официальный <script src="https://telegram.org/js/telegram-web-app.js"></script>, и установить типизацию для него.

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