Plugins Catalog

grammY — Official Plugins Catalog

The grammY ecosystem ships ~25 first-party plugins under the @grammyjs/* npm scope. Each is small, focused, and composable. Install only what you need.

Install pattern

Every plugin follows the same shape:

npm install @grammyjs/<plugin-name>

import { somePlugin } from "@grammyjs/<plugin-name>";
bot.use(somePlugin(options));

A few plugins are transformers (modify outgoing API calls) instead of middleware — install them differently:

import { someTransformer } from "@grammyjs/<plugin-name>";
bot.api.config.use(someTransformer(options));

State & flow plugins

Menu plugin

import { Menu } from "@grammyjs/menu";

const menu = new Menu<MyContext>("main")
  .text("A", (ctx) => ctx.reply("clicked A"))
  .text("B", (ctx) => ctx.reply("clicked B")).row()
  .submenu("Open child", "child");

const child = new Menu<MyContext>("child")
  .text("X", (ctx) => ctx.reply("X"))
  .back("Back");

menu.register(child);
bot.use(menu);
bot.command("menu", (ctx) => ctx.reply("Menu:", { reply_markup: menu }));

Router plugin

import { Router } from "@grammyjs/router";

const router = new Router<MyContext>((ctx) => ctx.session.step);

router.route("name",  async (ctx) => { ctx.session.name = ctx.msg.text; ctx.session.step = "email"; });
router.route("email", async (ctx) => { /* … */ });

bot.use(router);

Context augmentation

Hydrate

import { hydrate, HydrateFlavor } from "@grammyjs/hydrate";

type MyContext = HydrateFlavor<Context>;
bot.use(hydrate());

bot.on(":photo", async (ctx) => {
  const status = await ctx.reply("Processing…");
  await processImage(ctx.msg.photo);
  await status.editText("Done!");
  setTimeout(() => status.delete().catch(() => {}), 3000);
});

parse-mode

import { hydrateReply, parseMode } from "@grammyjs/parse-mode";
import type { ParseModeFlavor } from "@grammyjs/parse-mode";

type MyContext = ParseModeFlavor<Context>;
bot.api.config.use(parseMode("MarkdownV2"));   // default for ctx.reply
bot.use(hydrateReply);

bot.command("start", (ctx) => ctx.replyWithMarkdownV2("*Hello* _world_"));

Localization

import { I18n } from "@grammyjs/i18n";

const i18n = new I18n<MyContext>({
  defaultLocale: "en",
  directory: "locales",      // locales/en.ftl, locales/es.ftl, …
});

bot.use(i18n);
bot.command("start", (ctx) => ctx.reply(ctx.t("welcome", { name: ctx.from?.first_name })));

API reliability

See the dedicated scaling-runner skill for runner / throttler / auto-retry details.

ratelimiter

import { limit } from "@grammyjs/ratelimiter";

bot.use(limit({
  timeFrame: 2000,     // 2 seconds
  limit: 3,            // max 3 messages
  onLimitExceeded: async (ctx) => {
    await ctx.reply("Slow down!");
  },
}));

autoquote

import { autoQuote } from "@grammyjs/auto-quote";
bot.use(autoQuote());     // every reply now quotes the message it answers

Chat administration

chat-members hydration

import { hydrateChatMember, type HydrateChatMemberFlavor, type HydrateChatMemberApiFlavor } from "@grammyjs/chat-members";

type MyContext = HydrateChatMemberFlavor<Context>;
type MyApi = HydrateChatMemberApiFlavor<Api>;

const bot = new Bot<MyContext, MyApi>(process.env.BOT_TOKEN!);
bot.api.config.use(hydrateChatMember());

bot.command("ban", async (ctx) => {
  const author = await ctx.getAuthor();
  if (!author.is("admin")) return ctx.reply("Admin only");
  await ctx.banAuthor();
});

commands plugin

import { Commands } from "@grammyjs/commands";

const myCommands = new Commands<MyContext>();
myCommands.command("start", "Start the bot", (ctx) => ctx.reply("Hi!"));
myCommands.command("help",  "Show help",      (ctx) => ctx.reply("Help"));
bot.use(myCommands);
await myCommands.setCommands(bot);

.localize(languageCode, name, description) adds per-language translations:

myCommands.command("start", "Start the bot", handler)
  .localize("es", "iniciar", "Empezar el bot")
  .localize("ru", "старт",  "Запустить бота");

Reception filters & helpers

media-group

import { mediaGroup } from "@grammyjs/media-group";

bot.use(mediaGroup());

bot.on(":media", async (ctx) => {
  // ctx.mediaGroup is the full album (array of Message), or undefined for single media
  console.log("album size:", ctx.mediaGroup?.length ?? 1);
});

Picking plugins — rules of thumb

• Multi-message dialog? → @grammyjs/conversations
• Bot uses Bot API rate limits? → @grammyjs/auto-retry + (if heavy outbound) @grammyjs/transformer-throttler
• Bot must answer 10k+ updates/s? → @grammyjs/runner
• Bot spans many languages? → @grammyjs/i18n or @grammyjs/fluent
• Bot has complex menus? → @grammyjs/menu
• Group bot needs admin checks? → @grammyjs/chat-members
• Markdown formatting? → @grammyjs/parse-mode
• Need to download files? → @grammyjs/files

When in doubt, check https://grammy.dev/plugins/ for the full list and READMEs.