Telegram Mini Apps (Web app)

Guide is WIP.

For start, we recommend Telegram apps (tma.js).

Telegram documentation | Figma UI Kit | Telegram Developers Community

Scaffold monorepo

With create-gramio you can easily start developing Telegram mini app in monorepo. You can start a project with tma.js, Elysiajs and GramIO in a minute!

npm

npm create gramio@latest ./bot

yarn

yarn create gramio@latest ./bot

pnpm

pnpm create gramio@latest ./bot

bun

bun create gramio@latest ./bot

and choose the type of project you need!

For example, this is what a monorepo created using create-gramio looks like

├── apps
│   ├── bot
│   ├── mini-app
│   └── server
└── packages
    └── db

Scaffold via Telegram apps (tma.js)

npm

npm create @telegram-apps/mini-app@latest ./bot

yarn

yarn create @telegram-apps/mini-app@latest ./bot

pnpm

pnpm create @telegram-apps/mini-app@latest ./bot

bun

bun create @telegram-apps/mini-app@latest ./bot

This command will help you scaffold a project with a template that matches you from the list:

• TypeScript
• • React
• • Solid
• • Next
• JavaScript
• • React
• • Solid

HTTPS on localhost

BotFather only accepts http:// links and getting into the test environment can be problematic, so let's figure out how to work with https:// and localhost.

1. First you need to install mkcert:

Windows

choco install mkcert
# or with Scoop
scoop bucket add extras
scoop install mkcert

macOS

brew install mkcert
brew install nss # if you use Firefox

Linux

sudo apt install libnss3-tools
brew install mkcert

2. Then you need to create a local certificate for the custom hostname and instal it:

mkcert mini-app.local
mkcert --install

3. Add the custom hostname to your hosts file:

Windows (Open terminal as an administrator)

echo "127.0.0.1 mini-app.local" >> C:\Windows\System32\drivers\etc\hosts

macOS | Linux

sudo echo "127.0.0.1 mini-app.local" >> /etc/hosts

4. Configure it in vite.config.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"),
        },
    },
});

🔥 Now you don't need any tunnels and you are happy to develop with HMR in the telegram production environment!