Telegram Mini Apps Made Easy: A Developer's Handbook for Building on TON (2024)

Vite: This build tool is the star of the show. It's designed for modern web development and makes the process faster and smoother. It's like having a super-efficient assistant that handles all the background tasks so you can focus on coding your app's features.

Git: This version control system is like a time machine for your code. It lets you track changes, collaborate with others, and revert to previous versions if needed. It's essential for any software development project, especially if you're working with a team.

Node.js and npm (or yarn): Node.js is a JavaScript runtime that lets you run JavaScript code outside of a web browser. npm (or yarn) is a package manager that helps you install and manage the libraries and tools your project needs. Think of them as your toolbox, filled with all the little bits and pieces you need to build your app.

@twa-dev/sdk: This is the official TON Web Apps SDK, a set of tools and libraries specifically designed for building TON mini-apps. It's like a translator that helps your app understand and interact with the TON blockchain.

Code Editor: Choose your favorite code editor (e.g., Visual Studio Code, Atom, Sublime Text). This is where you'll write and edit your code, so pick one that feels comfortable and productive for you.

Vercel, Netlify or others: This platform will host your mini-app online, making it accessible to Telegram users. It's like renting a storefront for your app where everyone can see and interact with it.

Git - You can download it here

NodeJS - You can download it here

Create the app from scratch using package manager or simply clone TokenMinds example template for the Telegram Mini App.

1. From scratch:

   Using npm

   $ npm create vite@latest your-project-name

   Using yarn

   $ yarn create vite your-project-name

2. From TokenMinds template

   $ git clone https://github.com/TokenMinds-co/tokenminds-tma.git

Navigate to the project by using the cd command

We need to install the dependencies,

Using npm

$ npm install

Using yarn

$ yarn install

And now we are going to add @twa-dev/sdk. The @twa-dev/sdk package allows to work with SDK as with an npm package and with TypeScript support.

Using npm

$ npm install @twa-dev/sdk

Using yarn

$ yarn add @twa-dev/sdk

Open /src/main.tsx file and add following:

import WebApp from '@twa-dev/sdk'

WebApp.ready();

WebApp.ready() - is a method that informs the Telegram app that the Mini App is ready to be displayed. It is recommended to call this method as early as possible, as soon as all essential interface elements are loaded. Once this method is called, the loading placeholder is hidden and the Mini App is shown.

Open src/App.jsx and add the following code

import { useState } from "react";
import "./App.css";

function App() {
const [count, setCount] = useState(0);

return (
<>
<div>
<a href="https://tokenminds.co" target="_blank">
<img
src={`https://framerusercontent.com/images/7Fjd4JhBn4XdPoBAztnI31U.webp`}
className="logo"
alt="Tokenminds logo"
/>
</a>
</div>
<h1>My First Telegram Mini App</h1>
<div className="card">
<button onClick={() => setCount((count) => count + 1)}>
count is {count}
</button>
</div>
<div>
<p>
Click{" "}
<a href="https://docs.ton.org/develop/dapps/telegram-apps/app-examples"
target="_blank"
>
here
</a>{" "}
to learn more.
</p>
</div>
</>
);
}

export default App;

Now to see if our app is working we can run it locally by running this command

$ npm run dev

Your app should look like this if it's working correctly. If you encounter an error go through again the steps above and check, you might’ve missed some steps

Now that your app is working correctly, commit and push it in your github repository and then we can proceed on the next steps

Go to the vercel website and login using your Github account to easily import your project

Create a new project

Select your project

Rename the project if you want and then click deploy

Wait for it to finish building the project, and voila your app is up and running. You can click one of the domains to visit your application

Refine and Enhance

• User Experience (UX): Gather feedback from early users or testers to identify any friction points or areas for improvement in the user experience. Optimize navigation, simplify interactions, and ensure your TMA is intuitive and enjoyable to use.

• Functionality: Expand the functionality of your TMA by adding new features or capabilities. Consider integrating with other Telegram features, such as bots or channels, to enhance the overall experience.

• Performance: Optimize your code and assets to ensure your TMA loads quickly and performs smoothly, even on slower connections.

Thorough Testing

• Test on Different Devices: Ensure your TMA works flawlessly across different devices and operating systems (iOS, Android, web). Test on various screen sizes and resolutions to guarantee a consistent experience for all users.

• Security Audit (if applicable): If your TMA involves sensitive data or financial transactions, consider conducting a security audit to identify and address any potential vulnerabilities.

• User Testing: Gather feedback from a broader audience to identify any usability issues, bugs, or areas for improvement.

Launch and Promotion

• Create a Telegram Bot: If you haven't already, create a Telegram bot to interact with your TMA. This will allow users to access your app directly through the bot's interface.

• Submit to Telegram: Submit your TMA to the official Telegram Mini Apps platform for review and approval. This will make your app discoverable to Telegram users.

• Promote Your TMA: Spread the word about your mini-app through various channels, such as social media, Telegram groups and channels, and crypto communities. Consider partnering with influencers or running targeted ad campaigns to reach a wider audience.

Post-Launch Maintenance and Growth

• Monitor Performance: Track key metrics like user engagement, retention, and conversion rates to assess the success of your TMA. Use analytics tools to gain insights into user behavior and identify areas for improvement.

• Iterate and Update: Continuously update and improve your TMA based on user feedback and data analysis. Add new features, fix bugs, and optimize performance to keep users engaged.

• Community Building: Foster a community around your TMA by creating dedicated Telegram groups or channels where users can interact, share feedback, and get support. Actively engage with your community to build a loyal following.

