@ademax/tg-web-app

TypeScript helpers and typings for Telegram Mini Apps (Telegram WebApp API).

This package provides:

• global TypeScript typings for window.Telegram.WebApp
• reusable runtime helpers (for example useTelegram)
• strongly typed interfaces for Telegram WebApp API

The package is designed to be simple to use and easy to extend in the future.

Installation

npm install @ademax/tg-web-app

Enabling global typings

To enable global typing for window.Telegram, add the package to the types section of your tsconfig.json:

{
  "compilerOptions": {
    "types": ["@ademax/tg-web-app"]
  }
}

After that, window.Telegram.WebApp will be available with full TypeScript support across your project.

Example:

window.Telegram.WebApp.ready();

This approach is recommended if you rely on global access to the Telegram WebApp object and do not want to import anything explicitly in your code.

Runtime API

The package also exports runtime helpers that can be imported directly.

Example:

import { useTelegram } from "@ademax/tg-web-app";

const { webApp } = useTelegram();

webApp.ready();

Importing any runtime API automatically includes all related TypeScript typings.

Type exports

All core Telegram WebApp interfaces are exported and can be used directly in your code:

import type {
    IWebApp,
    IWebAppInitData,
    IWebAppUser,
    IWebAppChat,
    TChatType
} from "@ademax/tg-web-app";

This allows you to use Telegram WebApp types explicitly in your application code.

Notes

• The package is safe to import in browser environments.
• Global typings are included automatically when the package is listed in compilerOptions.types.
• No JavaScript code is executed just by enabling global typings.

License

MIT