Bot starter template based on grammY bot framework.
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 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):
npm run dev
Production Mode:
Install only production dependencies:
npm install --only=prod
Set DEBUG
environment variable to false
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
Branch: deploy/docker-compose (open diff)
Use in your project:
git remote add template git@github.com:bot-base/telegram-bot-template.git
git remote update
git merge template/deploy/docker-compose -X theirs --squash --no-commit --allow-unrelated-histories
deploy/docker-compose
branch.Branch: deploy/vercel (open diff)
Use in your project:
git remote add template git@github.com:bot-base/telegram-bot-template.git
git remote update
git merge template/deploy/vercel -X theirs --squash --no-commit --allow-unrelated-histories
deploy/vercel
branch.Branch: example/plugin-conversations (open diff)
Use in your project:
git remote add template git@github.com:bot-base/telegram-bot-template.git
git remote update
git merge template/example/plugin-conversations -X theirs --squash --no-commit --allow-unrelated-histories
npm i @grammyjs/conversations
example/plugin-conversations
branch.Branch: example/orm-prisma (open diff)
Use in your project:
git remote add template git@github.com:bot-base/telegram-bot-template.git
git remote update
git merge template/example/orm-prisma -X theirs --squash --no-commit --allow-unrelated-histories
npm i -D prisma
npm i @prisma/client
example/orm-prisma
branch.Branch: example/runtime-bun (open diff)
Use in your project:
git remote add template git@github.com:bot-base/telegram-bot-template.git
git remote update
git merge template/example/runtime-bun -X theirs --squash --no-commit --allow-unrelated-histories
# 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
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. |