nestjs-telegraf puts Telegram bot handlers inside a NestJS application

The value is that a bot handler becomes a Nest provider

nestjs-telegraf is presented as a powerful solution for creating Telegram bots, and the framing in the README is that the package uses the best of the NodeJS world under the hood. Telegraf is described as the leading library for creating bots and NestJS as a progressive framework for creating well-architectured applications, and this module provides a fast and easy way for creating Telegram bots with deep integration with your NestJS application. The practical difference from using Telegraf on its own is where the handler code lives. In plain Telegraf, a command is a function you register on a bot instance, which is fine until the handler needs a service from your application, or needs the same configuration, or should be guarded by the same authorisation logic. Here, the handler is a provider in a Nest module, so dependency injection, lifecycle hooks and configuration all work the way they do elsewhere in the application. The features list calls it simple and easy to use, with a ton of decorators available out of the box for handling bot actions.

Guards, interceptors, filters and pipes apply to bot actions

The strongest line in the feature list is that there is full support of NestJS guards, interceptors, filters and pipes. That is the claim worth examining, because it is the difference between a bot that is bolted onto a Nest application and a bot that is part of it. A guard is how you decide whether a given action may run, an interceptor wraps the execution of it, a filter catches the exceptions it throws, and a pipe transforms the arguments before the handler sees them. If those all work on bot actions, then the authorisation logic that protects your HTTP endpoints can protect a bot command with the same decorator, and the validation that runs on an HTTP body can run on a bot argument. The README also states the ability to create custom decorators, which is the other half of the value, since a team that writes its own decorator for a recurring pattern gets the same treatment on both sides of the application.

Scenes and plugins cover the two features bots need most

Two features in the list are worth separating out because they are the ones that most often force a bot to be written by hand. The first is scenes support, which is Telegraf's mechanism for multi-step conversations, where a user answers a question, the bot asks another, and the intermediate state has to be held between messages. The second is the support for Telegraf plugins and custom plugins, which is how a bot grows beyond its own commands. The README also mentions the ability to run multiple bots simultaneously, which matters for a team that operates a support bot, an admin bot and a notification bot from one service. The custom decorator ability overlaps with this, since a decorator over a bot action is how a project defines its own command surface with shared validation and shared context.

Installing means pulling Nest and Telegraf together

The install command pulls both the module and the bot library it wraps, which is the detail that matters because the two versions have to agree:

$ npm i nestjs-telegraf telegraf

The documentation is published as a site at nestjs-telegraf.gesh.app, and the repository itself is the source for it, with a .vitepress/ directory and a docs/ directory holding the content, plus a separate typedoc configuration in tsconfig.typedoc.json for the API reference. The package metadata shows the published entry points, with main at ./dist/index.js and types at ./dist/index.d.ts, and the build script is a plain tsc compile into dist with a clean step in front of it. The only runtime dependency is lodash, and the Nest packages themselves are dev dependencies, which is the normal pattern for a library that treats Nest as a peer rather than bundling it. The sample/ directory holds a single complete application, 01-complete-app, which is the fastest way to see the module wired into a real Nest project.

The repository carries its own conventions for commits and formatting

The package scripts show how the project is maintained. The build is rm -rf dist followed by tsc against tsconfig.json, and prepublish:npm runs the build before the publish, so the artefact on npm is always compiled from the current source. The lint-staged configuration runs prettier --write over staged TypeScript files, and husky installs two hooks, a pre-commit running lint-staged and a commit-msg running commitlint with the angular configuration and the HUSKY_GIT_PARAMS environment. The commitlint config at the root is the standard Angular preset, which fixes the commit message format for the whole team. The eslint setup is flat config with the typescript-eslint plugin, and the .npmignore file keeps the package tarball lean. The one thing that stands out is the test script, which is an empty string, so there is no automated test suite in the repository. That is worth knowing before you build on the module, because it means you are trusting the published version rather than a test run you can reproduce locally.

Where nestjs-telegraf is the wrong choice

Three situations argue against it. The first is a standalone bot with no application around it. A bot that reads a token, answers a few commands and runs on a small instance is a few dozen lines of Telegraf, and a Nest application brings a module system, a dependency injection container, a decorator pipeline and a framework you now have to keep on a supported Nest version for the sake of one bot. The second is a team that wants bot handlers to behave differently from the HTTP side. If the bot should not share your guards, your filters or your validation, then the integration is a cost rather than a benefit, and you have inherited two execution models where you wanted one. The third is a codebase that has moved off NestJS common and core, since the dev dependencies pin them at 11.1.0 and the module is built around the Nest provider and decorator model rather than around Telegraf itself. The realistic alternative is Telegraf used directly, with your own thin adapter for the shared services, which is less integration and more control, and is the better fit for a bot whose handlers are mostly self-contained.

Editorial conclusion

Adopt nestjs-telegraf when your Telegram bot is part of a larger NestJS service and you want the same dependency injection, guards and error handling as the HTTP side, and use Telegraf directly when the bot is a standalone script. Verify first which Telegraf version you install alongside it, since the install command pulls both packages and the two must match, and read the documentation site for the decorator list before designing handlers around it.

Frequently asked questions

Official sources

1. License: MIT
2. nksmnf/nestjs-telegraf on GitHub
3. Project website
4. README
5. Releases