Scalable structure
Config loading and validation
Internationalization, language changing
Graceful shutdown
Logger (powered by pino)
Ultrafast and multi-runtime server (powered by hono)
Ready-to-use deployment setups:
- Docker
- Vercel
Examples:
- grammY plugins:
  - Conversations
- Databases:
  - Prisma ORM
- Runtimes:
  - Bun

Usage

Follow these steps to set up and run your bot using this template:

Create a New Repository

Start by creating a new repository using this template. You can do this by clicking here.
Environment Variables Setup

Create an environment variables file by copying the provided example file:
```
# development
cp .env.example .env.bot.dev

# production
cp .env.example .env.bot.prod
```
Open the newly created .env.bot.dev and .env.bot.prod files and set the BOT_TOKEN environment variable.
Launching the Bot

You can run your bot in both development and production modes.

Development Mode:

Install the required dependencies:
```
npm install
```
Start the bot in watch mode (auto-reload when code changes):
```
docker compose up
```
Production Mode:

Set DEBUG environment variable to false in your .env file.

Start the bot in production mode:
```
docker compose -f compose.yml -f compose.prod.yml up
```

List of Available Commands

npm run lint — Lint source code.
npm run format — Format source code.
npm run typecheck — Run type checking.
npm run dev — Start the bot in development mode.
npm run start — Start the bot.
npm run start:force — Starts the bot without type checking.

Directory Structure

project-root/
  ├── locales # Localization files
  └── src
      ├── bot # Code related to bot
      │   ├── callback-data # Callback data builders
      │   ├── features      # Bot features
      │   ├── filters       # Update filters
      │   ├── handlers      # Update handlers
      │   ├── helpers       # Helper functions
      │   ├── keyboards     # Keyboard builders
      │   ├── middlewares   # Bot middlewares
      │   ├── i18n.ts       # Internationalization setup
      │   ├── context.ts    # Context object definition
      │   └── index.ts      # Bot entry point
      ├── server # Code related to web server
      │   ├── middlewares   # Server middlewares
      │   ├── environment   # Server environment setup
      │   └── index.ts      # Server entry point
      ├── config.ts # Application config
      ├── logger.ts # Logging setup
      └── main.ts   # Application entry point

Deploy

Docker (docker.com)

Branch: deploy/docker-compose (open diff)

Use in your project:

Add the template repository as a remote

git remote add template git@github.com:bot-base/telegram-bot-template.git
git remote update

Merge deployment setup

git merge template/deploy/docker-compose -X theirs --squash --no-commit --allow-unrelated-histories

Follow the usage instructions in the deploy/docker-compose branch.

Vercel (vercel.com)

Branch: deploy/vercel (open diff)

Use in your project:

Add the template repository as a remote

git remote add template git@github.com:bot-base/telegram-bot-template.git
git remote update

Merge deployment setup

git merge template/deploy/vercel -X theirs --squash --no-commit --allow-unrelated-histories

Follow the usage instructions in the deploy/vercel branch.

Examples

grammY conversations (grammy.dev/plugins/conversations)

Branch: example/plugin-conversations (open diff)

Use in your project:

Add the template repository as a remote

git remote add template git@github.com:bot-base/telegram-bot-template.git
git remote update

Merge example

git merge template/example/plugin-conversations -X theirs --squash --no-commit --allow-unrelated-histories

Install dependencies

npm i @grammyjs/conversations

Follow the usage instructions in the example/plugin-conversations branch.

Prisma ORM (prisma.io)

Branch: example/orm-prisma (open diff)

Use in your project:

Add the template repository as a remote

git remote add template git@github.com:bot-base/telegram-bot-template.git
git remote update

Merge example

git merge template/example/orm-prisma -X theirs --squash --no-commit --allow-unrelated-histories

Install dependencies

npm i -D prisma
npm i @prisma/client

Follow the usage instructions in the example/orm-prisma branch.

Bun (bun.sh)

Branch: example/runtime-bun (open diff)

Use in your project:

Add the template repository as a remote

git remote add template git@github.com:bot-base/telegram-bot-template.git
git remote update

Merge example

git merge template/example/runtime-bun -X theirs --squash --no-commit --allow-unrelated-histories

Install dependencies

# remove Node-related dependencies
npm r @types/node tsx tsc-watch

# install dependencies
bun i

# remove npm lockfile
rm package-lock.json

# install bun typings
bun add -d @types/bun

Follow the usage instructions in the example/runtime-bun branch.

Environment Variables

Variable	Type	Description
BOT_TOKEN	String	Telegram Bot API token obtained from @BotFather.
BOT_MODE	String	Specifies method to receive incoming updates (`polling` or `webhook`).
LOG_LEVEL	String	Optional. Specifies the application log level. Use `info` for general logging. Check the Pino documentation for more log level options. Defaults to `info`.
DEBUG	Boolean	Optional. Enables debug mode. You may use `config.isDebug` flag to enable debugging functions.
BOT_WEBHOOK	String	Optional in `polling` mode. Webhook endpoint URL, used to configure webhook.
BOT_WEBHOOK_SECRET	String	Optional in `polling` mode. A secret token that is used to ensure that a request is sent from Telegram, used to configure webhook.
SERVER_HOST	String	Optional in `polling` mode. Specifies the server hostname. Defaults to `0.0.0.0`.
SERVER_PORT	Number	Optional in `polling` mode. Specifies the server port. Defaults to `80`.
BOT_ALLOWED_UPDATES	Array of String	Optional. A JSON-serialized list of the update types you want your bot to receive. See Update for a complete list of available update types. Defaults to an empty array (all update types except `chat_member`, `message_reaction` and `message_reaction_count`).
BOT_ADMINS	Array of Number	Optional. Administrator user IDs. Use this to specify user IDs that have special privileges, such as executing `/setcommands`. Defaults to an empty array.