@eyenalxai/tma-sdk
v0.3.0
Published
TypeScript SDK for Telegram Mini Apps with React bindings and server init-data validation.
Maintainers
Readme
@eyenalxai/tma-sdk
TypeScript SDK for Telegram Mini Apps with React bindings and server init-data validation.
This package is unofficial and is not affiliated with Telegram.
Installation
npm install @eyenalxai/tma-sdkReact is required only when using the /react entry point:
npm install @eyenalxai/tma-sdk reactEntry points
@eyenalxai/tma-sdkexports framework-neutral Mini App session and launch-data APIs.@eyenalxai/tma-sdk/reactexports the React provider and hooks.@eyenalxai/tma-sdk/serverexports Node.js init-data validation helpers.
The root entry is safe to import during server rendering, but functions such as createSession() and retrieveLaunchParams() must be called in a browser launched by Telegram.
React usage
import { SessionProvider, useSession } from "@eyenalxai/tma-sdk/react"
import { useEffect } from "react"
const App = () => (
<SessionProvider fallback={null}>
<Main />
</SessionProvider>
)
const Main = () => {
const session = useSession()
useEffect(() => {
session.markReady()
}, [session])
return <div>User: {session.initData?.user?.first_name ?? "Unknown"}</div>
}SessionProvider creates the session on the client, mounts the viewport, binds Telegram's viewport, safe-area and theme CSS variables (--tg-viewport-height, --tg-viewport-stable-height, --tg-safe-area-inset-*, --tg-content-safe-area-inset-*, --tg-theme-*, --tg-color-scheme), and destroys the session when unmounted. It renders fallback until the session starts.
The provider leaves readiness to the app by default. Call session.markReady() when your first screen is ready, or set autoReady to mark the Mini App ready as soon as start() resolves. Pass onError to receive initialization failures instead of throwing to the nearest React error boundary. expand and disableVerticalSwipes default to false, so the provider does not change native behavior unless asked.
Client usage
import { createSession } from "@eyenalxai/tma-sdk"
const session = createSession()
await session.start()
session.markReady()
session.features.viewport.actions.expand()
// Later, when leaving the Mini App:
session.destroy()createSession() returns synchronously and installs the Telegram event bridge before any await. Init data is nullable because some launches have none; call session.requireInitData() when the app cannot work without it. A passive bridge captures viewport, fullscreen, safe-area, theme and visibility events from module import, so an event that arrives before createSession() is delivered to the first subscriber. Stateful events then keep their last payload and replay it to a later subscriber.
The read-only session status moves from launched to mounted and then ready, and ends at closed after destroy(). A failed start leaves it at failed until destroy(); markReady() only takes effect after mount and sends web_app_ready.
Features
session.features is one registry of controllers. Every controller has the same shape:
type FeatureController<State, Actions> = {
supported: boolean
state: ReadonlyStore<State>
actions: Actions
}supported comes from the protocol table, state is read-only (get() and subscribe(), which the React hooks use), and actions holds the user-facing calls. The registry covers theme, viewport, back button, main button, secondary button, settings button, closing behavior, swipe behavior, haptics, links, downloads, write access, dialogs and clipboard.
const session = createSession()
await session.start()
// Theme: store, request and CSS-variable binder
const theme = await session.features.theme.actions.request()
session.features.theme.actions.setHeaderColor("#1c1c1d")
const unbindTheme = session.features.theme.actions.bindCssVars()
// Bottom buttons: uniform set(partial) and onClick(listener)
session.features.mainButton.actions.set({ isVisible: true, text: "Pay" })
session.features.mainButton.actions.onClick(() => {
// handle the press
})
// Dialogs and clipboard
const pressed = await session.features.dialogs.actions.show({
message: "Delete this item?",
buttons: [
{ id: "delete", type: "destructive" },
{ id: "cancel", type: "cancel" },
],
})
const confirmed = await session.features.dialogs.actions.confirm("Continue?")
const text = await session.features.clipboard.actions.read()
// Downloads resolve with the status instead of throwing on cancel
const status = await session.features.downloads.actions.request(
"https://example.com/file.pdf",
"file.pdf",
)mainButton, secondaryButton and settingsButton share set(partial) and onClick(listener). set merges the partial into the stored state and posts the whole button state; the secondary button state also carries position, and the settings button also keeps show() and hide(). Dialogs resolve with the pressed button id (or null), alert() resolves, and confirm() resolves to a boolean. Clipboard reads resolve with the text or null. A cancelled download is the "cancelled" status, not an error.
For a method without a controller, session.protocol.invoke(method, params) remains the escape hatch; session.protocol.request(...) covers the methods that answer with an event.
Launch parameters and init data
import { parseInitData, parseLaunchParams, retrieveLaunchParams } from "@eyenalxai/tma-sdk"
const launchParams = retrieveLaunchParams()
const initData = parseInitData(launchParams.tgWebAppData ?? "")
const parsedLaunchParams = parseLaunchParams(new URLSearchParams(location.search))retrieveLaunchParams() preserves validated Telegram launch parameters in session storage so client-side navigation does not discard the original launch context.
Platform capability
import { getPlatform, retrieveLaunchParams } from "@eyenalxai/tma-sdk"
const platform = getPlatform(retrieveLaunchParams().tgWebAppPlatform)
platform.kind // "mobile" | "desktop" | "web" | "unknown"
platform.supportsViewport // true when the client provides a usable viewport height
platform.isEmbeddedWeb // true for web, weba and webkgetPlatform() replaces isDesktopPlatform(). The old desktop predicate is kind === "desktop" || kind === "web"; use supportsViewport for the viewport request strategy. macOS is a desktop client that answers with a null payload, so it does not request a viewport and uses the window height.
Server validation
import { validateInitData } from "@eyenalxai/tma-sdk/server"
const initData = validateInitData(rawInitData, process.env.BOT_TOKEN, {
expiresIn: 86_400,
})validateInitData() verifies the Telegram HMAC, validates auth_date, applies expiration, parses the signed payload, and throws on failure. Use isInitDataValid() when a boolean check is preferred.
A third party without the bot token can verify the same init data with Telegram's Ed25519 public key:
import { validateInitDataSignature } from "@eyenalxai/tma-sdk/server"
const initData = validateInitDataSignature(rawInitData, {
botId: 1234567890,
publicKey: "e7bf03a2fa4602af4580703d88dda5bb59f32ed8b02a56c187fe7d34caed242d",
expiresIn: 86_400,
})Pass Telegram's production key for production init data and the test key for test-environment data. The key is the raw 32-byte hex value from the Telegram documentation.
Keep the bot token server-side. Never expose it to Mini App client code.
Requirements
- Node.js
^22.18.0,^24.11.0, or>=26.0.0for the/serverentry point. - React 19 or newer for the
/reactentry point. - A browser environment launched inside Telegram for Mini App session APIs.
- ESM-compatible module resolution.
