🤖 Telegram Bot Boilerplate

A production-ready Telegram bot template built with Node.js, TypeScript, MongoDB, and Docker. Includes auto-tunneling via ngrok for seamless local development with webhooks.

---

✨ Features

• 🏗️ TypeScript — Fully typed codebase with strict mode
• 🍃 MongoDB + Mongoose — Database ready out of the box
• 🎯 grammY — Modern, fast Telegram Bot framework
• 🌐 Auto ngrok tunneling — Webhooks work locally without manual setup
• 🐳 Docker & Docker Compose — One-command dev environment with hot reload
• 🔄 3 bot modes — Polling, webhook, and auto-ngrok (auto-detected)
• 🛑 Graceful shutdown — Clean cleanup of bot, tunnel, and server
• ⚡ Hot reload — Instant feedback during development

---

📁 Project Structure

├── src/
│   ├── index.ts          # Entry point — mode detection & server setup
│   ├── bot.ts            # Bot commands & message handlers
│   ├── config.ts         # Environment config loader
│   └── db/
│       └── connection.ts # MongoDB connection handler
├── .env.example          # Environment variables template
├── docker-compose.yml    # Docker services (app + MongoDB)
├── Dockerfile            # Multi-stage build (dev + prod)
├── tsconfig.json         # TypeScript configuration
├── nodemon.json          # Nodemon config for Docker hot reload
└── package.json

---

🚀 Quick Start

Prerequisites

• Node.js v20+
• MongoDB (local or Atlas) — or just use Docker
• A Telegram bot token from @BotFather

1. Use this template

Click the "Use this template" button on GitHub, or clone it:

git clone https://github.com/YOUR_USERNAME/telegram-bot-boilerplate.git
cd telegram-bot-boilerplate

2. Install dependencies

npm install

3. Configure environment

cp .env.example .env

Edit .env with your values:

BOT_TOKEN=your_bot_token_here
MONGO_URI=mongodb://localhost:27017/telegram-bot
PORT=3000
NGROK_AUTHTOKEN=your_ngrok_authtoken_here  # Optional, for webhook mode

4. Start the bot

npm run dev

That's it! 🎉 Send /start to your bot on Telegram.

---

🔄 Bot Modes

The bot automatically selects the best mode based on your environment variables:

Priority	Condition	Mode	Best For
1	WEBHOOK_URL is set	Production Webhook	Deployed servers
2	NGROK_AUTHTOKEN is set	Auto Ngrok Tunnel	Local dev with webhooks
3	Neither is set	Long Polling	Simplest local dev

Polling Mode (default)

No public URL needed. The bot polls Telegram for updates:

BOT_TOKEN=your_token
# No WEBHOOK_URL or NGROK_AUTHTOKEN

Ngrok Mode (auto-tunnel)

Automatically creates a public URL via ngrok and sets the webhook:

BOT_TOKEN=your_token
NGROK_AUTHTOKEN=your_ngrok_token

Get your free auth token at dashboard.ngrok.com

Production Webhook Mode

Uses your own public URL:

BOT_TOKEN=your_token
WEBHOOK_URL=https://your-domain.com

---

🐳 Docker

Development (with hot reload)

docker-compose up

This starts:

• App container — with hot reload via volume mounts
• MongoDB container — persistent data in a Docker volume

Edit files in src/ and changes reflect instantly.

Production

docker build --target production -t telegram-bot .
docker run --env-file .env telegram-bot

---

🛠️ Available Scripts

Script	Description
npm run dev	Start with hot reload (tsx watch)
npm run dev:docker	Start with hot reload in Docker (nodemon)
npm run build	Compile TypeScript to dist/
npm start	Run compiled production build

---

🧩 Extending the Bot

Adding a new command

Edit src/bot.ts:

bot.command("ping", async (ctx) => {
  await ctx.reply("🏓 Pong!");
});

Adding a Mongoose model

Create src/models/user.ts:

import mongoose from "mongoose";

const userSchema = new mongoose.Schema({
  telegramId: { type: Number, required: true, unique: true },
  username: String,
  firstName: String,
  createdAt: { type: Date, default: Date.now },
});

export const User = mongoose.model("User", userSchema);

Use it in your bot:

import { User } from "./models/user.js";

bot.command("start", async (ctx) => {
  await User.findOneAndUpdate(
    { telegramId: ctx.from?.id },
    {
      username: ctx.from?.username,
      firstName: ctx.from?.first_name,
    },
    { upsert: true },
  );
  await ctx.reply("Welcome! You've been registered. 🎉");
});

---

📚 Tech Stack

Technology	Purpose
grammY	Telegram Bot framework
Mongoose	MongoDB ODM
tsx	TypeScript execution & watch mode
@ngrok/ngrok	Programmatic tunneling
Docker	Containerization

---

📄 License

This project is licensed under the MIT License.

---

Made with ❤️ — Happy bot building!