telegram-miniapp-tools

Telegram Miniapp Tools

A utility package designed to simplify the development of Telegram Mini Apps (unofficial). This package includes tools and types for seamless interaction with the Telegram WebApp environment.

Installation

React/Node.js (NPM/Yarn)

To add telegram-miniapp-tools to your Node.js/React project, use the following command:

npm install telegram-miniapp-tools

or

yarn add telegram-miniapp-tools

Deno

For Deno users, the package is available as @smartearnersteam/tapp-tools and can be imported directly from jsr.io:

import {
  parseInitData,
  createAddIconToHomeScreen,
} from "https://jsr.io/@smartearnersteam/tapp-tools";

Features

• Utilities to manage Telegram Mini App environments and parameters.
• Functions for custom functionality like adding an icon to the home screen.
• Strongly typed interfaces for Telegram WebApp parameters.
• Modular and lightweight implementation for modern web development.

Usage

Utilities

The following utilities are available for managing your Telegram Mini App:

More details in /docs/md/utils.md

Initialization

import { webApp } from "telegram-miniapp-tools";

webApp.showAlert("Hello world!");
console.log(webApp.isVersionAtLeast("7.10"));

Adding an Icon to the Home Screen

import { createAddIconToHomeScreen } from "telegram-miniapp-tools/utils";

const homeScreenManager = createAddIconToHomeScreen();

For Deno:

import { createAddIconToHomeScreen } from "https://jsr.io/@smartearnersteam/tapp-tools";

const homeScreenManager = createAddIconToHomeScreen();

In use:

const status: HomeScreenStatus = homeScreenManager.getStatus();

if (status !== "added") {
  homeScreenManager.addToHomeScreen();
  // Optionally, listen for status changes
  const onStatusChange = (newStatus: HomeScreenStatus) => {
    if (newStatus === "added") {
      // do something here
      homeScreenManager.offStatusChange(onStatusChange);
    }
  };
  homeScreenManager.onStatusChange(onStatusChange);
}

Parsing Initialization Data

import { parseInitData } from "telegram-miniapp-tools/utils";
// Let's imagine, we have init data in a raw format like this. Telegram application is
// sending it in the exact same format.
const initDataString = "user=%7B%22id%22%3A13707702%2C%22first_name%22%3A%22EVMlord%22%2C%22last_name%22%3A%22%22%2C%22username%22%3A%22EVMlord%22%2C%22language_code%22%3A%22en%22%2C%22is_premium%22%3Atrue%2C%22allows_write_to_pm%22%3Atrue%2C%22photo_url%22%3A%22https%3A%5C%2F%5C%2Ft.me%5C%2Fi%5C%2Fuserpic%5C%2F320%5C%2FlR3FXmzCS9q3lI-K-WLLiUstzaM7ri38rvrU6hLA.svg%22%7D&chat_instance=604945030034165&chat_type=sender&auth_date=1732636784&signature=1oewsopfbyF6LnZtb0HY6-XmGe8mc1rUUUIklSXGlrPsVeetK_4pb-v3L6rPr3mwheJtyjSLawxqDyGQpimCAw&hash=f0981624e433a75f60559592609ac345699c635942bdcbc869c8b5e60264fad2",

// Extract init data.
console.log(parseInitData(initDataString));
// or
console.log(parseInitData(new URLSearchParams(initDataString)));

// Output:
// {
//     "authDate": "2024-11-26T15:59:44.000Z",
//     "chatInstance": "60494508300341655",
//     "chatType": "sender",
//     "hash": "f0981624e433a75f60559592609ac345699c635942bdcbc869c8b5e60264fad2",
//     "signature": "1oewsopfbyF6LnZtb0HY6-XmGe8mc1rUUUIklSXGlrPsVeetK_4pb-v3L6rPr3mwheJtyjSLawxqDyGQpimCAw",
//     "user": {
//         "allowsWriteToPm": true,
//         "firstName": "EVMlord",
//         "id": 13707702,
//         "isPremium": true,
//         "languageCode": "en",
//         "lastName": "",
//         "photoUrl": "https://t.me/i/userpic/320/lR3FXmzCS9q3lI-K-WLLiUstzaM7ri38rvrU6hLA.svg",
//         "username": "EVMlord"
//     }
// }

The function extracts the required parameters and automatically validates their types. If a property has an invalid type or value, it will throw an error.

Mocking Telegram Environment (for testing)

The mockTelegramEnv function imitates the WebApp environment provided by Telegram. It helps developers start building applications even without creating a mini app record in BotFather.

import { mockTelegramEnv } from "telegram-miniapp-tools/utils";

mockTelegramEnv({
  themeParams: {
    accentTextColor: "#6ab2f2",
    bgColor: "#17212b",
    buttonColor: "#5288c1",
    buttonTextColor: "#ffffff",
    destructiveTextColor: "#ec3942",
    headerBgColor: "#17212b",
    hintColor: "#708499",
    linkColor: "#6ab3f3",
    secondaryBgColor: "#232e3c",
    sectionBgColor: "#17212b",
    sectionHeaderTextColor: "#6ab3f3",
    subtitleTextColor: "#708499",
    textColor: "#f5f5f5",
  },
  initData: parseInitData(initDataString),
  initDataString,
  version: "7.2",
  platform: "tdesktop",
});

