Telegram Mini App opens new opportunities for developers, allowing the creation of interactive applications directly inside the messenger. In this guide, we’ll show how to build a working Mini App on React from scratch using Vite and set up an ngrok tunnel for real-time testing. This approach makes it easy to see results quickly, work with user data, and integrate Telegram SDK functionality without a complex server deployment.

We’ll go through the entire process step by step: from creating a starter React project, setting up the ngrok tunnel, to linking it to a bot, so you end up with a fully functional Telegram Mini App, ready for further development and customization.

Step 1: Creating a starter React application

For developing a Telegram Mini App, we use the modern and fast Vite, which works perfectly with React. First, open the terminal and create a project, for example:

npm create vite@latest mini-app

Here, mini-app is the project name and can be chosen freely. Vite will then ask to select the framework and project variant. We choose React and JavaScript, but if you need strict type checking, TypeScript can be used instead. Next, we navigate into the project folder:

cd mini-app
npm install

After installing dependencies, the environment is ready for development.

The next step is integrating the Telegram Mini App SDK:

npm install @twa-dev/sdk

In App.jsx, we import the library and set up basic functionality:

import WebApp from '@twa-dev/sdk'
import { useEffect, useState } from 'react'
import './App.css'

function App() {
  const [tab, setTab] = useState("home")

  useEffect(() => {
    WebApp.ready()
    WebApp.expand()
  }, [])

  const user = WebApp.initDataUnsafe?.user

  return (
    <div>
      <h1>My first Mini App for Telegram!</h1>
      <p>Welcome, {user?.first_name}!</p>

      <button onClick={() => setTab("home")}>Home</button>
      <button onClick={() => setTab("diary")}>Diary</button>

      {tab === "home" && <div>Home</div>}
      {tab === "diary" && <div>Diary</div>}
    </div>
  )
}

export default App

This creates a minimal Telegram Mini App template, which can already work inside the messenger and recognize the user.

To test the project, run:

npm run dev

The terminal will show a local address, usually http://localhost:5173/. Opening it in a browser displays the starter screen with the app title. At this stage, we have a working template ready for further development and for connecting an ngrok tunnel to test the app directly inside Telegram.

Step 2: Setting up an ngrok tunnel

To test the Telegram Mini App directly in the messenger, we need a tunnel that exposes the local server to the internet. ngrok is perfect for this. First, download ngrok from the official website — for Windows, use https://ngrok.com/download, and for Linux, you can run snap install ngrok.

After installing, it’s important to authorize ngrok using your token. Register at https://dashboard.ngrok.com/signup, copy your Auth Token, and add it in the terminal:

ngrok config add-authtoken YOUR_TOKEN

Now we can launch the tunnel to the local server where our React app runs. If the project runs on port 5173, the command is:

ngrok http 5173

Once started, the terminal will show a unique address like:

Forwarding: https://subuncinated-shiftless-gertie.ngrok-free.dev -> http://localhost:5173

This link allows opening the app from any browser and, importantly, from Telegram.

One caveat: Vite by default protects the project from “unknown hosts,” so the ngrok URL may be blocked. To fix this, open vite.config.js in the project root and add permission for the host:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  server: {
    host: true,          // allow all hosts
    strictPort: true,
    allowedHosts: [
      'subuncinated-shiftless-gertie.ngrok-free.dev'
    ]
  }
})

Now our React app is accessible via HTTPS through ngrok, and we can use the link for testing inside Telegram.

After these steps, the local project becomes a fully functional test Telegram Mini App, which can be opened on a phone or in the web version of Telegram to test the interface and SDK in real conditions. This is extremely convenient since all changes are immediately visible, making the development process fast and transparent.

Step 3: Creating a Telegram bot and linking it to the tunnel

Once our React app works through ngrok, the next step is to create a Telegram bot and link it to the tunnel, so we can test the Telegram Mini App directly in the messenger.

First, open @BotFather and create a new bot with:

/start
/newbot

Give it a name and a unique username, which must end with _bot. BotFather will then provide a TOKEN — the key for accessing the bot API. Save it for future use.

Next, connect the Mini App to the bot. In BotFather, select your bot:

/mybots → your bot → Bot Settings → Menu Button

Choose Configure Menu Button and set the parameters:

  • Text: Open Mini App
  • URL: the ngrok tunnel link, e.g., https://subuncinated-shiftless-gertie.ngrok-free.dev

Make sure the link uses HTTPS, otherwise Telegram will not allow opening the app.

After this setup, the bot menu button will launch our React app via the ngrok tunnel, turning the local project into a fully functional Telegram Mini App. Now we can test the interface, user interaction, and any SDK features directly in Telegram.

This approach provides a complete development cycle: first, create a React project with Telegram SDK integration; then, set up ngrok for external access; and finally, link the app to a bot. This workflow allows rapid development and testing of a Mini App without deploying to a real server.