{"id":31534490,"url":"https://github.com/yuurahz/yoru","last_synced_at":"2025-10-04T05:40:18.281Z","repository":{"id":313667725,"uuid":"1052220101","full_name":"yuurahz/yoru","owner":"yuurahz","description":"Yoru is a multi-functional and versatile telegram bot, built using the telegraph library.","archived":false,"fork":false,"pushed_at":"2025-09-20T20:21:55.000Z","size":68,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-09-20T22:14:09.271Z","etag":null,"topics":["base-bot-telegram","bot-tele","bot-telegram","telegraf","telegrambots","yoru"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yuurahz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":null,"patreon":null,"ko_fi":"yoshidajs","custom":["https://saweria.co/yoshida"]}},"created_at":"2025-09-07T16:45:42.000Z","updated_at":"2025-09-20T20:21:58.000Z","dependencies_parsed_at":"2025-09-07T18:38:44.063Z","dependency_job_id":"311f7e90-608b-421d-89cf-012a8c661319","html_url":"https://github.com/yuurahz/yoru","commit_stats":null,"previous_names":["yuurahz/yoru"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/yuurahz/yoru","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuurahz%2Fyoru","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuurahz%2Fyoru/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuurahz%2Fyoru/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuurahz%2Fyoru/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yuurahz","download_url":"https://codeload.github.com/yuurahz/yoru/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuurahz%2Fyoru/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278269238,"owners_count":25959109,"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","status":"online","status_checked_at":"2025-10-04T02:00:05.491Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["base-bot-telegram","bot-tele","bot-telegram","telegraf","telegrambots","yoru"],"created_at":"2025-10-04T05:40:16.498Z","updated_at":"2025-10-04T05:40:18.275Z","avatar_url":"https://github.com/yuurahz.png","language":"JavaScript","funding_links":["https://ko-fi.com/yoshidajs","https://saweria.co/yoshida"],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n    \u003ch1\u003eYORU\u003c/h1\u003e\n    \u003ca href=\"https://github.com/yuurahz/yoru\"\u003e\n        \u003cimg src=\"https://files.catbox.moe/obrip8.jpg\" alt=\"Yoru\"/\u003e\n    \u003c/a\u003e\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n\u003ch3\u003eA Lightweight, Powerful, and Scalable Telegram Bot\u003c/h3\u003e\n\n[![Community](https://img.shields.io/badge/Telegram-Community-Blue?style=for-the-badge\u0026logo=telegram)](https://t.me/yoshida_team)\n[![License](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](LICENSE)\n[![Issues](https://img.shields.io/github/issues/yuurahz/yoru?style=for-the-badge\u0026logo=github)](https://github.com/yuurahz/yoru/issues)\n[![Stars](https://img.shields.io/github/stars/yuurahz/yoru?style=for-the-badge\u0026logo=github)](https://github.com/yuurahz/yoru/stargazers)\n[![Forks](https://img.shields.io/github/forks/yuurahz/yoru?style=for-the-badge\u0026logo=github)](https://github.com/yuurahz/yoru/network/members)\n\n\u003c/div\u003e\n\n---\n\n\u003e [!NOTE]\n\u003e **Yoru** is a modern Telegram bot framework designed for developers who need a robust foundation for building feature-rich bots. Whether you're creating a simple utility bot or a complex, multi-service platform, Yoru provides the architecture and tools to scale efficiently and optimized for lightweight performance.\n\n---\n\n## Table of Contents\n\n- [Why Choose Yoru?](#why-choose-yoru)\n- [Requirements](#requirements)\n- [Getting Started](#getting-started)\n- [Configuration](#configuration)\n- [Running the Bot](#️running-the-bot)\n- [Installation via Docker](#installation-via-docker)\n- [Plugin Development](#plugin-development)\n- [PM2 Configuration](#pm2-configuration)\n- [Contributing](#contributing)\n- [Troubleshooting](#troubleshooting)\n- [License](#license)\n\n---\n\n## Why Choose Yoru?\n\n- **Free \u0026 Open Source:** Completely free for personal and commercial use under the MIT License.\n- **Modular Architecture:** Easily extend functionality with a simple plug-and-play plugin system.\n- **Fast \u0026 Stable:** Powered by [Telegraf](https://telegraf.js.org/), one of the most popular and reliable Telegram bot libraries.\n- **Hybrid Storage:** Choose between simple JSON file-based storage or a powerful MongoDB database for scalability.\n- **Active Roadmap:**\n    - [x] **Robust Error Handling:** A more resilient system to gracefully handle errors and maintain a stable connection.\n    - [ ] **Easy Deployment:** Streamlined processes for hosting on various platforms.\n\n---\n\n## Requirements\n\n### Software\n\n- **NodeJS:** Version `16.x` or higher. (Recommended `20.x`)\n- **Git:** For cloning the repository.\n\n### Hardware (Minimum Recommendation)\n\n- **vCPU:** 1 Core\n- **RAM:** 500 MB\n\n### Recommended Services\n\n- **Hosting:** [Hostdata (NAT VPS)](https://hostdata.id/nat-vps-usa/), [Optiklink](https://optiklink.com/), [VPS](https://www.orangevps.com/), [RDPWin](https://www.rdpwin.com/rdpbot.php)\n- **Database:** [MongoDB Atlas](https://www.mongodb.com/cloud/atlas) for a free cloud database.\n\n---\n\n## Getting Started\n\n### 1. Clone \u0026 Install\n\n```bash\n# Clone the repository\ngit clone https://github.com/yuurahz/yoru.git\n\n# Navigate into the project directory\ncd yoru\n\n# Install all required dependencies\nnpm install\n```\n\n### 2. Configure Environment\n\nCopy the example `.env` file to create your own configuration file.\n\n```bash\ncp .env.example .env\n```\n\nNext, open the `.env` file and customize the values as needed.\n\n---\n\n## Configuration\n\nEdit the `.env` file you just created:\n\n| Variable         | Description                                                      | Example Value  |\n| :--------------- | :--------------------------------------------------------------- | :------------- |\n| `TOKEN_BOT`      | Your unique bot token from [@BotFather](https://t.me/BotFather). | -              |\n| `OWNER_ID`       | ID of the account that will be used as the owner.                | -              |\n| `TZ`             | The local timezone of your server.                               | `Asia/Jakarta` |\n| `LIMIT`          | The daily command usage limit per user.                          | `50`           |\n| `DATABASE_STATE` | Choose `json` for local files or `mongodb` for a database.       | `json`         |\n| `DATABASE_NAME`  | The name of your database (for MongoDB).                         | `yoru_db`      |\n| `MONGO_URL`      | Your MongoDB connection string (if using `mongodb`).             | -              |\n\n---\n\n## Running the Bot\n\nYou can run the bot in several different modes:\n\n- **Production Mode:**\n    ```bash\n    npm start\n    ```\n- **Development Mode (with auto-reload on file changes):**\n    ```bash\n    npm run dev\n    ```\n- **Using PM2 (to keep the bot online):**\n    ```bash\n    npm run pm2\n    ```\n\n---\n\n## Installation via Docker\n\nFor an easy and isolated setup, you can use Docker.\n\n```bash\n# Update packages and install dependencies\nsudo apt update -y \u0026\u0026 sudo apt install curl git -y\n\n# Install Docker\ncurl -fsSL https://get.docker.com | bash\n\n# Clone the repository\ngit clone https://github.com/yuurahz/yoru\n\n# Navigate into the directory\ncd yoru\n\n# (IMPORTANT) Create and edit your .env file before building the image\n# cp .env.example .env\n# nano .env\n\n# Build the Docker image\ndocker build -t yoru-bot .\n\n# Run the container in detached mode and set it to always restart\ndocker run -d --name yoru --restart always yoru-bot\n\n# View the bot's logs in real-time\ndocker logs -f yoru\n```\n\nTo stop the container:\n\n```bash\ndocker stop yoru\n```\n\n---\n\n## Plugin Development\n\nYoru uses a flexible and easy-to-extend plugin system.\n\n#### Basic Plugin Example\n\nThis is a simple `ping` plugin to check the bot's latency.\n\n```javascript\n// file: plugins/tools/ping.js\nmodule.exports = {\n\t// Plugin metadata\n\thelp: [\"ping\"],\n\tcategory: \"tools\",\n\tcommand: \"ping\",\n\n\t// The main logic of the plugin\n\trun: async (m, { client }) =\u003e {\n\t\tconst start = Date.now();\n\t\tconst msg = await m.reply(\"Pinging...\");\n\t\tconst latency = Date.now() - start;\n\n\t\tawait client.telegram.editMessageText(\n\t\t\tm.chat,\n\t\t\tmsg.message_id,\n\t\t\tnull,\n\t\t\t`🏓 Pong!\\n*Latency:* ${latency} ms`,\n\t\t\t{ parse_mode: \"Markdown\" }\n\t\t);\n\t},\n\n\t// Plugin permissions and properties\n\tgroup: true, // Works in groups\n\tadmin: false, // Does not require admin\n\tlimit: 1, // Consumes 1 usage limit (can be a Number or Boolean)\n\tpremium: false, // Not premium-only\n\tbotAdmin: false, // Bot does not need to be an admin\n\towner: false, // Not owner-only\n};\n```\n\n#### Event Handler Example\n\nPlugins can also respond to events instead of commands, such as replying to specific messages.\n\n```javascript\n// file: plugins/events/auto-reply.js\nmodule.exports = {\n\t// The 'before' function runs on every incoming message\n\tbefore: async (m, { client }) =\u003e {\n\t\tif (m.body?.toLowerCase().includes(\"hello yoru\")) {\n\t\t\tawait m.reply(\"👋 Hello there!\");\n\t\t}\n\n\t\t// Always return a boolean value\n\t\treturn true;\n\t},\n};\n```\n\n---\n\n## PM2 Configuration\n\nIf you run the bot using `npm run pm2`, you can customize its configuration in the `ecosystem.config.js` file.\n\n```javascript\nmodule.exports = {\n\tapps: [\n\t\t{\n\t\t\tname: \"yoru\",\n\t\t\tscript: \"index.js\",\n\t\t\texec_mode: \"fork\",\n\t\t\tinstances: 1,\n\t\t\tmax_memory_restart: \"300M\",\n\t\t\twatch: false, // Set to true to automatically restart on file changes\n\t\t},\n\t],\n};\n```\n\n---\n\n## Contributing\n\nYour contributions are highly appreciated! If you'd like to help improve Yoru, please follow these steps:\n\n1.  **Fork** the repository.\n2.  Create a new feature branch (`git checkout -b feature/NewFeature`).\n3.  Make your changes and **commit** them (`git commit -m \"Add NewFeature\"`).\n4.  **Push** to your branch (`git push origin feature/NewFeature`).\n5.  Open a **Pull Request**.\n\n---\n\n## Troubleshooting\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eBot is not responding\u003c/strong\u003e\u003c/summary\u003e\n\n1.  **Check Bot Token:** Ensure the token in your `.env` file is correct and has no extra spaces.\n2.  **Verify Internet Connectivity:** Try to `ping google.com` from your server.\n3.  **Check Logs:** Run the bot in `dev` mode (`npm run dev`) or check Docker/PM2 logs for any error messages.\n4.  **Rate Limits:** Make sure the bot is not sending too many messages in a short period, which could get it rate-limited by Telegram.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eDatabase connection issues\u003c/strong\u003e\u003c/summary\u003e\n\n1.  **Verify MongoDB URL:** Double-check that the URL and credentials (username/password) are correct.\n2.  **Database Server is Running:** Ensure your database server is active.\n3.  **Whitelist IP:** If using MongoDB Atlas, make sure your server's IP address has been whitelisted.\n4.  **Firewall:** Check for any firewall rules that might be blocking the outbound connection to the database port.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003ePlugin is not loading\u003c/strong\u003e\u003c/summary\u003e\n\n1.  **Check Syntax:** Ensure there are no syntax errors in your plugin file.\n2.  **Plugin Structure:** Verify that the `module.exports` structure is correct.\n3.  **Look for Errors:** Check the console on startup for any error messages related to loading plugins.\n4.  **File Location:** Make sure the plugin file is inside the correct `plugins` directory.\n\u003c/details\u003e\n\n---\n\n## License\n\nThis project is licensed under the **MIT License**. Free for personal \u0026 commercial use.\n\n\u003cdiv align=\"center\"\u003e\n\n---\n\n**Need Help?** Open an [Issue](https://github.com/yuurahz/yoru/issues) or join the discussions!  \n**⭐ Star this repo if you like it! ⭐**\n\n_Built with ❤️ for the Telegram community_\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyuurahz%2Fyoru","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyuurahz%2Fyoru","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyuurahz%2Fyoru/lists"}