Vite: This build tool is the star of the show. It's designed for modern web development and makes the process faster and smoother. It's like having a super-efficient assistant that handles all the background tasks so you can focus on coding your app's features.

Git: This version control system is like a time machine for your code. It lets you track changes, collaborate with others, and revert to previous versions if needed. It's essential for any software development project, especially if you're working with a team.

Node.js and npm (or yarn): Node.js is a JavaScript runtime that lets you run JavaScript code outside of a web browser. npm (or yarn) is a package manager that helps you install and manage the libraries and tools your project needs. Think of them as your toolbox, filled with all the little bits and pieces you need to build your app.

@twa-dev/sdk: This is the official TON Web Apps SDK, a set of tools and libraries specifically designed for building TON mini-apps. It's like a translator that helps your app understand and interact with the TON blockchain.

Code Editor: Choose your favorite code editor (e.g., Visual Studio Code, Atom, Sublime Text). This is where you'll write and edit your code, so pick one that feels comfortable and productive for you.

Vercel, Netlify or others: This platform will host your mini-app online, making it accessible to Telegram users. It's like renting a storefront for your app where everyone can see and interact with it.

Git - You can download it here

NodeJS - You can download it here

Create the app from scratch using package manager or simply clone TokenMinds example template for the Telegram Mini App.

1. From scratch:

   Using npm

   $ npm create vite@latest your-project-name

   Using yarn

   $ yarn create vite your-project-name

2. From TokenMinds template

   $ git clone https://github.com/TokenMinds-co/tokenminds-tma.git

Navigate to the project by using the cd command

We need to install the dependencies,

Using npm

$ npm install

Using yarn

$ yarn install

And now we are going to add @twa-dev/sdk. The @twa-dev/sdk package allows to work with SDK as with an npm package and with TypeScript support.

Using npm

$ npm install @twa-dev/sdk

Using yarn

$ yarn add @twa-dev/sdk

Open /src/main.tsx file and add following:

import WebApp from '@twa-dev/sdk'

WebApp.ready();

WebApp.ready() - is a method that informs the Telegram app that the Mini App is ready to be displayed. It is recommended to call this method as early as possible, as soon as all essential interface elements are loaded. Once this method is called, the loading placeholder is hidden and the Mini App is shown.

Open src/App.jsx and add the following code

import { useState } from "react";
import "./App.css";

function App() {
const [count, setCount] = useState(0);

return (
<>
<div>
<a href="https://tokenminds.co" target="_blank">
<img
src={`https://framerusercontent.com/images/7Fjd4JhBn4XdPoBAztnI31U.webp`}
className="logo"
alt="Tokenminds logo"
/>
</a>
</div>
<h1>My First Telegram Mini App</h1>
<div className="card">
<button onClick={() => setCount((count) => count + 1)}>
count is {count}
</button>
</div>
<div>
<p>
Click{" "}
<a href="https://docs.ton.org/develop/dapps/telegram-apps/app-examples"
target="_blank"
>
here
</a>{" "}
to learn more.
</p>
</div>
</>
);
}

export default App;

Now to see if our app is working we can run it locally by running this command

$ npm run dev

Your app should look like this if it's working correctly. If you encounter an error go through again the steps above and check, you might’ve missed some steps

Now that your app is working correctly, commit and push it in your github repository and then we can proceed on the next steps

Go to the vercel website and login using your Github account to easily import your project

Create a new project

Select your project

Rename the project if you want and then click deploy

Wait for it to finish building the project, and voila your app is up and running. You can click one of the domains to visit your application

Refine and Enhance

• User Experience (UX): Gather feedback from early users or testers to identify any friction points or areas for improvement in the user experience. Optimize navigation, simplify interactions, and ensure your TMA is intuitive and enjoyable to use.

• Functionality: Expand the functionality of your TMA by adding new features or capabilities. Consider integrating with other Telegram features, such as bots or channels, to enhance the overall experience.

• Performance: Optimize your code and assets to ensure your TMA loads quickly and performs smoothly, even on slower connections.

Thorough Testing

• Test on Different Devices: Ensure your TMA works flawlessly across different devices and operating systems (iOS, Android, web). Test on various screen sizes and resolutions to guarantee a consistent experience for all users.

• Security Audit (if applicable): If your TMA involves sensitive data or financial transactions, consider conducting a security audit to identify and address any potential vulnerabilities.

• User Testing: Gather feedback from a broader audience to identify any usability issues, bugs, or areas for improvement.

Launch and Promotion

• Create a Telegram Bot: If you haven't already, create a Telegram bot to interact with your TMA. This will allow users to access your app directly through the bot's interface.

• Submit to Telegram: Submit your TMA to the official Telegram Mini Apps platform for review and approval. This will make your app discoverable to Telegram users.

• Promote Your TMA: Spread the word about your mini-app through various channels, such as social media, Telegram groups and channels, and crypto communities. Consider partnering with influencers or running targeted ad campaigns to reach a wider audience.

Post-Launch Maintenance and Growth

• Monitor Performance: Track key metrics like user engagement, retention, and conversion rates to assess the success of your TMA. Use analytics tools to gain insights into user behavior and identify areas for improvement.

• Iterate and Update: Continuously update and improve your TMA based on user feedback and data analysis. Add new features, fix bugs, and optimize performance to keep users engaged.

• Community Building: Foster a community around your TMA by creating dedicated Telegram groups or channels where users can interact, share feedback, and get support. Actively engage with your community to build a loyal following.