vue-tg

Many fields in vue-tg are reactive. You can use standard Vue patterns like watch or computed to respond to changes in the Telegram environment, such as the isActive state of the Mini App.

const miniApp = useMiniApp()

watch(miniApp.isActive, (isActive) => {
  if (isActive)
    startUpdating()
  else
    stopUpdating()
})

The library provides runtime feature support checks to prevent errors on clients with outdated Bot API versions. For features introduced in specific versions (e.g., DeviceStorage in Bot API 9.0), use isVersionAtLeast to guard your code.

const deviceStorage = useDeviceStorage()

// Guard against older clients
if (deviceStorage.isVersionAtLeast('9.0')) {
  // Safe to use features introduced in 9.0
  deviceStorage.getItem('token')
}

Most Telegram interaction methods support async/await, allowing you to write flat, readable code instead of nesting callbacks. While callback-style usage is still supported for compatibility, the modern approach is preferred.

const miniApp = useMiniApp()
const qrScanner = useQrScanner()
const popup = usePopup()

// Modern async/await flow
const url = await qrScanner.show({ text: 'Scan URL' })
const ok = await popup.showConfirm(`Open ${url}?`)
if (ok) {
  miniApp.openLink(url)
}

To use vue-tg in a Nuxt 3 application, follow these steps:

1. Install the package: npm i vue-tg.
2. Add the Telegram script: Include the script in your nuxt.config.ts under the app.head.script section.
3. Client-side rendering: Because the Telegram Web App script relies on the browser environment, you must wrap your Telegram-related components in the <ClientOnly> component to prevent SSR errors.

export default defineNuxtConfig({
  app: {
    head: {
      script: [{ src: 'https://telegram.org/js/telegram-web-app.js' }],
    },
  },
})

<template>
  <NuxtPage />
  <ClientOnly>
    <MiniApp />
  </ClientOnly>
</template>

<script setup lang="ts">
import MiniApp from '~/components/MiniApp.vue'
</script>

Install the vue-tg package via npm to begin integrating Telegram Mini Apps and Widgets into your Vue project.

npm i vue-tg

To enable Telegram functionality, you must include the official Telegram Web App script in the <head> section of your HTML. This script must be placed before any other scripts to ensure the Telegram environment is initialized correctly.

<script src="https://telegram.org/js/telegram-web-app.js"></script>

Telegram features are tied to specific Bot API versions. To prevent runtime errors when using features not yet supported by the user's Telegram client, use isVersionAtLeast from useMiniApp to perform a check.

Alternatively, you can import composables from a version-specific entry point (e.g., vue-tg/7.8) to ensure the types and methods available match that version.

Warning: Importing from vue-tg/latest skips version checks. This is useful for prototyping but can lead to crashes in production if the user's client is outdated.

import { useMiniApp } from 'vue-tg'

const miniApp = useMiniApp()

// Check if version 7.8+ is supported before using shareToStory
if (miniApp.isVersionAtLeast('7.8')) {
  miniApp.shareToStory("https://url-to-image")
}

Register the VueTelegramPlugin on your Vue instance to enable the use of global aliases for Telegram components. This allows you to use shorthand component names (e.g., <tg-alert />) instead of importing and using the full component names (e.g., <Alert />) in every template.

import { VueTelegramPlugin } from 'vue-tg'

Vue.use(VueTelegramPlugin)

To use the Telegram components globally in your Vue application, install the VueTelegramPlugin. This registers all Telegram-related components with the Tg prefix (e.g., TgAlert, TgMainButton, TgLoginWidget).

import { createApp } from 'vue'
import { VueTelegramPlugin } from 'vue-tg'
import App from './App.vue'

const app = createApp(App)

app.use(VueTelegramPlugin)
app.mount('#app')