tma.js: a TypeScript toolkit for building Telegram Mini Apps

A monorepo of packages, examples and a documentation app

The repository describes itself as a mono-repository containing all the packages, connected with comfortable and safe TypeScript development on the Telegram Mini Apps platform, and the description of the contents is equally direct, that these are made from scratch TypeScript packages, examples and documentation you will surely need to start developing on Telegram Mini Apps. The root listing shows how that is laid out. There is a packages/ directory for the published libraries, an apps/ directory holding the documentation site, and a pnpm-workspace.yaml with a pnpm-lock.yaml, which means the whole thing is a pnpm workspace rather than a single package. The build is driven by turbo, with a turbo.json at the root, and the release pipeline is built around changesets, with a .changeset/ directory and the changesets CLI in the dev dependencies.

The published packages are published together under one scope

The release history shows the shape of the output. Three releases landed on the same day in July 2026, @tma.js/sdk at 3.3.0, @tma.js/sdk-vue at 1.0.23 and @tma.js/sdk-svelte at 1.0.23, which is the signature of a monorepo where a change to a shared core bumps several packages at once. The core package is @tma.js/sdk, and the framework-specific packages, sdk-vue and sdk-svelte, sit alongside it rather than replacing it, so a project on Vue or Svelte gets a binding shaped for that framework while the rest of the stack stays shared. The version numbers themselves are worth reading: the core is at 3.x while the framework packages are at 1.0.x, which suggests the framework adapters are younger and less settled than the core they wrap.

The project exists because the official SDK did not meet its quality bar

The README has a section headed Why not Telegram SDK, and it addresses the obvious question directly, asking why bother creating a project like @tma.js when there are existing solutions from the developers who own the platform. The answer given is that the currently provided solution does not seem to meet the required minimum quality standards, with the acknowledgement that quality is a specific and subjective term and an intention to make the section more objective. The comparison target is named, telegram-web-app.js, which the README calls the only existing official SDK for Telegram Mini Apps by Telegram, and the project says it was born during the research of a solution provided by Telegram. The full argument is long enough that it was moved into a separate document, MOTIVATION.md, at the root of the repository, and that document is the right starting point if you want to know what the author thinks the official script gets wrong.

Two documentation sources, and the platform's own docs as a cross-check

The Getting Started section is short and points in three directions. The first is the community-built documentation at docs.telegram-mini-apps.com, which the README recommends as a great starting point for learning about the platform, and which is also where the list of available libraries lives for both client-side and backend development. The second is the official Telegram platform documentation on web apps, which the README says can provide valuable insights and a different perspective on the platform, and the phrasing about a different perspective is a fair hint that the two sources do not say exactly the same things. The third pointer is to explore the available libraries before diving into development, so that you understand the tools at your disposal. The homepage field of the repository is the same community documentation site, and the platform version in play is covered by a V4_CHANGES.md file at the root.

One command surface for packages, docs and checks

The root package.json is private, which is what you would expect of a workspace root, and its scripts show the shape of the pipeline. The dev script runs turbo run dev, the packages:build script filters turbo to the packages directory, and the docs:build and docs:dev scripts filter to the docs app instead.

"packages:build": "turbo run build --filter=\"./packages/*\"",
"packages:lint": "turbo run lint --filter=\"./packages/*\"",
"packages:test": "vitest --run --retry 3",
"packages:typecheck": "turbo run typecheck --filter=\"./packages/*\"",
"docs:dev": "turbo run dev --filter=\"./apps/docs\""

The ci:packages:rollup script is the full local gate in one line, installing, building, linting, type checking and testing in sequence, which is a useful thing to copy into your own fork. The test runner is Vitest with coverage, and the tooling around it is current rather than legacy, with TypeScript 6.0.3, Vite 6.3.3, Rollup, ESLint 9 and the typescript-eslint plugin, plus husky and commitizen with the conventional changelog preset for commit messages.

A community project with the usual governance files in place

The root listing carries the files you would expect from a project inviting outside contributions, a CODE_OF_CONDUCT.md, a CONTRIBUTING.md, an AGENTS.md, a CLAUDE.md and a .gitattributes, alongside an eslint.config.js at the root. The README's contribution section is brief, that any contribution is appreciated and that the Contribution Guidelines document explains the process. There is a commitizen friendly badge, and the commit script runs git cz, so the conventional changelog format is enforced at commit time rather than asked for in review. The licence is MIT, the default branch is master, the last push to the repository was on 2026-10-12, and the repository publishes no GitHub releases, with versioning handled through the changesets pipeline instead.

Editorial conclusion

tma.js fits a TypeScript team building a Telegram Mini App who wants the platform bridge behind typed packages rather than a global object, since the monorepo ships separate SDK builds for plain TypeScript, Vue and Svelte and the packages are versioned together through changesets. It is a poor fit if you need a single small dependency, since this is a workspace with an apps/ directory for the docs site and a packages/ directory of several builds, and a poor fit if you want the platform's own reference script, since the whole premise of the project is that it replaces that. Verify first which of the SDK packages covers your framework and read the MOTIVATION.md document before adopting it, because the project's argument for existing is a quality judgement you should check against your own needs rather than take on trust.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. Telegram-Mini-Apps/tma.js on GitHub