![](https://private-user-images.githubusercontent.com/26162440/259665736-c4371683-3e99-4b1c-ae8e-11ccbea78f4b.png?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3MjUwODc5MTksIm5iZiI6MTcyNTA4NzYxOSwicGF0aCI6Ii8yNjE2MjQ0MC8yNTk2NjU3MzYtYzQzNzE2ODMtM2U5OS00YjFjLWFlOGUtMTFjY2JlYTc4ZjRiLnBuZz9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFWQ09EWUxTQTUzUFFLNFpBJTJGMjAyNDA4MzElMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjQwODMxVDA3MDAxOVomWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPTIyNTNjNzcxYmRhYzY5N2EzOTJlODAzYjVjYzFlYzBjMTY0MTUzOWJjYTM3MDcwMzUwYjRhOWZhZjg4Y2I2M2ImWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0JmFjdG9yX2lkPTAma2V5X2lkPTAmcmVwb19pZD0wIn0.v4hcTpA6iKF5GPoZyiLt_XHFy6CEDMb2dPYq9ikQdHA)
Bot starter template based on grammY bot framework.
- 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:
- Examples:
- grammY plugins:
- Databases:
- Runtimes:
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:
cp .env.example .env
Open the newly created
.env
file and set theBOT_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):
npm run dev
Production Mode:
Install only production dependencies:
npm install --only=prod
Set
DEBUG
environment variable tofalse
in your.env
file.Start the bot in production mode:
npm run start:force # skip type checking and start # or npm start # with type checking (requires development dependencies)
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.
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
Docker (docker.com)
Branch: deploy/docker-compose (open diff)
Use in your project:
- Add the template repository as a remote
git remote add template [email protected]: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 [email protected]: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.
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 [email protected]: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 [email protected]: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 [email protected]: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.
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. |