{"id":21261484,"url":"https://github.com/tomerron/cordless","last_synced_at":"2025-10-19T11:22:00.407Z","repository":{"id":38411795,"uuid":"338786504","full_name":"TomerRon/cordless","owner":"TomerRon","description":"🤖 Declarative Discord bot framework. Build your first bot in 5 minutes with 3 lines of code!","archived":false,"fork":false,"pushed_at":"2024-02-21T17:18:10.000Z","size":618,"stargazers_count":57,"open_issues_count":2,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-11-20T15:44:24.398Z","etag":null,"topics":["bot","discord","discord-api","discord-bot","discord-js","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TomerRon.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-02-14T11:09:36.000Z","updated_at":"2023-05-04T01:58:12.000Z","dependencies_parsed_at":"2022-07-17T05:46:15.767Z","dependency_job_id":null,"html_url":"https://github.com/TomerRon/cordless","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TomerRon%2Fcordless","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TomerRon%2Fcordless/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TomerRon%2Fcordless/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TomerRon%2Fcordless/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TomerRon","download_url":"https://codeload.github.com/TomerRon/cordless/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225675083,"owners_count":17506272,"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","discord","discord-api","discord-bot","discord-js","typescript"],"created_at":"2024-11-21T04:43:32.352Z","updated_at":"2025-10-19T11:22:00.317Z","avatar_url":"https://github.com/TomerRon.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![cordless](assets/splash.png)](#)\n\n\u003ch3 align=\"center\"\u003eSimple framework for creating Discord bots with minimal boilerplate\u003c/h3\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/cordless\"\u003e\n    \u003cimg alt=\"npm latest version\" src=\"https://img.shields.io/npm/v/cordless/latest.svg\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://app.travis-ci.com/github/TomerRon/cordless\"\u003e\n    \u003cimg alt=\"build status\" src=\"https://api.travis-ci.com/TomerRon/cordless.svg?branch=master\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/semantic-release/semantic-release\"\u003e\n    \u003cimg alt=\"semantic-release\" src=\"https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n**cordless** is a simple wrapper for [discord.js](https://github.com/discordjs/discord.js) that allows you to create extensive and extensible Discord bots.\n\n```\nyarn add cordless\nnpm i cordless\n```\n\n## Quick Start\n\n⏲️ Estimated time: **5 minutes**\n\n1. Follow [docs/setup.md](docs/setup.md) to create a new bot in the Discord developer portal.\n2. Write your first command and initialize your bot:\n\n```ts\n// TypeScript\nimport { BotCommand, init } from 'cordless'\n\nconst ping: BotCommand = {\n  name: 'ping',\n  handler: ({ interaction }) =\u003e interaction.reply('Pong!'),\n}\n\ninit({ commands: [ping], token: 'your.bot.token' })\n```\n\n```js\n// JavaScript\nconst cordless = require('cordless')\n\nconst ping = {\n  name: 'ping',\n  handler: ({ interaction }) =\u003e interaction.reply('Pong!'),\n}\n\ncordless.init({ commands: [ping], token: 'your.bot.token' })\n```\n\nYou can also check out the [code samples](sample) for ready-to-go solutions. See: [sample/01-basic-typescript](sample/01-basic-typescript) or [sample/02-basic-javascript](sample/02-basic-javascript)\n\n## Advanced Usage\n\n#### Create advanced interactions\n\nCordless allows you to interface with the full [Discord Application Commands API](https://discord.com/developers/docs/interactions/application-commands) in a declarative fashion:\n\n- Add interactive buttons and link buttons to your interactions. See: [docs/command-components.md](docs/command-components.md)\n- Create CLI-like commands with arguments and pre-defined choices. See: [docs/command-options.md](docs/command-options.md)\n- Nest commands within each other by creating subcommands. See: [docs/command-subcommands.md](docs/command-subcommands.md)\n- Select menus: **_Coming soon!_**\n- Autocomplete: **_Coming soon!_**\n- Modals: **_Coming soon!_**\n\nFor a quick overview of the commands API, see: [docs/commands.md](docs/commands.md)\n\n#### Subscribe to Gateway Events\n\nCommands are the easiest way to let users interact with your bot, but sometimes you need to react to other events as they happen (for example: user joined the server, a message was deleted, etc). You can use the built-in event handlers to easily subscribe to any [Discord Gateway Event](https://discord.com/developers/docs/topics/gateway#commands-and-events-gateway-events).\n\nFor example, let's say our bot needs to greet new text channels whenever they are created, expect for channels that start with `admin-`. We can subscribe an event handler to the `channelCreate` event:\n\n```ts\n// TypeScript\nimport { BotEventHandler } from 'cordless'\nimport { ChannelType } from 'discord.js'\n\nconst channelGreeter: BotEventHandler\u003c'channelCreate'\u003e = {\n  event: 'channelCreate',\n  condition: (channel) =\u003e !channel.name.startsWith('admin-'),\n  callback: (channel) =\u003e {\n    if (channel.type === ChannelType.GuildText) {\n      return channel.send(`Hello world! This is ${channel.name}`)\n    }\n  },\n}\n```\n\nSee: [docs/events.md](docs/events.md)\n\n#### Using discord.js features\n\nThe `init` method returns a logged-in [discord.js Client](https://discord.js.org/#/docs/main/stable/class/Client).\n\n```ts\nconst client = await init({\n  // ...\n})\n\nconsole.log(`Logged in as ${client.user.tag}!`)\n```\n\nSee [discord.js documentation](https://discord.js.org/#/docs) for more information about using the client.\n\n#### Context and State Management\n\nYou can share business logic and state between your different event handlers using context. By default, the context contains the `discord.js` client and the current list of event handlers. You can also extend the context with your own custom context to share additional business logic and even implement state management.\n\nSee: [docs/context.md](docs/context.md)\n\n#### Override the default Gateway Intents\n\nBy default, cordless initializes the discord.js client with the [Gateway Intents](https://discord.com/developers/docs/topics/gateway#gateway-intents) `[GUILDS, GUILD_MESSAGES]`. This should be sufficient for bots that only use command interactions, or bots that only subscribe to events like \"messageCreate\". You can provide your own list of intents if you need additional functionality.\n\nSee: [docs/intents.md](docs/intents.md)\n\n## Local development\n\nClone and install the dependencies:\n\n```\ngit clone https://github.com/TomerRon/cordless.git\ncd cordless\nyarn\n```\n\nWe recommend installing [yalc](https://github.com/wclr/yalc). Publish your changes locally with:\n\n```\nyalc publish\n```\n\nYou can then test your changes in a local app using:\n\n```\nyalc add cordless\n```\n\n#### Unit tests\n\nRun the unit tests:\n\n```\nyarn test\n```\n\n#### End-to-end tests\n\nYou must first create two bots and add them to a Discord server. One of the bots will run the cordless client, and the other bot will pretend to be a normal user. The cordless client bot must have the \"Message Content Intent\" enabled - you can enable it in the Discord Developer Dashboard, in your application's \"Bot\" page.\n\nYou'll need the tokens for both of the bots, and the channel ID of a channel where the bots can send messages.\n\nCopy the `.env` file and edit it:\n\n```\ncp .example.env .env\n```\n\n```\n# .env\nE2E_CLIENT_TOKEN=some.discord.token\nE2E_USER_TOKEN=some.discord.token\nE2E_CHANNEL_ID=12345678\n```\n\nRun the e2e tests:\n\n```\nyarn e2e\n```\n\n## Special thanks\n\nHuge shoutout to [fivenp](https://fivenp.com/) ([@fivenp](https://github.com/fivenp)) for the amazing visual assets. Go check out his work!\n\n## License\n\nThis project is licensed under the ISC License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftomerron%2Fcordless","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftomerron%2Fcordless","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftomerron%2Fcordless/lists"}