npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@eyenalxai/tma-sdk

v0.3.0

Published

TypeScript SDK for Telegram Mini Apps with React bindings and server init-data validation.

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-sdk

React is required only when using the /react entry point:

npm install @eyenalxai/tma-sdk react

Entry points

  • @eyenalxai/tma-sdk exports framework-neutral Mini App session and launch-data APIs.
  • @eyenalxai/tma-sdk/react exports the React provider and hooks.
  • @eyenalxai/tma-sdk/server exports 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 webk

getPlatform() 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.0 for the /server entry point.
  • React 19 or newer for the /react entry point.
  • A browser environment launched inside Telegram for Mini App session APIs.
  • ESM-compatible module resolution.

License

MIT