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

tree

├── 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

WARNING

At the moment, create-gramio's monorepo support may not be ideal (not the most convenient out of the box). because it's difficult to support these two creation options at the same time.

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!