Middleware

grammY — Middleware

grammY's update pipeline is a stack of middleware. bot.use() adds a function to the stack; each function calls await next() to hand off to the next one — like Koa or Express, but typed.

The signature

type Middleware<C extends Context> =
  (ctx: C, next: NextFunction) => unknown | Promise<unknown>;

type NextFunction = () => Promise<void>;

A middleware can:

1. Read or mutate ctx.
2. await next() to continue to the next middleware.
3. Not call next() — to stop the chain.

Execution order = registration order

bot.use(async (ctx, next) => { console.log("1 before"); await next(); console.log("1 after"); });
bot.use(async (ctx, next) => { console.log("2 before"); await next(); console.log("2 after"); });
bot.on("message", (ctx) => console.log("handler"));

Receiving a message logs:

1 before
2 before
handler
2 after
1 after

This is the same onion model as Express — outer middleware sees both the request and the response.

Mounting handlers and other Composers

A Composer is a fluent middleware builder. Bot itself is a Composer. You can build sub-routers and mount them:

import { Bot, Composer } from "grammy";

const adminRouter = new Composer<MyContext>();
adminRouter.command("ban", (ctx) => { /* … */ });
adminRouter.command("kick", (ctx) => { /* … */ });

const bot = new Bot<MyContext>(process.env.BOT_TOKEN!);
bot.use(async (ctx, next) => {
  if (await isAdmin(ctx.from?.id)) await next();
});
bot.use(adminRouter); // only admins reach these commands

Composer methods

Custom middleware example

// Tag each ctx with a unique request id and log start/end
const requestId: Middleware<Context> = async (ctx, next) => {
  const id = crypto.randomUUID();
  console.log(`[${id}] start update=${ctx.update.update_id}`);
  const start = Date.now();
  try {
    await next();
  } finally {
    console.log(`[${id}] done in ${Date.now() - start}ms`);
  }
};
bot.use(requestId);

Authorization middleware (stop the chain)

bot.use(async (ctx, next) => {
  if (BANNED_USER_IDS.has(ctx.from?.id ?? 0)) {
    return; // do not call next() — banned users go no further
  }
  await next();
});

errorBoundary — local error handling

bot.catch (see error-handling) is the catch-all last resort. To handle errors only in a sub-branch without bubbling up, use errorBoundary:

const safe = bot.errorBoundary(
  (err) => console.error("admin branch crashed:", err),
  adminRouter,
);

// Suppress errors silently in a different branch
const suppress = (_err: BotError, next: NextFunction) => next();
bot.errorBoundary(suppress).on("edited_message", noisyMiddleware);

fork — run middleware in parallel

// Log message length without blocking the main handler chain
bot.fork(async (ctx) => {
  await metrics.record("update", { type: ctx.update });
});
bot.on("message", mainHandler); // runs alongside the fork, not after it

Common plugin ordering

When stacking grammY plugins, ordering matters:

bot.use(session({ initial: () => ({ counter: 0 }) }));   // 1. session first
bot.use(conversations());                                 // 2. conversations needs session
bot.use(hydrate());                                       // 3. hydrate attaches helpers
bot.use(i18n.middleware());                               // 4. i18n
bot.use(myAuthMiddleware);                                // 5. business middleware
bot.use(createConversation(myConvo));                     // 6. individual conversations
bot.command("start", startHandler);                       // 7. handlers
bot.catch(globalErrorHandler);                            // 8. catch-all LAST

Forgetting "session before conversations" gives an obscure cannot serialize conversation error.

What this skill does NOT cover

• The full filter-query grammar (use filter-queries).
• Plugin-specific middleware patterns (use plugins-catalog for the catalog; sessions/conversations for those two).
• Error catching strategies beyond errorBoundary (use error-handling).