![](https://private-user-images.githubusercontent.com/26162440/259665736-c4371683-3e99-4b1c-ae8e-11ccbea78f4b.png?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3MjUwOTUxNzksIm5iZiI6MTcyNTA5NDg3OSwicGF0aCI6Ii8yNjE2MjQ0MC8yNTk2NjU3MzYtYzQzNzE2ODMtM2U5OS00YjFjLWFlOGUtMTFjY2JlYTc4ZjRiLnBuZz9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFWQ09EWUxTQTUzUFFLNFpBJTJGMjAyNDA4MzElMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjQwODMxVDA5MDExOVomWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPTRiYTlmYjE5ZmY0ZmY4OThmYWY2OTdlMTIwYWIyNzZlOGM4YWZiY2U0N2UzYzZjMjBhMzE1ODVhOTc3OGJlOTUmWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0JmFjdG9yX2lkPTAma2V5X2lkPTAmcmVwb19pZD0wIn0.6TrO3GkWxfX4ks0gLPiZPzDjtw0n36zY1t-tQbVV2Fc)
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:
# 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 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):
docker compose up
Production Mode:
Install only production dependencies (no development dependencies):
npm install --only=prod
Set
NODE_ENV
environment variable toproduction
in your.env.bot.prod
file.
UpdateBOT_WEBHOOK
with the actual URL where your bot will receive updates.
UpdateBOT_WEBHOOK_SECRET
with a random secret token.NODE_ENV=production BOT_WEBHOOK=<server_url>/webhook BOT_WEBHOOK_SECRET=<random_secret_value>
Start the bot in production mode:
docker compose -f compose.yml -f compose.prod.yml up
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 # Contains the code related to the bot
β βββ callback-data # Callback data builders
β βββ features # Implementations of bot features
β βββ filters # Update filters
β βββ handlers # Update handlers
β βββ helpers # Utility functions
β βββ keyboards # Keyboard builders
β βββ middlewares # Middleware functions
β βββ i18n.ts # Internationalization setup
β βββ context.ts # Context object definition
β βββ index.ts # Bot entry point
βββ server # Contains the code related to the web server
β βββ index.ts # Web 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.
grammY runner (grammy.dev/plugins/runner)
Branch: example/plugin-runner (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-runner -X theirs --squash --no-commit --allow-unrelated-histories
- Install dependencies
npm i @grammyjs/runner
- Follow the usage instructions in the
example/plugin-runner
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 |
---|---|---|
NODE_ENV | String | Specifies the application environment. (development or production ) |
BOT_TOKEN | String | Telegram Bot API token obtained from @BotFather. |
LOG_LEVEL | String |
Optional.
Specifies the application log level. For example, use info for general logging. View the Pino documentation for more log level options. Defaults to info .
|
BOT_MODE | String |
Optional.
Specifies method to receive incoming updates (polling or webhook ).Default depends on NODE_ENV (polling for development , webhook for production ).
|
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.
|
BOT_SERVER_HOST | String |
Optional. Specifies the server hostname. Defaults to 0.0.0.0 .
|
BOT_SERVER_PORT | Number |
Optional. 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. |