{"id":13454353,"url":"https://github.com/bot-base/telegram-bot-template","last_synced_at":"2025-05-16T09:03:40.693Z","repository":{"id":37484989,"uuid":"440302068","full_name":"bot-base/telegram-bot-template","owner":"bot-base","description":"Telegram bot template based on grammY","archived":false,"fork":false,"pushed_at":"2025-05-12T04:41:44.000Z","size":2931,"stargazers_count":378,"open_issues_count":13,"forks_count":56,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-05-12T05:31:46.436Z","etag":null,"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"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bot-base.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-12-20T20:45:24.000Z","updated_at":"2025-05-12T04:40:29.000Z","dependencies_parsed_at":"2024-04-15T06:10:28.217Z","dependency_job_id":"f77b48b2-5b89-4424-a58c-9e5ff5e5d0ed","html_url":"https://github.com/bot-base/telegram-bot-template","commit_stats":{"total_commits":623,"total_committers":6,"mean_commits":"103.83333333333333","dds":0.4879614767255217,"last_synced_commit":"b79bc49151a131043b66b020d0a896017bd36484"},"previous_names":[],"tags_count":0,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bot-base%2Ftelegram-bot-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bot-base%2Ftelegram-bot-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bot-base%2Ftelegram-bot-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bot-base%2Ftelegram-bot-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bot-base","download_url":"https://codeload.github.com/bot-base/telegram-bot-template/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254501554,"owners_count":22081528,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["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"],"created_at":"2024-07-31T08:00:53.324Z","updated_at":"2025-05-16T09:03:40.660Z","avatar_url":"https://github.com/bot-base.png","language":"TypeScript","readme":"\u003ch1 align=\"center\"\u003e🤖 Telegram Bot Template\u003c/h1\u003e\n\n\u003cimg align=\"right\" width=\"35%\" src=\"https://github.com/bot-base/telegram-bot-template/assets/26162440/c4371683-3e99-4b1c-ae8e-11ccbea78f4b\"\u003e\n\nBot starter template based on [grammY](https://grammy.dev/) bot framework.\n\n## Features\n\n- Scalable structure\n- Config loading and validation\n- Internationalization, language changing\n- Graceful shutdown\n- Logger (powered by [pino](https://github.com/pinojs/pino))\n- Ultrafast and multi-runtime server (powered by [hono](https://github.com/honojs/hono))\n- Ready-to-use deployment setups:\n    - [Docker](#docker-dockercom)\n    - [Vercel](#vercel-vercelcom)\n- Examples:\n    - grammY plugins:\n        - [Conversations](#grammy-conversations-grammydevpluginsconversations)\n    - Databases:\n      - [Prisma ORM](#prisma-orm-prismaio)\n    - Runtimes:\n      - [Bun](#bun-bunsh)\n\n## Usage\n\nFollow these steps to set up and run your bot using this template:\n\n1. **Create a New Repository**\n\n    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).\n\n2. **Environment Variables Setup**\n\n    Create an environment variables file by copying the provided example file:\n     ```bash\n     cp .env.example .env\n     ```\n    Open the newly created `.env` file and set the `BOT_TOKEN` environment variable.\n\n3. **Launching the Bot**\n\n    You can run your bot in both development and production modes.\n\n    **Development Mode:**\n\n    Install the required dependencies:\n    ```bash\n    npm install\n    ```\n    Start the bot in watch mode (auto-reload when code changes):\n    ```bash\n    npm run dev\n    ```\n\n   **Production Mode:**\n\n    Install only production dependencies:\n    ```bash\n    npm install --only=prod\n    ```\n\n    Set `DEBUG` environment variable to `false` in your `.env` file.\n\n    Start the bot in production mode:\n    ```bash\n    npm run start:force # skip type checking and start\n    # or\n    npm start # with type checking (requires development dependencies)\n    ```\n\n### List of Available Commands\n\n- `npm run lint` — Lint source code.\n- `npm run format` — Format source code.\n- `npm run typecheck` — Run type checking.\n- `npm run dev` — Start the bot in development mode.\n- `npm run start` — Start the bot.\n- `npm run start:force` — Starts the bot without type checking.\n\n### Directory Structure\n\n```\nproject-root/\n  ├── locales # Localization files\n  └── src\n      ├── bot # Code related to bot\n      │   ├── callback-data # Callback data builders\n      │   ├── features      # Bot features\n      │   ├── filters       # Update filters\n      │   ├── handlers      # Update handlers\n      │   ├── helpers       # Helper functions\n      │   ├── keyboards     # Keyboard builders\n      │   ├── middlewares   # Bot middlewares\n      │   ├── i18n.ts       # Internationalization setup\n      │   ├── context.ts    # Context object definition\n      │   └── index.ts      # Bot entry point\n      ├── server # Code related to web server\n      │   ├── middlewares   # Server middlewares\n      │   ├── environment   # Server environment setup\n      │   └── index.ts      # Server entry point\n      ├── config.ts # Application config\n      ├── logger.ts # Logging setup\n      └── main.ts   # Application entry point\n```\n\n## Deploy\n\n### Docker ([docker.com](https://docker.com))\n\nBranch:\n[deploy/docker-compose](https://github.com/bot-base/telegram-bot-template/tree/deploy/docker-compose)\n([open diff](https://github.com/bot-base/telegram-bot-template/compare/deploy/docker-compose))\n\nUse in your project:\n\n1. Add the template repository as a remote\n\n```sh\ngit remote add template git@github.com:bot-base/telegram-bot-template.git\ngit remote update\n```\n\n2. Merge deployment setup\n\n```sh\ngit merge template/deploy/docker-compose -X theirs --squash --no-commit --allow-unrelated-histories\n```\n\n3. Follow [the usage instructions](https://github.com/bot-base/telegram-bot-template/tree/deploy/docker-compose#usage) in the `deploy/docker-compose` branch.\n\n### Vercel ([vercel.com](https://vercel.com))\n\nBranch:\n[deploy/vercel](https://github.com/bot-base/telegram-bot-template/tree/deploy/vercel)\n([open diff](https://github.com/bot-base/telegram-bot-template/compare/deploy/vercel))\n\nUse in your project:\n\n1. Add the template repository as a remote\n\n```sh\ngit remote add template git@github.com:bot-base/telegram-bot-template.git\ngit remote update\n```\n\n2. Merge deployment setup\n\n```sh\ngit merge template/deploy/vercel -X theirs --squash --no-commit --allow-unrelated-histories\n```\n\n3. Follow [the usage instructions](https://github.com/bot-base/telegram-bot-template/tree/deploy/vercel#usage) in the `deploy/vercel` branch.\n\n## Examples\n\n### grammY conversations ([grammy.dev/plugins/conversations](https://grammy.dev/plugins/conversations))\n\nBranch:\n[example/plugin-conversations](https://github.com/bot-base/telegram-bot-template/tree/example/plugin-conversations)\n([open diff](https://github.com/bot-base/telegram-bot-template/compare/example/plugin-conversations))\n\nUse in your project:\n\n1. Add the template repository as a remote\n\n```sh\ngit remote add template git@github.com:bot-base/telegram-bot-template.git\ngit remote update\n```\n\n2. Merge example\n\n```sh\ngit merge template/example/plugin-conversations -X theirs --squash --no-commit --allow-unrelated-histories\n```\n\n3. Install dependencies\n\n```sh\nnpm i @grammyjs/conversations\n```\n\n4. Follow [the usage instructions](https://github.com/bot-base/telegram-bot-template/tree/example/plugin-conversations#usage) in the `example/plugin-conversations` branch.\n\n### Prisma ORM ([prisma.io](https://prisma.io))\n\nBranch:\n[example/orm-prisma](https://github.com/bot-base/telegram-bot-template/tree/example/orm-prisma)\n([open diff](https://github.com/bot-base/telegram-bot-template/compare/example/orm-prisma))\n\nUse in your project:\n\n1. Add the template repository as a remote\n\n```sh\ngit remote add template git@github.com:bot-base/telegram-bot-template.git\ngit remote update\n```\n\n2. Merge example\n\n```sh\ngit merge template/example/orm-prisma -X theirs --squash --no-commit --allow-unrelated-histories\n```\n\n3. Install dependencies\n\n```sh\nnpm i -D prisma\nnpm i @prisma/client\n```\n\n4. Follow [the usage instructions](https://github.com/bot-base/telegram-bot-template/tree/example/orm-prisma#usage) in the `example/orm-prisma` branch.\n\n### Bun ([bun.sh](https://bun.sh))\n\nBranch:\n[example/runtime-bun](https://github.com/bot-base/telegram-bot-template/tree/example/runtime-bun)\n([open diff](https://github.com/bot-base/telegram-bot-template/compare/example/runtime-bun))\n\nUse in your project:\n\n1. Add the template repository as a remote\n\n```sh\ngit remote add template git@github.com:bot-base/telegram-bot-template.git\ngit remote update\n```\n\n2. Merge example\n\n```sh\ngit merge template/example/runtime-bun -X theirs --squash --no-commit --allow-unrelated-histories\n```\n\n3. Install dependencies\n\n```sh\n# remove Node-related dependencies\nnpm r @types/node tsx tsc-watch\n\n# install dependencies\nbun i\n\n# remove npm lockfile\nrm package-lock.json\n\n# install bun typings\nbun add -d @types/bun\n```\n\n4. Follow [the usage instructions](https://github.com/bot-base/telegram-bot-template/tree/example/runtime-bun#usage) in the `example/runtime-bun` branch.\n\n## Environment Variables\n\n\u003ctable\u003e\n\u003cthead\u003e\n  \u003ctr\u003e\n    \u003cth\u003eVariable\u003c/th\u003e\n    \u003cth\u003eType\u003c/th\u003e\n    \u003cth\u003eDescription\u003c/th\u003e\n  \u003c/tr\u003e\n\u003c/thead\u003e\n\u003ctbody\u003e\n  \u003ctr\u003e\n    \u003ctd\u003eBOT_TOKEN\u003c/td\u003e\n    \u003ctd\u003e\n        String\n    \u003c/td\u003e\n    \u003ctd\u003e\n        Telegram Bot API token obtained from \u003ca href=\"https://t.me/BotFather\"\u003e@BotFather\u003c/a\u003e.\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003eBOT_MODE\u003c/td\u003e\n    \u003ctd\u003e\n        String\n    \u003c/td\u003e\n    \u003ctd\u003e\n        Specifies method to receive incoming updates (\u003ccode\u003epolling\u003c/code\u003e or \u003ccode\u003ewebhook\u003c/code\u003e).\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003eLOG_LEVEL\u003c/td\u003e\n    \u003ctd\u003e\n        String\n    \u003c/td\u003e\n    \u003ctd\u003e\n        \u003ci\u003eOptional.\u003c/i\u003e\n        Specifies the application log level. \u003cbr/\u003e\n        Use \u003ccode\u003einfo\u003c/code\u003e for general logging. Check the \u003ca href=\"https://github.com/pinojs/pino/blob/master/docs/api.md#level-string\"\u003ePino documentation\u003c/a\u003e for more log level options. \u003cbr/\u003e\n        Defaults to \u003ccode\u003einfo\u003c/code\u003e.\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003eDEBUG\u003c/td\u003e\n    \u003ctd\u003eBoolean\u003c/td\u003e\n    \u003ctd\u003e\n      \u003ci\u003eOptional.\u003c/i\u003e\n      Enables debug mode. You may use \u003ccode\u003econfig.isDebug\u003c/code\u003e flag to enable debugging functions.\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003eBOT_WEBHOOK\u003c/td\u003e\n    \u003ctd\u003e\n        String\n    \u003c/td\u003e\n    \u003ctd\u003e\n        \u003ci\u003eOptional in \u003ccode\u003epolling\u003c/code\u003e mode.\u003c/i\u003e\n        Webhook endpoint URL, used to configure webhook.\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003eBOT_WEBHOOK_SECRET\u003c/td\u003e\n    \u003ctd\u003e\n        String\n    \u003c/td\u003e\n    \u003ctd\u003e\n        \u003ci\u003eOptional in \u003ccode\u003epolling\u003c/code\u003e mode.\u003c/i\u003e\n        A secret token that is used to ensure that a request is sent from Telegram, used to configure webhook.\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003eSERVER_HOST\u003c/td\u003e\n    \u003ctd\u003e\n        String\n    \u003c/td\u003e\n    \u003ctd\u003e\n        \u003ci\u003eOptional in \u003ccode\u003epolling\u003c/code\u003e mode.\u003c/i\u003e Specifies the server hostname. \u003cbr/\u003e\n        Defaults to \u003ccode\u003e0.0.0.0\u003c/code\u003e.\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003eSERVER_PORT\u003c/td\u003e\n    \u003ctd\u003e\n        Number\n    \u003c/td\u003e\n    \u003ctd\u003e\n        \u003ci\u003eOptional in \u003ccode\u003epolling\u003c/code\u003e mode.\u003c/i\u003e Specifies the server port. \u003cbr/\u003e\n        Defaults to \u003ccode\u003e80\u003c/code\u003e.\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003eBOT_ALLOWED_UPDATES\u003c/td\u003e\n    \u003ctd\u003e\n        Array of String\n    \u003c/td\u003e\n    \u003ctd\u003e\n        \u003ci\u003eOptional.\u003c/i\u003e A JSON-serialized list of the update types you want your bot to receive. See \u003ca href=\"https://core.telegram.org/bots/api#update\"\u003eUpdate\u003c/a\u003e for a complete list of available update types. \u003cbr/\u003e\n        Defaults to an empty array (all update types except \u003ccode\u003echat_member\u003c/code\u003e, \u003ccode\u003emessage_reaction\u003c/code\u003e and \u003ccode\u003emessage_reaction_count\u003c/code\u003e).\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003eBOT_ADMINS\u003c/td\u003e\n    \u003ctd\u003e\n        Array of Number\n    \u003c/td\u003e\n    \u003ctd\u003e\n        \u003ci\u003eOptional.\u003c/i\u003e\n        Administrator user IDs.\n        Use this to specify user IDs that have special privileges, such as executing \u003ccode\u003e/setcommands\u003c/code\u003e. \u003cbr/\u003e\n        Defaults to an empty array.\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/tbody\u003e\n\u003c/table\u003e\n","funding_links":[],"categories":["TypeScript","Templates"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbot-base%2Ftelegram-bot-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbot-base%2Ftelegram-bot-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbot-base%2Ftelegram-bot-template/lists"}