Nestgram v2.0
Docs/Introduction

Installation

Nestgram is a normal npm package that plugs into a NestJS project. If you have a Nest app, you’re one install away.

Requirements

  • Node.js 18+ (the engine uses the built-in fetch and FormData).
  • NestJS 10+ — @nestjs/common and @nestjs/core are peer dependencies, so a standard Nest project already satisfies them.

Install

Terminal
npm install nestgram@next

Nestgram is decorator-driven, so the compiler needs experimentalDecorators and emitDecoratorMetadata (the standard Nest setup already enables both). A fresh Nest project on TypeScript 6 also turns on isolatedModules — and that combination has one sharp edge worth knowing before you write your first handler (see the next section).

tsconfig.json
{
  "compilerOptions": {
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "target": "es2022",
    "strict": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "isolatedModules": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "outDir": "dist"
  }
}

Importing event types

With isolatedModules and emitDecoratorMetadata both on (the TypeScript 6 default for new projects), the compiler refuses to read a type out of a value import when that type appears in a decorated handler signature:

error TS1272: A type referenced in a decorated signature must be imported with
'import type' or a namespace import when 'isolatedModules' and
'emitDecoratorMetadata' are enabled.

It fires on any handler with a param decorator — start(message: Message, @Sender() user: User) trips it on User. The fix is to split the import: values (decorators, classes, free functions) stay a normal import; event types come in through import type:

greet.router.ts
import { Router, OnStart, Sender } from 'nestgram'; // values
import type { Message, User } from 'nestgram'; // types

@Router()
export class GreetRouter {
  @OnStart()
  start(message: Message, @Sender() user: User) {
    return `Hello, ${user.first_name}!`;
  }
}

Get a bot token

Every bot needs a token from Telegram’s @BotFather:

  1. Open a chat with @BotFather and send /newbot.
  2. Pick a name and a username ending in bot.
  3. Copy the token it gives you (looks like 123456789:AAExxxx...).

Keep the token out of source control — load it from the environment:

Terminal
BOT_TOKEN=123456789:AAExxxx... node dist/main.js

With Nestgram installed and a token in hand, you’re ready for the quickstart.