{"id":21201770,"url":"https://github.com/r6stats/valkord-discord","last_synced_at":"2025-07-10T06:31:57.488Z","repository":{"id":39997967,"uuid":"145901518","full_name":"R6Stats/valkord-discord","owner":"R6Stats","description":"Micro framework for building Discord bots with TypesScript","archived":false,"fork":false,"pushed_at":"2022-12-06T11:28:05.000Z","size":744,"stargazers_count":4,"open_issues_count":5,"forks_count":7,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-11-20T09:29:03.964Z","etag":null,"topics":["bot","discord","discord-bot","discordjs","framework","typescript","valkord"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/R6Stats.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":"2018-08-23T20:04:40.000Z","updated_at":"2021-05-13T03:25:20.000Z","dependencies_parsed_at":"2023-01-24T01:16:33.523Z","dependency_job_id":null,"html_url":"https://github.com/R6Stats/valkord-discord","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/R6Stats%2Fvalkord-discord","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/R6Stats%2Fvalkord-discord/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/R6Stats%2Fvalkord-discord/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/R6Stats%2Fvalkord-discord/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/R6Stats","download_url":"https://codeload.github.com/R6Stats/valkord-discord/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225622846,"owners_count":17498168,"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-bot","discordjs","framework","typescript","valkord"],"created_at":"2024-11-20T20:11:03.470Z","updated_at":"2024-11-20T20:11:05.362Z","avatar_url":"https://github.com/R6Stats.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Valkord (valk-discord)\n\n[![Discord](https://discordapp.com/api/guilds/293848587391991836/embed.png)](https://discord.gg/pUdraS3)\n[![npm (scoped)](https://img.shields.io/npm/v/@r6stats/valkord)](https://www.npmjs.com/package/@r6stats/valkord)\n[![David](https://img.shields.io/david/r6stats/valkord-discord)](https://david-dm.org/r6stats/valkord-discord)\n[![David](https://img.shields.io/david/peer/r6stats/valkord-discord)](https://david-dm.org/r6stats/valkord-discord)\n\nValkord is a micro framework for building Discord bots with [discordjs](https://discord.js.org/#/) and [TypeScript](https://www.typescriptlang.org/). Valkord uses a [Modular](https://en.wikipedia.org/wiki/Modular_design) component loading system, allowing you to develop or use 3rd party modules in your bot. Modules consist of commands, listeners and other classes that can be customized on a case-by-case basis.\n\n## Installing\n\nTo use Valkord to develop your own bot, you'll need to install it in your project alongside discord.js.\n\n```bash\nnpm install @r6stats/valkord discord.js --save\n```\n\n## Creating a Module\n\nIn order to create your own module, you'll want to extend the `ValkordModule` class and define the components that make up your module. You can also optionally add add a custom config for loading variables from the user's `.env` file.\ncd \n```ts\n// my.module.ts\n\nimport { ClientCommand, Constructor, ValkordModule } from '@r6stats/valkord'\nimport { MyModuleConfig } from './my.module-config'\nimport { PingCommand } from './commands'\n\nexport class MyModule extends ValkordModule\u003cMyModuleConfig\u003e {\n  public getName = (): string =\u003e 'MyStuff'\n\n  public getConfig = (): Constructor\u003cMyModuleConfig\u003e | null =\u003e MyModuleConfig // or return null\n\n  public getCommands = (): Constructor\u003cClientCommand\u003e[] =\u003e {\n    PingCommand,\n  }\n}\n```\n\n```ts\n// my.module-config.ts\n\nimport { ValkordConfig } from '@r6stats/valkord'\n\nexport interface MyModuleConfigOptions {\n  my_config_value: string\n}\n\nexport class MyModuleConfig extends ValkordConfig\u003cMyModuleConfigOptions\u003e {\n  public load = (): MyModuleConfigOptions =\u003e ({\n    my_config_value: env('MY_CONFIG_VALUE')\n  })\n}\n```\n\n```ts\n// index.ts\n\nexport * from './my.module-config'\nexport * from './my.module'\n```\n\nThe referenced command class makes use of the `ValkordCommand` class built into Valkord, which is extensible and allows for custom command handling as well as built in support for aliases, help messages and more.\n\n```ts\nimport { ValkordCommand, CommandContext, Injectable } from '@r6stats/valkord'\nimport { Message } from 'discord.js'\n\n@Injectable()\nexport class PingCommand extends ValkordCommand {\n  public readonly command = 'ping'\n  public readonly name = 'Ping'\n\n  public async handle (ctx: CommandContext): Promise\u003cMessage | Message[] | void\u003e {\n    return ctx.reply('Pong!')\n  }\n}\n\n```\n\nThanks to Valkord's incredibly simple [Dependency Injection](https://en.wikipedia.org/wiki/Dependency_injection) implementation, you can also create your own service (among others) classes that can auomatically be resolved from Valkord's built in container.\n\nTake for example, the `TimeService` class:\n\n```ts\nimport R6StatsAPI, { GenericStatsResponse, OperatorStatsResponse } from '@r6stats/node'\nimport { ConfigService, OnModuleBoot, Injectable } from '@r6stats/valkord'\n\n@Injectable()\nexport class TimeService {\n  public async getTime (): Promise\u003cDate\u003e {\n    return new Date()\n  }\n}\n```\n\nYou can now reference the `TimeService` from any class where the `@Injectable()` decorator is present, more importantly in the commands.\n\n```ts\nimport { ValkordCommand, CommandContext, Injectable } from '@r6stats/valkord'\nimport { Message } from 'discord.js'\n\n@Injectable()\nexport class TimeCommand extends ValkordCommand {\n  public readonly command = 'time'\n  public readonly name = 'Time'\n\n  private readonly time: TimeService\n\n  public constructor (time: TimeService) {\n    this.time = time\n  }\n\n  public async handle (ctx: CommandContext): Promise\u003cMessage | Message[] | void\u003e {\n    return ctx.reply(this.time.getTime())\n  }\n}\n\n```\n\n## Creating a Deployable Bot\n\nRegardless or whether or not you want to build your own modules, you'll have no problem running the bot in production.\n\nYou'll simply need to create a TypeScript or JavaScript file named `index.js` (or whatever you prefer) and instantiate your bot:\n\n```ts\nimport { ValkordClient, ValkordFactory } from '@r6stats/valkord'\n\n// optionally import your custom module, or any 3rd party modules\nimport MyModule from 'my-valkord-module'\n\nexport class MyClient extends ValkordClient {\n\n}\n\nconst run = async () =\u003e {\n  // instatiate the client from the Container\n  const client = await ValkordFactory.create\u003cMyClient\u003e(MyClient)\n\n  // load any modules of your choosing\n  const loader = client.getModuleLoader()\n  loader.load(MyModule)\n\n  // connect!\n  await client.connect()\n}\n\nrun()\n\n```\n\n### Sharded Bot\n\nLarger Discord bots may require sharding, typically suggested for any bots in more than 2000 guilds. Read more about sharding [here](https://discordjs.guide/sharding/). In order to enable sharding in Valkord, a second file is necessary to create shards of the client. \n\nThe new `index` file (TypeScript or JavaScript) will create an instance of the `ValkordManager` which will handle spawning the bot's shards. No changes to the client class are necessary.\n\n```ts\n// index.ts\n\nimport { ValkordFactory } from '@r6stats/valkord'\nimport * as path from 'path'\n\nexport const run = async (): Promise\u003cvoid\u003e =\u003e {\n  // the path should refer to the file containing your ValkordClient instance\n  await ValkordFactory.createManaged(path.join(__dirname, './client.ts'))\n}\n\nrun()\n```\n\nThe total number of shards and the range of shards to create can be configured in the `.env` file. \n\n```js\nTOTAL_SHARDS=3 // total number of shards, if running more than one instance of the manager\nSHARD_RANGE=0-2 // zero-based range of shards to run on this instance, starting at 0, last shard # should be one less than the total\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fr6stats%2Fvalkord-discord","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fr6stats%2Fvalkord-discord","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fr6stats%2Fvalkord-discord/lists"}