website·Indexed 33 days ago
https://docs.telegram-mini-apps.comDocumentation for building web applications within Telegram. Includes guides on the platform's viewport, theming, and closing behavior, as well as technical details on init data validation, user authorization, and app communication via methods and events. Features documentation for the tma.js SDK, bridge, and Node.js init-data validation packages.
@tma.js/sdk package for most application needs.Telegram Mini Apps operate in a web-based environment provided by the Telegram native application. Communication between the native app and the Mini App is based on two primary patterns:
miniApp component must be mounted before use. To ensure properties have correct values, themeParams must be mounted before calling miniApp.mount(). The isMounted signal tracks the current state. Use unmount() to tear down the component.import { miniApp, themeParams } from '@tma.js/sdk';
// Correct mounting sequence
themeParams.mount();
miniApp.mount();
console.log(miniApp.isMounted()); // true
// Unmounting
miniApp.unmount();
console.log(miniApp.isMounted()); // false@tma.js/sdk-react package provides React.js utilities for Telegram Mini Apps. It has react as a peer dependency and fully re-exports the @tma.js/sdk package, meaning you do not need to install the base SDK separately.# Using pnpm
pnpm i @tma.js/sdk-react
# Using npm
npm i @tma.js/sdk-react
# Using yarn
yarn add @tma.js/sdk-reactsecondaryButton must be mounted to work with properly configured properties. Because it depends on the miniApp and themeParams components, those must be mounted first. Use the mount() method to initialize and unmount() to clean up. The isMounted signal tracks the current state.import { secondaryButton, miniApp, themeParams } from '@tma.js/sdk';
// Order of mounting is critical
miniApp.mount();
themeParams.mount();
secondaryButton.mount();
console.log(secondaryButton.isMounted()); // true
secondaryButton.unmount();
console.log(secondaryButton.isMounted()); // false@tma.js/init-data-node package to handle Telegram Mini Apps initialization data on the server side using npm, pnpm, or yarn.pnpm i @tma.js/init-data-node
# or
npm i @tma.js/init-data-node
# or
yarn add @tma.js/init-data-nodeon(*), the callback now receives an object with properties event: string and payload?: any instead of a tuple. The typing of the payload depends on the event property.@tma.js/bridge package provides functional alternatives to its standard functions (suffixed with Fp). Instead of throwing exceptions, these functions return errors as values. It is recommended to use a library like fp-ts to process these results, typically using the Either type to handle success and failure cases explicitly.import * as E from 'fp-ts/Either';
import { pipe } from 'fp-ts/function';
import { postEventFp, retrieveLaunchParamsFp } from '@tma.js/bridge';
// Example: Posting an event functionally
pipe(
postEventFp('web_app_expand'),
E.match(
error => {
// Handle the specific error here
},
() => {
// Success case
}
)
);
// Example: Retrieving launch parameters functionally
pipe(
retrieveLaunchParamsFp(),
E.match(
error => {
// Handle error
},
launchParams => {
// Use the retrieved launch parameters
}
)
);@tma.js/bridge, the onEvent option in mockTelegramEnv no longer receives a tuple. It now receives an object containing event: string and params?: any. The specific typing of the object depends on the value of the event property.