document discord.js events

Author: notunderctrl

apps/website/docs/guide/02-commands/04-message-commands.mdx

@@ -18,7 +18,7 @@ message commands in favor of the more modern
 
 :::
 
-## Basic Setup
+## Basic setup
 
 Message commands, like all the other command types, live in your
 `src/app/commands` directory. To let CommandKit know that this is a
@@ -61,7 +61,7 @@ With the above command as an example, if a user on Discord runs
 `!ping john jack jane`, the value of `args` will equal
 `['john', 'jack', 'jane']`.
 
-## Custom Prefixes
+## Custom prefixes
 
 The simplest way to set a custom prefix is using the
 `setPrefixResolver` method on the `commandkit` instance:
@@ -88,7 +88,7 @@ return ['?', '!', '>'];
 
 :::
 
-### Guild-Specific Prefixes
+### Guild-specific prefixes
 
 For a more dynamic approach, you might want different prefixes for
 different guilds. Here's how to implement that:

apps/website/docs/guide/02-commands/06-category-directory.mdx

@@ -12,7 +12,7 @@ category directories to create a hierarchy of commands. This can then
 be used across your application in places such as middlewares,
 plugins, or even other commands through your `commandkit` instance.
 
-## Example Structure
+## Example structure
 
 ```title="" {4-15}
 .

apps/website/docs/guide/03-events/01-discordjs-events.mdx

@@ -1,3 +1,156 @@
 ---
-title: Discord.js events
+title: Discord.js Events
 ---
+
+Events allow your Discord bot to react to various actions happening on
+Discord, such as when users send messages, join guilds, or when your
+bot comes online.
+
+CommandKit provides a simple way to organize and handle Discord.js
+events using the `events` directory inside your `src/app` directory.
+This approach makes it easy to manage multiple events and keep your
+code organized.
+
+## Basic event directory structure
+
+Each Discord.js event gets its own directory within `src/app/events`,
+and the directory name must match the exact Discord.js event name.
+Inside each event directory, you can create multiple handler files
+that will all execute when that event is triggered.
+
+Here's how your project structure might look with the
+`"messageCreate"` and `"ready"` events:
+
+```title="" {4-9}
+.
+├── src/
+│   ├── app/
+│   │   └── events/
+│   │       ├── messageCreate/
+│   │       │   ├── give-xp.ts
+│   │       │   └── log-message.ts
+│   │       └── ready/
+│   │           └── log.ts
+│   └── app.ts
+├── .env
+├── .gitignore
+├── commandkit.config.ts
+├── package.json
+└── tsconfig.json
+```
+
+:::tip
+
+You can see what events are available in Discord.js by checking the
+[Discord.js documentation](https://discord.js.org/docs/packages/discord.js/main/ClientEventTypes:Interface).
+
+:::
+
+## Creating an event handler
+
+To create an event handler, create a folder inside the
+`src/app/events` directory which should match the event name from
+Discord.js. This example will use the `"ready"` event.
+
+```ts title="src/app/events/ready/log.ts"
+import type { Client } from 'commandkit';
+
+export default function (client: Client<true>) {
+  console.log(`🤖 ${client.user.displayName} is online!`);
+}
+```
+
+That's it! CommandKit will automatically detect this file and register
+it as one of the handler functions for the `"ready"` event.
+
+### Event parameters
+
+Just like the Discord.js `client.on()` method, the parameters you
+receive in your event file will be based on what event you're trying
+to handle. In the example above, the `"ready"` event should give you a
+`Client` instance.
+
+If you were to, for example, handle the `"messageCreate"` event, you
+would get a `Message` instance.
+
+### Events with multiple parameters
+
+Some Discord.js events have multiple parameters, such as the
+`"messageUpdate"` event.
+
+```ts title="src/app/events/messageUpdate/log-message-update.ts"
+import type { Message } from 'discord.js';
+
+export default function (oldMessage: Message, newMessage: Message) {
+  console.log(
+    `Message from ${oldMessage.author.username} updated: ${oldMessage.content} -> ${newMessage.content}`,
+  );
+}
+```
+
+### Additional parameters
+
+Outside of the parameters provided by Discord.js, CommandKit will pass
+additional parameters to the event handler, including a `Client` and
+`CommandKit` instance.
+
+```ts title="src/app/events/messageCreate/log.ts"
+import type { CommandKit } from 'commandkit';
+import type { Message } from 'discord.js';
+
+export default function (
+  message: Message,
+  client: Client<true>,
+  commandkit: CommandKit,
+) {
+  console.log(
+    `Message from ${message.author.username}: ${message.content}`,
+  );
+}
+```
+
+## Multiple handlers for the same event
+
+One of the powerful features of CommandKit's event system is the
+ability to have multiple handlers for the same event. Each handler
+file you create in an event directory will be executed when that event
+is called.
+
+For example, you might want to do several things when a message is
+created:
+
+```ts title="src/app/events/messageCreate/give-xp.ts"
+import type { MessageCreateEvent } from 'commandkit';
+
+export default function ({ message }: MessageCreateEvent) {
+  // Don't give XP to bots
+  if (message.author.bot) return;
+
+  // Give XP to the user
+  console.log(`Giving XP to ${message.author.username}`);
+}
+```
+
+```ts title="src/app/events/messageCreate/log-message.ts"
+import type { MessageCreateEvent } from 'commandkit';
+
+export default function ({ message }: MessageCreateEvent) {
+  console.log(
+    `Message from ${message.author.username}: ${message.content}`,
+  );
+}
+```
+
+Both handler functions will be called whenever a message is sent in
+Discord.
+
+:::tip
+
+Event handler files can be named anything you want - CommandKit
+identifies them by their location in the event directory, not by their
+filename. However, since each file is treated as a handler function,
+they're executed one-by-one in the order of their file name.
+
+Example: `01-give-xp.ts` will be executed before `02-log-message.ts`.
+
+:::