GramIO

Русский

English

Русский

English

Тема

Telegram Mini Apps (Web app) ​

🚧 Это руководство в процессе разработки 🚧

Данное руководство поможет вам начать разработку Telegram Mini Apps.

Для более подробного руководства рекомендуем обратиться к Telegram apps (tma.js).

Дополнительные ресурсы:

Создание проекта с помощью create-gramio ​

create-gramio — это мощный инструмент для создания проектов Telegram Mini App. Он поддерживает различные конфигурации проектов и легко интегрируется с GramIO.

Вы можете быстро настроить:

  • Отдельный Telegram бот
  • Монорепозиторий с Mini App + Bot
  • Полноценный монорепозиторий с Mini App + Bot + Elysia (бэкенд фреймворк)

    Примечание: Этот вариант доступен только с bun (альтернатива среде выполнения Node.js) из-за требований фреймворка Elysia

Установка ​

Выберите предпочитаемый менеджер пакетов:

bash
npm create gramio@latest ./bot
bash
yarn create gramio@latest ./bot
bash
pnpm create gramio@latest ./bot
bash
bun create gramio@latest ./bot

Параметры настройки проекта ​

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

  1. Выбор типа проекта:

    • Bot (отдельный бот)
    • Mini App + Bot + Elysia (фреймворк для бэкенда) монорепозиторий
    • Mini App + Bot монорепозиторий

  2. Для проектов с монорепозиторием:

    • Вам будет предложено выбрать шаблон Mini App из опций @telegram-apps/create-mini-app
    • Если выбрана опция Elysia, вы также настроите бэкенд на Elysia

  3. Конфигурация фреймворка для бота:

    • Выберите предпочитаемую базу данных (без БД, Prisma, Drizzle)
    • Выберите инструменты разработки (ESLint, Biome)
    • Настройте дополнительные функции (i18n, Redis, аналитика PostHog и т.д.)

Структура монорепозитория ​

Когда вы создаете проект с монорепозиторием, структура вашего каталога будет выглядеть так:

tree
bash
├── apps
│   ├── bot         # Ваше приложение бота GramIO
│   ├── mini-app    # Фронтенд Telegram Mini App
│   └── server      # Серверная часть (если используется опция Elysia)
└── packages
    └── db          # Общий пакет базы данных (если выбран)

Использование Telegram apps (tma.js) напрямую ​

В качестве альтернативы вы можете создать только часть Mini App с помощью @telegram-apps/create-mini-app:

bash
npm create @telegram-apps/mini-app@latest ./miniapp
bash
yarn create @telegram-apps/mini-app@latest ./miniapp
bash
pnpm create @telegram-apps/mini-app@latest ./miniapp
bash
bun create @telegram-apps/mini-app@latest ./miniapp

Эта команда поможет вам создать проект с шаблоном из следующих вариантов:

WARNING

На данный момент поддержка монорепозитория в create-gramio может быть не идеальной (не самой удобной из коробки), поскольку сложно поддерживать эти два варианта создания одновременно.

HTTPS на localhost ​

BotFather принимает только ссылки http:// для продакшена, но для получения вашего приложения в тестовой среде требуется HTTPS. Вот как настроить HTTPS на localhost:

  1. Сначала установите mkcert:
bash
choco install mkcert
# или с помощью Scoop
scoop bucket add extras
scoop install mkcert
bash
brew install mkcert
brew install nss # если вы используете Firefox
bash
sudo apt install libnss3-tools
brew install mkcert
  1. Создайте локальный сертификат для вашего пользовательского имени хоста и установите его:
bash
mkcert mini-app.local
mkcert --install
  1. Добавьте пользовательское имя хоста в файл hosts:
powershell
echo "127.0.0.1 mini-app.local" >> C:\Windows\System32\drivers\etc\hosts
bash
sudo echo "127.0.0.1 mini-app.local" >> /etc/hosts
  1. Настройте его в vite.config.ts:
ts
import fs from "node:fs";
import { defineConfig } from "vite";

export default defineConfig({
    server: {
        port: 443,
        host: "0.0.0.0",
        hmr: {
            host: "mini-app.local",
            port: 443,
        },
        https: {
            key: fs.readFileSync("./mini-app.local-key.pem"),
            cert: fs.readFileSync("./mini-app.local.pem"),
        },
    },
});

🔥 Теперь вам не нужны никакие туннели, и вы можете с удовольствием разрабатывать с HMR в производственной среде Telegram!