For developers looking to enter the Telegram ecosystem, Telegram Mini Apps are undoubtedly an excellent starting point. They not only offer access to a massive user base but also allow for deep integration with features like payments and bots. However, many get stuck at the beginning: What tech stack should I use? How do I configure the development environment? How can I actually run my local project within Telegram?
This article will guide you through the end-to-end development process with a real-world food delivery app case study (similar to Durer King), taking you from zero to one. Whether you're a front-end developer or a product manager looking to explore the Telegram ecosystem, this article will help you get up to speed quickly.
Telegram is more than just an instant messaging tool; its open ecosystem offers immense possibilities for developers:
For this article’s case study, we'll build a complete food delivery system encompassing a Web App + Telegram Bot + Payment Functionality. We’ll use React.js for the front-end and Node.js for the back-end, integrating Telegram's official payment capabilities.
Before we dive in, let's define our technical approach:
It's crucial to note that Telegram Mini Apps mandate the use of the HTTPS protocol. This means you'll need to configure an SSL certificate even for local development. We'll detail how to resolve this issue later.
All Telegram Mini Apps are launched through a Bot. Let's start by creating one using BotFather:
@BotFather in Telegram and open the chat./newbot command.This token acts like a key, connecting your application to Telegram's servers.
Next, we'll use the official Telegram Mini App SDK to quickly set up our project:
# Create React + TypeScript project
npx create-react-app my-telegram-app --template typescript
cd my-telegram-app
# Install Telegram SDK
npm install @twa-dev/sdk
The SDK provides a rich set of APIs for tasks like fetching user information, invoking payment interfaces, sending messages, and more. Once installed, open your project in VS Code and start it:
npm start
At this point, your project will be running on http://localhost:3000. However, this isn't sufficient – Telegram requires all Mini Apps to be accessed via HTTPS.
Many developers get stuck here: How do I use HTTPS for local development? There are two solutions:
Modify the start script in your package.json:
"scripts": {
"start": "HTTPS=true react-scripts start"
}
This will automatically start your project with a self-signed certificate at https://localhost:3000.
If you need to test remotely (e.g., on your phone), you can use ngrok to expose your local service to the public internet:
ngrok http 3000
ngrok will generate a public HTTPS address. Copy this address, and you can then use it within Telegram.
Now, we need to tell Telegram where the Mini App entry point for this Bot is. Go back to BotFather:
/mybots command and select the Bot you just created.Bot Settings → Menu Button.https://your-ngrok-url.io).Once done, open your Bot in Telegram, click the menu button at the bottom, and your Mini App will open within Telegram!
Clean up the default React code, keeping only the core structure:
import { useEffect } from 'react';
import './App.css';
function App() {
useEffect(() => {
// Initialize Telegram SDK
const tg = (window as any).Telegram.WebApp;
tg.ready();
console.log('Telegram WebApp is loaded');
}, []);
return (
<div className="App">
<h1>Hello Telegram!</h1>
</div>
);
}
export default App;
Save the file and refresh your Telegram chat. You should now see the "Hello Telegram!" page, and the console log indicating successful SDK initialization should appear.
To ensure consistent display across different devices, it's recommended to use Normalize.css and set up global styles:
/* App.css */
* {
margin: 0;
padding: 0;
box-sizing: border-box;
}
body {
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
background-color: var(--tg-theme-bg-color);
color: var(--tg-theme-text-color);
}
Telegram provides a set of theme variables. Using these variables allows your app to automatically adapt to the user's light or dark mode preferences.
After completing these steps, you'll have a functional Telegram Mini App framework. You can then proceed to:
If you require an anti-detect browser for scenarios like managing multiple accounts or automated testing, consider using MasLogin. It can help you simulate different environments during development and testing, mitigating account risks.
If you're using the free version of ngrok, the address changes every time you restart ngrok. It's recommended to:
Commonly used APIs include:
window.Telegram.WebApp.ready() - Initializationwindow.Telegram.WebApp.MainButton - Main button controlwindow.Telegram.WebApp.initData - Fetch user informationwindow.Telegram.WebApp.close() - Close the Mini AppFor detailed documentation, refer to the Telegram WebApp API.
Telegram offers a sandbox environment. You can use test payment credentials for debugging. Refer to the official payment documentation for specific instructions.
Through this article, you've grasped the core development workflow for Telegram Mini Apps. Remember: start by building a minimal viable version, and then iterate and optimize. Now, start building your own Telegram ecosystem application!
Outline