⚠️ Warning
This function only imitates Telegram environment behavior. It doesn't send any real requests or perform actions that will only be visible in the Telegram application..

Retrieving Launch Parameters

import { retrieveLaunchParams } from "telegram-miniapp-tools/utils";

const MainContent: FC = () => {
  const { initData, themeParams } = retrieveLaunchParams();

  return (
    <>
      // content here
      <div className="pt-8">Something goes here</div>
    </>
  );
};

Managing Back Button Behavior

import createBackButtonManager from "telegram-miniapp-tools/utils";

const backButtonManager = createBackButtonManager();

if (backButtonManager) {
  // Show the back button
  backButtonManager.show();

  // Add a click event handler
  function handleBackButtonClick() {
    console.log("Back button clicked!");
    // Perform any action, e.g., navigate to the previous page
  }

  backButtonManager.onClick(handleBackButtonClick);

  // Optionally, remove the event handler later
  // backButtonManager.offClick(handleBackButtonClick);

  // Hide the back button when not needed
  // backButtonManager.hide();
} else {
  console.error("BackButton is not available.");
}

Managing Cloud Storage

import { createCloudStorageManager } from "telegram-miniapp-tools/utils";

const cloudStorage = createCloudStorageManager();

// Attempt to save `token` to cloud storage.
try {
  if (cloudStorage) {
    await cloudStorage.setItem("token", JSON.stringify({ token, expiresAt })); // Consistently store as JSON
  }
  // console.log("Token successfully saved to cloud storage.");
} catch (cloudError) {
  console.error("Error saving token to cloud storage:", cloudError);
}

// Attemt to retrieve `token` from cloud storage
const storedTokenStr = await cloudStorage?.getItem("token");

Managing Fullscreen

This function manages the fullscreen state and provides requestFullscreen and exitFullscreen methods.

Public Methods:

• getIsFullscreen(): Returns the current fullscreen state.
• getError(): Returns the current error state.
• requestFullscreen(): Attempts to enter fullscreen mode and resets any previous errors.
• exitFullscreen(): Attempts to exit fullscreen mode and resets any previous errors.
• onFullscreenChange(callback): Registers a callback to be called when the fullscreen state changes.
• offFullscreenChange(callback): Unregisters a previously registered fullscreen change callback.
• onError(callback): Registers a callback to be called when an error occurs.
• offError(callback): Unregisters a previously registered error callback.
• destroy(): Cleans up event listeners and handlers. Should be called when the manager is no longer needed.

import { createFullscreenManager } from "telegram-miniapp-tools/utils";

const fullscreenManager = createFullscreenManager();

if (fullscreenManager) {
  // Get the current fullscreen state
  const isFullscreen = fullscreenManager.getIsFullscreen();
  console.log(`Is fullscreen: ${isFullscreen}`);

  // Listen for fullscreen changes
  const handleFullscreenChange = (isFullscreen: boolean) => {
    console.log(`Fullscreen state changed: ${isFullscreen}`);
  };
  fullscreenManager.onFullscreenChange(handleFullscreenChange);

  // Listen for errors
  const handleError = (error: FullscreenError | null) => {
    if (error) {
      console.error(`Fullscreen error: ${error}`);
    }
  };
  fullscreenManager.onError(handleError);

  // Request fullscreen
  fullscreenManager.requestFullscreen();

  // Later, when you want to exit fullscreen
  // fullscreenManager.exitFullscreen();

  // When you're done, clean up
  // fullscreenManager.offFullscreenChange(handleFullscreenChange);
  // fullscreenManager.offError(handleError);
  // fullscreenManager.destroy();
} else {
  console.error("Fullscreen manager is not available.");
}

Types

Strongly typed interfaces are available to enhance TypeScript support for Telegram Mini Apps.

More details in /docs/md/types.md

import type { InitData, LaunchParams, ParsedThemeParams } from 'telegram-miniapp-tools/types';

// Example usage
const initData: InitData = { ... };

Exported Variables

The library provides direct access to the Telegram WebApp and environment variables.

import telegram, { webApp } from "telegram-miniapp-tools";

console.log(webApp.initData);
console.log(telegram);

You will find more details in the Telegram-MiniApp-Tools Documentation

Contributing

We welcome contributions! If you'd like to contribute to this project:

1. Fork the repository.
2. Create a new branch for your feature or bugfix.
3. Submit a pull request with a detailed description of your changes.

License

This package is open source and licensed under the Apache-2.0 License. See the LICENSE file for details.

Credits

This package was inspired by the amazing work done in:

• telegram-apps/sdk
• grammyjs/web-app

A big thank you to the developers and contributors of these projects for their invaluable work!