Skip to main content

​
Overview

grammY is available for multiple JavaScript runtimes and can be installed using your preferred package manager. Choose the installation method that matches your environment.
grammY requires Node.js 12.20.0 or higher, or the latest version of Deno.

​
Node.js Installation

grammY is available on npm as the grammy package. You can install it using any Node.js package manager. 
npm install grammy

​
Usage in Node.js

After installation, import grammY in your project: 
const { Bot } = require("grammy");

const bot = new Bot("YOUR_BOT_TOKEN");
bot.command("start", (ctx) => ctx.reply("Hello!"));
bot.start();

​
Version Requirements

grammY supports the following Node.js versions:
  • Node.js 12.20.0 or higher
  • Node.js 14.13.1 or higher (recommended)
  • All current LTS versions
Make sure your Node.js version meets the minimum requirements. You can check your version with node --version.

​
Deno Installation

grammY runs natively on Deno without any transpilation. All grammY packages are published to deno.land/x.

​
Usage in Deno

Import grammY directly from the Deno module registry: 
import { Bot } from "https://deno.land/x/grammy/mod.ts";

const bot = new Bot("YOUR_BOT_TOKEN");
bot.command("start", (ctx) => ctx.reply("Hello!"));
bot.start();

​
Running with Deno

When running your bot, you need to grant network permissions: 
deno run --allow-net bot.ts
You can also import specific versions:
import { Bot } from "https://deno.land/x/[email protected]/mod.ts";

​
Why Deno Support?

grammY is developed primarily for Deno and then compiled to Node.js. This approach provides:
  • Native Deno support with no transpilation needed
  • Modern JavaScript features out of the box
  • Type safety with built-in TypeScript support
  • Secure by default with explicit permissions
While grammY is Deno-first, the documentation is written Node.js-first since most bot developers still use Node.js. All examples work on both platforms.

​
Browser & Edge Installation

grammY can run in browsers and on edge platforms like Cloudflare Workers, Deno Deploy, and more.

​
Using Web Bundle (Node.js)

For Node.js projects that need browser compatibility: 
import { Bot } from "grammy/web";

const bot = new Bot("YOUR_BOT_TOKEN");
bot.command("start", (ctx) => ctx.reply("Hello!"));
The web bundle is included in the npm package and doesn’t require separate installation.

​
Using Deno Bundle

For browsers or edge runtimes, grammY is available as a JavaScript bundle via bundle.deno.dev: 
<script type="module">
  import { Bot } from "https://bundle.deno.dev/https://deno.land/x/grammy/mod.ts";
  
  const bot = new Bot("YOUR_BOT_TOKEN");
  // Note: Use webhooks instead of polling in browser environments
</script>

​
Cloudflare Workers Example

import { Bot } from "grammy/web";

export default {
  async fetch(request: Request) {
    const bot = new Bot("YOUR_BOT_TOKEN");
    
    bot.command("start", (ctx) => ctx.reply("Hello from Cloudflare!"));
    
    // Handle webhook
    if (request.method === "POST") {
      const update = await request.json();
      await bot.handleUpdate(update);
      return new Response("OK");
    }
    
    return new Response("Bot is running!");
  },
};
When running in browsers or edge environments, you must use webhooks instead of long polling. Long polling requires a persistent connection which isn’t available in these environments.

​
Package Exports

The grammY package provides multiple entry points for different use cases:

​
Main Export

import { Bot, Context } from "grammy";
Includes all core functionality:
  • Bot - Main bot class
  • Context - Context object for handling updates
  • Composer - Middleware composition
  • Api - Telegram Bot API wrapper
  • All convenience utilities (keyboard, inline query, etc.)

​
Web Export

import { Bot } from "grammy/web";
Browser-compatible bundle for:
  • Cloudflare Workers
  • Deno Deploy
  • Service Workers
  • Browser applications

​
Types Export

import type { Update, Message } from "grammy/types";
TypeScript type definitions for:
  • All Telegram Bot API types
  • Update types
  • Message types
  • And more
The grammy/types export provides access to the underlying @grammyjs/types package, which contains TypeScript definitions for the entire Telegram Bot API.

​
TypeScript Support

grammY has first-class TypeScript support with complete type definitions.

​
Installation for TypeScript

npm install grammy
npm install -D typescript @types/node

​
TypeScript Configuration

Add a tsconfig.json file to your project: 
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

​
Type Inference

grammY provides excellent type inference. Your editor will automatically suggest available methods and properties: 
import { Bot } from "grammy";

const bot = new Bot("YOUR_BOT_TOKEN");

bot.on("message:text", (ctx) => {
  // TypeScript knows ctx.message.text exists
  const text: string = ctx.message.text;
  
  // Autocomplete works for all methods
  ctx.reply(text.toUpperCase());
});
Use TypeScript for the best development experience. grammY’s types will help you catch errors early and provide helpful autocomplete suggestions.

​
Dependencies

grammY has minimal dependencies to keep your bundle size small:

​
Node.js Dependencies

  • @grammyjs/types - TypeScript definitions for Telegram Bot API
  • node-fetch - HTTP client for making API calls
  • abort-controller - For cancelling requests
  • debug - Debugging utility

​
Deno Dependencies

Deno version has zero dependencies - everything is built using Deno’s standard library.

​
Verifying Installation

After installation, verify that grammY is working correctly: 
const { Bot } = require("grammy");

const bot = new Bot("YOUR_BOT_TOKEN");
console.log("grammY installed successfully!");

bot.command("start", (ctx) => ctx.reply("It works!"));
bot.start();
Run the code and send /start to your bot. If you get a response, everything is working!

​
Updating grammY

​
Node.js

npm update grammy

​
Deno

Update the version number in your import URL: 
// Before
import { Bot } from "https://deno.land/x/[email protected]/mod.ts";

// After
import { Bot } from "https://deno.land/x/[email protected]/mod.ts";
Omit the version to always use the latest version (not recommended for production):
import { Bot } from "https://deno.land/x/grammy/mod.ts";

​
Troubleshooting

​
”Cannot find module ‘grammy’”

Make sure you’ve installed grammY: 
npm install grammy

​
“Error: Empty token!”

You need to provide a valid bot token from @BotFather: 
const bot = new Bot("YOUR_ACTUAL_TOKEN_HERE");

​
Permission Errors (Deno)

Make sure to grant network permissions: 
deno run --allow-net bot.ts

​
Node.js Version Too Old

Upgrade to Node.js 14.13.1 or higher: 
node --version  # Check your version
nvm install 20  # Install Node.js 20 (if using nvm)

​
Next Steps

Now that you have grammY installed, you’re ready to build your bot!

​
Getting Help

If you run into issues during installation:

Build docs developers (and LLMs) love

Get started for freeTalk to us