grammY

grammY is a middleware-based framework for building Telegram bots in TypeScript or JavaScript. It wraps the full Telegram Bot API in a typed Context object and a Koa/Express-style Composer chain, letting bots be built as a pipeline of small, testable middleware functions instead of one large update handler.

It runs unmodified on Node.js, Deno, and Bun, and ships a large first-party plugin ecosystem (sessions, conversations, rate limiting, files, runner for scaling long polling) maintained under the same grammyjs organization, making it the most actively maintained Telegram bot framework in the JavaScript ecosystem.

What You Get

• A Bot class handling long polling or webhook-based update delivery
• A Composer/middleware system (bot.use(), bot.on(), bot.command(), bot.filter()) for organizing handlers
• A fully-typed Context object exposing update data plus shortcut reply/API methods
• Cross-runtime builds for Node.js, Deno, and browser/edge (Cloudflare Workers) environments
• An official plugin ecosystem (@grammyjs/session, conversations, runner, ratelimiter, files) for common bot needs

Common Use Cases

• Building production Telegram bots with structured, testable middleware pipelines
• Deploying bots to serverless/edge platforms like Cloudflare Workers via the web build target
• Scaling bots that need to process high update volume using the runner plugin’s concurrent long-polling
• Stateful bots (multi-step forms, wizards) via the conversations plugin’s sequential flow API

Under The Hood

Architecture: The core lives in src/, centered on bot.ts (update loop and API client wiring), composer.ts (the middleware chaining engine implementing .use, .on, .command, .filter with the filter.ts predicate system), and a large context.ts (4,800+ lines) that flattens every Telegram Bot API method and update field onto one ergonomic Context object; src/core/ holds the low-level client.ts/api.ts/payload.ts that talk to the Telegram Bot API over HTTP. Platform-specific entry points (platform.node.ts, platform.deno.ts, platform.web.ts) isolate the few runtime differences (fetch, AbortController, file handling) so the same middleware code runs everywhere. Tech Stack: Written in TypeScript against the Deno runtime first, then back-compiled to Node.js via deno2node; runtime dependencies are minimal (@grammyjs/types for Bot API types, debug, node-fetch, abort-controller), keeping the core dependency-light. Code Quality: An 18-file test/ suite (Deno’s built-in test runner) covers the composer/middleware chain, context helpers, and API client behavior; the project has shipped 88 tagged releases with a steady ~6 commits/month cadence and strict TypeScript throughout. API Design: The middleware model (bot.on('message:text', ctx => ...)) mirrors Express/Koa conventions familiar to JS/TS developers, and the typed Context (auto-completing every Bot API field and shortcut method in an editor) minimizes the boilerplate of looking up raw Telegram API responses.