Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/bot-base/telegram-bot-template

Telegram bot template based on grammY
https://github.com/bot-base/telegram-bot-template

bot bun docker docker-compose grammy grammyjs hono honojs prisma starter-template telegram telegram-api telegram-bot telegram-bot-api telegram-bot-template template typescript vercel

Last synced: 5 days ago
JSON representation

Telegram bot template based on grammY

Host: GitHub
URL: https://github.com/bot-base/telegram-bot-template
Owner: bot-base
Created: 2021-12-20T20:45:24.000Z (almost 3 years ago)
Default Branch: main
Last Pushed: 2024-10-28T04:47:42.000Z (about 2 months ago)
Last Synced: 2024-10-30T03:55:51.677Z (about 1 month ago)
Topics: bot, bun, docker, docker-compose, grammy, grammyjs, hono, honojs, prisma, starter-template, telegram, telegram-api, telegram-bot, telegram-bot-api, telegram-bot-template, template, typescript, vercel
Language: TypeScript
Homepage:
Size: 2.42 MB
Stars: 310
Watchers: 4
Forks: 48
Open Issues: 14
Metadata Files:
- Readme: README.md

Awesome Lists containing this project

awesome - bot-base/telegram-bot-template - Telegram bot template based on grammY (TypeScript)
awesome-grammY - bot-base/telegram-bot-template - A starter bot template with a scalable structure and ready-to-use Docker setup. (Templates)

README

🤖 Telegram Bot Template

Bot starter template based on [grammY](https://grammy.dev/) bot framework.

## Features

- Scalable structure
- Config loading and validation
- Internationalization, language changing
- Graceful shutdown
- Logger (powered by [pino](https://github.com/pinojs/pino))
- Ultrafast and multi-runtime server (powered by [hono](https://github.com/honojs/hono))
- Ready-to-use deployment setups:
- [Docker](#docker-dockercom)
- [Vercel](#vercel-vercelcom)
- Examples:
- grammY plugins:
- [Conversations](#grammy-conversations-grammydevpluginsconversations)
- Databases:
- [Prisma ORM](#prisma-orm-prismaio)
- Runtimes:
- [Bun](#bun-bunsh)

## Usage

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

1. **Create a New Repository**

Start by creating a new repository using this template. You can do this by clicking [here](https://github.com/bot-base/telegram-bot-template/generate).

2. **Environment Variables Setup**

Create an environment variables file by copying the provided example file:
```bash
cp .env.example .env
```
Open the newly created `.env` file and set the `BOT_TOKEN` environment variable.

3. **Launching the Bot**

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

**Development Mode:**

Install the required dependencies:
```bash
npm install
```
Start the bot in watch mode (auto-reload when code changes):
```bash
npm run dev
```

**Production Mode:**

Install only production dependencies:
```bash
npm install --only=prod
```

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

Start the bot in production mode:
```bash
npm run start:force # skip type checking and start
# or
npm start # with type checking (requires development dependencies)
```

### 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](https://docker.com))

Branch:
[deploy/docker-compose](https://github.com/bot-base/telegram-bot-template/tree/deploy/docker-compose)
([open diff](https://github.com/bot-base/telegram-bot-template/compare/deploy/docker-compose))

Use in your project:

1. Add the template repository as a remote

```sh
git remote add template [email protected]:bot-base/telegram-bot-template.git
git remote update
```

2. Merge deployment setup

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

3. Follow [the usage instructions](https://github.com/bot-base/telegram-bot-template/tree/deploy/docker-compose#usage) in the `deploy/docker-compose` branch.

### Vercel ([vercel.com](https://vercel.com))

Branch:
[deploy/vercel](https://github.com/bot-base/telegram-bot-template/tree/deploy/vercel)
([open diff](https://github.com/bot-base/telegram-bot-template/compare/deploy/vercel))

Use in your project:

1. Add the template repository as a remote

```sh
git remote add template [email protected]:bot-base/telegram-bot-template.git
git remote update
```

2. Merge deployment setup

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

3. Follow [the usage instructions](https://github.com/bot-base/telegram-bot-template/tree/deploy/vercel#usage) in the `deploy/vercel` branch.

## Examples

### grammY conversations ([grammy.dev/plugins/conversations](https://grammy.dev/plugins/conversations))

Branch:
[example/plugin-conversations](https://github.com/bot-base/telegram-bot-template/tree/example/plugin-conversations)
([open diff](https://github.com/bot-base/telegram-bot-template/compare/example/plugin-conversations))

Use in your project:

1. Add the template repository as a remote

```sh
git remote add template [email protected]:bot-base/telegram-bot-template.git
git remote update
```

2. Merge example

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

3. Install dependencies

```sh
npm i @grammyjs/conversations
```

4. Follow [the usage instructions](https://github.com/bot-base/telegram-bot-template/tree/example/plugin-conversations#usage) in the `example/plugin-conversations` branch.

### Prisma ORM ([prisma.io](https://prisma.io))

Branch:
[example/orm-prisma](https://github.com/bot-base/telegram-bot-template/tree/example/orm-prisma)
([open diff](https://github.com/bot-base/telegram-bot-template/compare/example/orm-prisma))

Use in your project:

1. Add the template repository as a remote

```sh
git remote add template [email protected]:bot-base/telegram-bot-template.git
git remote update
```

2. Merge example

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

3. Install dependencies

```sh
npm i -D prisma
npm i @prisma/client
```

4. Follow [the usage instructions](https://github.com/bot-base/telegram-bot-template/tree/example/orm-prisma#usage) in the `example/orm-prisma` branch.

### Bun ([bun.sh](https://bun.sh))

Branch:
[example/runtime-bun](https://github.com/bot-base/telegram-bot-template/tree/example/runtime-bun)
([open diff](https://github.com/bot-base/telegram-bot-template/compare/example/runtime-bun))

Use in your project:

1. Add the template repository as a remote

```sh
git remote add template [email protected]:bot-base/telegram-bot-template.git
git remote update
```

2. Merge example

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

3. Install dependencies

```sh
# 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
```

4. Follow [the usage instructions](https://github.com/bot-base/telegram-bot-template/tree/example/runtime-bun#usage) 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.