React Telegram MiniApp

Overview

React Telegram MiniApp is a developer-centric library tailored for seamless integration of Telegram Mini Apps into React and Next.js projects. It provides a rich set of hooks, components, and utilities to work with the Telegram WebApps API, enabling the creation of highly interactive experiences within Telegram.

Features

• 🌟 TelegramProvider: Efficiently manage the Telegram WebApp context state across your React components.
• 🔄 Custom Hooks: Simplified handling of Telegram WebApp events like theme changes, button interactions, and more.
• 🔐 Data Validation: Securely validate data received from the Telegram WebApp on your backend.
• 🛠️ TypeScript Support: Fully typed, ensuring a robust and type-safe development experience.
• 🎛️ Custom Script Loader: Automatically loads the Telegram WebApp script based on the environment.

Installation

Install the package using your preferred package manager:

npm install react-telegram-miniapp
# or
yarn add react-telegram-miniapp
# or
pnpm install react-telegram-miniapp

Getting Started

1. Wrap Your Application with TelegramProvider

Wrap your main application component with TelegramProvider to initialize the Telegram WebApp context.

import React from 'react';
import { TelegramProvider } from 'react-telegram-miniapp';

const MyApp = ({ Component, pageProps }) => (
  <TelegramProvider>
    <Component {...pageProps} />
  </TelegramProvider>
);

export default MyApp;

2. Utilize Hooks to Handle Telegram Events

Leverage the provided hooks to manage various Telegram WebApp events:

import React from 'react';
import { useThemeChanged, useMainButtonClicked } from 'react-telegram-miniapp';

const MyComponent = () => {
  useThemeChanged(() => {
    console.log("Theme changed!");
  });

  useMainButtonClicked(() => {
    console.log("Main button clicked!");
  });

  return <h1>Hello, Telegram User!</h1>;
};

export default MyComponent;

3. Validate Telegram WebApp Data on the Backend

Securely validate the data received from the Telegram WebApp using the validateWebAppData utility:

import { validateWebAppData } from 'react-telegram-miniapp';

const botToken = 'YOUR_BOT_TOKEN';

app.post('/validate-webapp-data', (req, res) => {
  const { initData } = req.body;

  const validationResult = validateWebAppData(initData, botToken);

  if (validationResult.isValid) {
    res.status(200).send('Data is valid');
  } else {
    res.status(400).send(`Invalid data: ${validationResult.reason}`);
  }
});

Documentation

Components

Component	Description	Props
TelegramProvider	Initializes and manages the Telegram WebApp context.	children: ReactNode - Components to wrap.

Hooks

Hook	Description	Example Usage
useThemeChanged	Handles the themeChanged event.	useThemeChanged(() => { console.log("Theme changed!"); });
useMainButtonClicked	Handles the mainButtonClicked event.	useMainButtonClicked(() => { console.log("Main button clicked!"); });
useViewportChanged	Handles the viewportChanged event.	useViewportChanged((event) => { console.log("Viewport changed:", event); });
useBackButtonClicked	Handles the backButtonClicked event.	useBackButtonClicked(() => { console.log("Back button clicked!"); });
useSettingsButtonClicked	Handles the settingsButtonClicked event.	useSettingsButtonClicked(() => { console.log("Settings button clicked!"); });
useInvoiceClosed	Handles the invoiceClosed event.	useInvoiceClosed((event) => { console.log("Invoice closed:", event); });
usePopupClosed	Handles the popupClosed event.	usePopupClosed((event) => { console.log("Popup closed:", event); });
useQrTextReceived	Handles the qrTextReceived event.	useQrTextReceived((event) => { console.log("QR text received:", event.data); });
useScanQrPopupClosed	Handles the scanQrPopupClosed event.	useScanQrPopupClosed(() => { console.log("QR scan popup closed!"); });
useClipboardTextReceived	Handles the clipboardTextReceived event.	useClipboardTextReceived((event) => { console.log("Clipboard text received:", event.data); });
useWriteAccessRequested	Handles the writeAccessRequested event.	useWriteAccessRequested((event) => { console.log("Write access requested:", event.status); });
useContactRequested	Handles the contactRequested event.	useContactRequested((event) => { console.log("Contact requested:", event.status); });
useBiometricManagerUpdated	Handles the biometricManagerUpdated event.	useBiometricManagerUpdated(() => { console.log("Biometric manager updated!"); });
useBiometricAuthRequested	Handles the biometricAuthRequested event.	useBiometricAuthRequested((event) => { console.log("Biometric auth requested:", event.isAuthenticated); });
useBiometricTokenUpdated	Handles the biometricTokenUpdated event.	useBiometricTokenUpdated((event) => { console.log("Biometric token updated:", event.isUpdated); });

Utilities

validateWebAppData

• Description: Validates the integrity of data received from the Telegram WebApp.
• Parameters:
  • initData: string - The data received from the WebApp.
  • botToken: string - Your bot’s token.
• Returns: { isValid: boolean, reason?: string }
• Example Usage:

const validationResult = validateWebAppData(initData, botToken);

if (validationResult.isValid) {
  console.log("Data is valid");
} else {
  console.log("Invalid data:", validationResult.reason);
}

Advanced Usage

Centralized Event Management

To manage multiple Telegram WebApp events centrally, utilize a custom hook or context:

import { useGlobalEventManager } from 'react-telegram-miniapp';

const { registerEvent, unregisterEvent } = useGlobalEventManager();

useEffect(() => {
  const themeHandler = () => console.log('Theme changed!');
  registerEvent('themeChanged', themeHandler);

  return () => unregisterEvent('themeChanged', themeHandler);
}, [registerEvent, unregisterEvent]);

Customizing Event Handling

Tailor event handling with options like debounce, throttle, once, and debug:

useThemeChanged(() => {
  console.log('Theme changed!');
}, { debounce: 300, debug: true });

Debugging Tips

• Enable Debug Mode: Pass { debug: true } to any hook to log detailed event information.
• Inspect Validation Failures: When using validateWebAppData, check the reason to understand validation issues.

Contributing

We welcome contributions, issues, and feature requests! Check the issues page to see how you can help.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgements

Special thanks to the contributors and the Telegram team for their exceptional platform.

---

Developed by CodedPro

---