Vue Telegram Integration Library

0.10.0 · active · verified Sun Apr 19

vue-tg is a lightweight package designed for seamless integration of Telegram Mini Apps and Telegram Widgets into Vue 3 applications. Currently at version 0.10.0, it maintains an active release cadence, frequently updating to support the latest Telegram Bot API versions, such as 9.5. Key differentiators include its use of Vue 3 composables for reactive interaction with the Telegram client, full TypeScript type safety, and an innovative API that enforces runtime feature support checks to prevent errors on clients with outdated Bot API versions. It also provides async/await support for methods, eliminating callback hell, and includes ready-to-use Vue components for common Mini App UI elements like MainButton and BackButton, streamlining development workflows.

Common errors

```
Type error: 'getItem' may not be available — DeviceStorage was introduced in Bot API 9.0
```
cause Attempting to use a Telegram Mini App feature (e.g., `deviceStorage.getItem`) that was introduced in a newer Bot API version without a runtime version check, potentially targeting an older client that does not support it.

fix Implement a version check before using the feature: `if (deviceStorage.isVersionAtLeast('9.0')) { deviceStorage.getItem('token') }`. Alternatively, configure a minimum required Bot API version globally if all target clients are known to support it.
```
Module not found: Error: Can't resolve 'vue-tg/latest'
```
cause An attempt to import a symbol (e.g., `usePopup`) using an incorrect import path, or when the `/latest` subpath export is not properly configured or recognized by the module bundler.

fix Verify that the import statement matches the exact path specified in the `vue-tg` documentation for the given symbol (e.g., `import { usePopup } from 'vue-tg/latest'`). Ensure your bundler supports subpath exports if applicable.

Warnings

breaking Since version 0.9.0, `vue-tg` introduces a new API that enforces runtime feature support checks. Directly calling Telegram Mini App features without verifying client Bot API version support can lead to runtime errors or TypeScript type errors on clients with outdated APIs.
Fix: Always use `isVersionAtLeast()` checks (e.g., `deviceStorage.isVersionAtLeast('9.0')`) before utilizing features, or configure a minimum required Bot API version globally as per the documentation to disable warnings.
gotcha The core Telegram Web App JavaScript SDK (`telegram-web-app.js`) is not bundled with `vue-tg`. It is an essential external dependency that must be explicitly included in your HTML's `<head>` tag before your application scripts.
Fix: Add `<script src="https://telegram.org/js/telegram-web-app.js"></script>` to your `index.html`'s `<head>` section.
gotcha Certain composables, such as `usePopup`, require importing from the non-standard `vue-tg/latest` subpath, rather than directly from the base `vue-tg` package. Incorrect import paths will result in module resolution errors.
Fix: Consult the official documentation for each specific composable to ensure the correct import path is used. Pay close attention to examples like `import { usePopup } from 'vue-tg/latest'`.
gotcha `vue-tg` frequently updates to support new Telegram Bot API versions. Developers should anticipate regular updates to the library and may need to adapt their code to leverage new features or accommodate changes in the underlying Telegram API paradigms.
Fix: Maintain awareness of `vue-tg` release notes and Telegram Bot API updates. Regularly update the package and review your codebase for necessary adjustments, especially when upgrading to new major or minor versions.

Install

npm install vue-tg npm
yarn add vue-tg yarn
pnpm add vue-tg pnpm

Imports

MainButton
wrong:
```
import MainButton from 'vue-tg'
```
correct:
```
import { MainButton } from 'vue-tg'
```
MainButton is a named component export. Attempting a default import will fail.
usePopup
wrong:
```
import { usePopup } from 'vue-tg'
```
correct:
```
import { usePopup } from 'vue-tg/latest'
```
Some composables, like `usePopup`, are imported from the 'vue-tg/latest' path to access the most recent API features. Importing from the base 'vue-tg' package will not work for these.
useDeviceStorage
wrong:
```
const useDeviceStorage = require('vue-tg')
```
correct:
```
import { useDeviceStorage } from 'vue-tg'
```
This composable is a named export. The library primarily supports ES Modules; CommonJS `require()` syntax is not supported for module imports.
Telegram Web App Script
```
<script src="https://telegram.org/js/telegram-web-app.js"></script>
```
The core Telegram Web App script is an external dependency and must be included globally in the `<head>` tag before any other scripts for `vue-tg` to function correctly. This is not a standard JavaScript module import.

Quickstart

This example demonstrates how to use the `MainButton` component to trigger an alert via the `usePopup` composable within a Vue 3 Telegram Mini App.

<template>
  <MainButton text="Open alert" @click="() => popup.showAlert('Hello!')" />
</template>

<script lang="ts" setup>
import { MainButton } from 'vue-tg'
import { usePopup } from 'vue-tg/latest'

const popup = usePopup()
</script>

view raw JSON →