A Telegram mini app is a web app that opens inside the messenger, so a developer can reach Telegram users without a separate store release. This guide builds one with Vue.js, from creating the project to opening it in Telegram. There's also a video version of the article, in Russian.

Why Vue.js

Vue.js is a framework for single-page applications, which is what a mini app is. It has a simple project structure, routing and state management in the official ecosystem and good documentation. Load speed and a responsive interface matter for mini apps, and a small Vue app handles both without much setup.

Step 1: Create a Vue.js project

You'll need Node.js and npm.

  1. Scaffold a project and choose the options you need (router, TypeScript and so on):
    npm create vue@latest
  2. Go to the project folder and install the dependencies:
    cd <project_name>
npm install
  3. Start the dev server:
    npm run dev
    By default the app is available at http://localhost:5173.

Step 2: Clean up the project

Remove the demo files and components that came with the template. Keep the base styles and one main component, for example Home.vue. Replace its content with your own, import it in App.vue and check that the page still renders.

Step 3: Install the Telegram SDK

In a second terminal, install a library that wraps the Mini Apps API (or use the current command from the Telegram Mini Apps documentation):

npm install @twa-dev/sdk

The package wraps the window.Telegram.WebApp object, so you don't need to add anything to index.html. Import it in your main file (main.ts or main.js) and tell Telegram the app is ready:

import { createApp } from 'vue';
import WebApp from '@twa-dev/sdk';
import App from './App.vue';

const app = createApp(App);
app.mount('#app');
WebApp.ready();

Call WebApp.ready() after the interface has rendered: Telegram hides its loading placeholder at that moment.

Step 4: Test the app inside Telegram

Many SDK features work only inside Telegram, so opening the app in an ordinary browser won't show everything. To open your local server from Telegram, you need a public HTTPS address, and a tunnel such as ngrok provides one.

  1. Sign up on the ngrok website and install the tool.
  2. Run it against the port of your dev server:
    ngrok http 5173
  3. ngrok prints a public HTTPS address. Use it to open the app from Telegram.

If Vite answers the tunnel address with a "Blocked request. This host is not allowed" error, allow the host in vite.config, for example with server: { allowedHosts: true }. Use that setting for local development only.

Step 5: Register the mini app

  1. In Telegram, open @BotFather and create a bot by following the instructions. An icon is optional.
  2. Add the mini app to the bot, either with the /newapp command or in the bot settings, and enter the public ngrok address as its URL.
  3. Save the changes.

The mini app now opens from Telegram through your bot. If the tunnel address changes after a restart, update the URL in BotFather.

Step 6: Use Telegram features

Once the SDK works inside Telegram, you can call the rest of the Mini Apps API. Two simple examples are the native Back button and pop-up messages (WebApp.showAlert). This is how to show the Back button on a page and remove its handler when you leave it:

import WebApp from '@twa-dev/sdk';

export default {
  mounted() {
    WebApp.BackButton.show();
    WebApp.BackButton.onClick(this.goBack);
  },
  beforeUnmount() {
    WebApp.BackButton.offClick(this.goBack);
    WebApp.BackButton.hide();
  },
  methods: {
    goBack() {
      // Your "Back" handler
    },
  },
};

Tips

The Telegram Mini Apps documentation has many examples, but not every button and method is explained in detail. When something is unclear, experiment with it in the app and read the SDK source. If access to official sites is restricted in your region, you may need a VPN. And since Vue's hot reload works through the tunnel, changes appear in the mini app almost immediately after you save a file.

From here you can add pages with the Vue router, third-party libraries and your own business logic.

If you want to see a finished mini app, look at iTasker, a task manager inside Telegram with projects, reports and Google Calendar integration. It shows what a full service in a mini app can look like.

Launch the iTasker bot