discordjs
diff --git a/‎apps/guide/CONTRIBUTING.md‎
Lines changed: 135 additions & 0 deletions b/‎apps/guide/CONTRIBUTING.md‎
Lines changed: 135 additions & 0 deletions
diff --git a/‎apps/guide/README.md‎
Lines changed: 9 additions & 11 deletions b/‎apps/guide/README.md‎
Lines changed: 9 additions & 11 deletions
diff --git a/‎apps/guide/content/docs/index.mdx‎
Lines changed: 0 additions & 7 deletions b/‎apps/guide/content/docs/index.mdx‎
Lines changed: 0 additions & 7 deletions
diff --git a/‎apps/guide/content/docs/legacy/additional-features/cooldowns.mdx‎
Lines changed: 103 additions & 0 deletions b/‎apps/guide/content/docs/legacy/additional-features/cooldowns.mdx‎
Lines changed: 103 additions & 0 deletions
diff --git a/‎apps/guide/content/docs/legacy/additional-features/reloading-commands.mdx‎
Lines changed: 74 additions & 0 deletions b/‎apps/guide/content/docs/legacy/additional-features/reloading-commands.mdx‎
Lines changed: 74 additions & 0 deletions
@@ -0,0 +1,135 @@
+# Contributing
+
+## Local development
+
+Clone the code base into a local folder, `cd` into it, and install the dependencies:
+
+```bash
+git clone https://github.com/discordjs/discord.js.git
+cd discord.js/apps/guide
+pnpm --filter guide install
+```
+
+You can and should use `pnpm dev` to check your changes out locally before pushing them for review.
+
+## Adding pages
+
+To add a new page to the guide, create a `filename.mdx` file in the folder of your choice located under `/content`. Fumadocs will pick it up and route appropriately. To list the section in the sidebar, make sure it is listed in the `meta.json` file of the directory you placed it in under the `pages` key. The order in the `pages` array determines the order pages have in the sidebar.
+
+## Framework and components
+
+The guide uses the fumadocs documention framework for Next.js. You can find examples as well as documentation for the components you can use at <https://fumadocs.dev/docs/ui>.
+
+## General guidelines
+
+Please try your best to follow the guidelines below. They help to make the guide appear as a coherent piece of work rather than a collection of disconnected pieces with different writing styles.
+
+### Spelling, grammar, and wording
+
+Improper grammar, strange wording, and incorrect spelling are all things that may lead to confusion when a user reads a guide page. It's important to attempt to keep the content clear and consistent. Re-read what you've written and place yourself in the shoes of someone else for a moment to see if you can fully understand everything without any confusion.
+
+Don't worry if you aren't super confident with your grammar/spelling/wording skills; all pull requests get thoroughly reviewed, and comments are left in areas that need to be fixed or could be done better/differently.
+
+#### "You"/"your" instead of "we"/"our"
+
+When explaining parts of the guide, we recommend to use "you" instead of "we" when referring to the read or things they can do:
+
+```diff
+- To check our Node version, we can run `node -v`.
++ To check your Node version, you can run `node -v`.
+
+- To delete a message, we can do: `message.delete();`
++ To delete a message, you can do: `message.delete();`
+
+- Our final code should look like this: ...
++ Your final code should look like this: ...
+
+- Before we can actually do this, we need to update our configuration file.
++ Before you can actually do this, you need to update your configuration file.
+```
+
+#### "We" instead of "I"
+
+When referring to yourself, use "we" (as in "the writers of this guide") instead of "I". For example:
+
+```diff
+- If you don't already have this package installed, I would highly recommend doing so.
++ If you don't already have this package installed, we would highly recommend doing so.
+# Valid alternative:
++ If you don't already have this package installed, it's highly recommended that you do so.
+
+- In this section, I'll be covering how to do that really cool thing everyone's asking about.
++ In this section, we'll be covering how to do that really cool thing everyone's asking about.
+```
+
+#### Inclusive language
+
+Try to avoid using genered and otherwise non-inclusive language. The following are just examples to give you an idea of what we expect. Don't understand this as a complete list of "banned terms":
+
+- Use they/them/their instead of gendered pronouns (he/him/his, she/her/hers).
+- Avoid using "master" and "slave", you can use "primary" and "replica" or "secondary" instead.
+- Avoid gendered terms like "guys", "folks" and "people" work just as well.
+- Avoid ableist terms "sanity check", use "confidence check" or "coherence check" instead.
+- Avoid talking about "dummy" values, call them "placeholder" or "sample value" instead.
+
+### Paragraph structure
+
+Try to keep guide articles formatted nicely and easy to read. If paragraphs get too long, you can usually split them up where they introduce a new concept or facet. Adding a bit of spacing can make the guide easier to digest and follow! Try to avoid run-on sentences with many embedded clauses.
+
+## Semantic components
+
+You can find the full documentation for the guide framework at <https://fumadocs.dev/docs/ui/>. If you are unsure what to use when, consider looking through the existing guide pages and how they approach things.
+
+### Callouts
+
+You can use [Callouts](https://fumadocs.dev/docs/ui/markdown#callouts) to describe additional context that doesn't fully fit into the flow of the paragraph or requires special attention. Prefer to MDX syntax `<Callout />` over Remark `:::` admonitions.
+
+### Code
+
+Fumadocs integrates [Shiki transformers](https://fumadocs.dev/docs/ui/markdown#shiki-transformers) for visual highlighting through the use of [Rhype Code](https://fumadocs.dev/docs/headless/mdx/rehype-code).
+
+When describing changes or additions to code, prefer using the appropriate language (`js` in most cases for this guide) with diff transformers over `diff` highlights:
+
+```js
+console.log('Hello'); // [!code --]
+console.log('Hello World'); // [!code ++]
+```
+
+You can put the transfomer syntax above the respective line and declare ranges instead of repeating formatting intsructions. You can also combine different transformers on the same line. Note that word highlights highlight the word across the code block by default, but do respect ranges.
+
+```js
+console.log('Hello'); // [!code --:2]
+console.log('World');
+// [!code ++]
+console.log('Hello World');
+```
+
+```js
+// ...
+// [!code focus:2] [!code word:log:1]
+console.log('Hello World!'); // this instance of "log" is highlighted
+console.log('Foobar'); // this one is not
+// ...
+```
+
+When introducing new functions in a paragraph, consider highlighting them in the following code snippet to draw additional attention to their use. For example, if you just described the `log` function:
+
+```js
+console.log('Hello World'); // [!code word:log]
+```
+
+Make sure to denote the file names or paths if you describe progress in a specific code sample. When descrbing multiple files, use [tab groups](https://fumadocs.dev/docs/ui/markdown#tab-groups).
+
+````md
+```json title="package.json" tab="Configuration"
+{ ... }
+```
+
+```js tab="Usage"
+// code showing how to use what is being configued
+```
+````
+
+### Directory Structure
+
+You can use the [Files](https://fumadocs.dev/docs/ui/components/files) component to visualize the expected directory structure, if it is relevant to the approach you describe.
@@ -19,17 +19,17 @@
 - [Website][website] ([source][website-source])
 - [Documentation][documentation]
 - [Guide][guide] ([source][guide-source])
-  Also see the v13 to v14 [Update Guide][guide-update], which includes updated and removed items from the library.
 - [discord.js Discord server][discord]
-- [Discord API Discord server][discord-api]
 - [GitHub][source]
-- [Related libraries][related-libs]
 
 ## Contributing
 
-Before creating an issue, please ensure that it hasn't already been reported/suggested, and double-check the
-[documentation][documentation].  
-See [the contribution guide][contributing] if you'd like to submit a PR.
+Before creating an issue, please ensure that it hasn't already been reported/suggested, and double-check the existing guide.  
+See [the contribution guide][./contributing] if you'd like to submit a PR.
+
+## Local Development
+
+To install and run just the guide portion of the repository for development, you can install dependencies with `pnpm --filter guide install` and serve a development version of the guide on localhost with `pnpm dev`.
 
 ## Help
 
@@ -38,11 +38,9 @@ If you don't understand something in the documentation, you are experiencing pro
 [website]: https://discord.js.org
 [website-source]: https://github.com/discordjs/discord.js/tree/main/apps/website
 [documentation]: https://discord.js.org/docs
-[guide]: https://discordjs.guide/
-[guide-source]: https://github.com/discordjs/guide
+[guide]: https://discord.js/guide
+[guide-source]: https://github.com/discordjs/discord.js/tree/main/apps/guide
 [guide-update]: https://discordjs.guide/additional-info/changes-in-v14.html
 [discord]: https://discord.gg/djs
-[discord-api]: https://discord.gg/discord-api
-[source]: https://github.com/discordjs/discord.js/tree/main/apps/website
-[related-libs]: https://discord.com/developers/docs/topics/community-resources#libraries
+[source]: https://github.com/discordjs/discord.js/tree/main/apps/guide
 [contributing]: https://github.com/discordjs/discord.js/blob/main/.github/CONTRIBUTING.md
@@ -0,0 +1,103 @@
+---
+title: Cooldowns
+---
+
+Spam is something you generally want to avoid, especially if one of your commands require calls to other APIs or takes a bit of time to build/send.
+
+<Callout>
+	This section assumes you followed the [Command Handling](../app-creation/handling-commands) part of the guide.
+</Callout>
+
+First, add a cooldown property to your command. This will determine how long the user would have to wait (in seconds) before using the command again.
+
+```js title="commands/utility/ping.js"
+const { SlashCommandBuilder } = require('discord.js');
+
+module.exports = {
+	cooldown: 5, // [!code ++]
+	data: new SlashCommandBuilder().setName('ping').setDescription('Replies with Pong!'),
+	async execute(interaction) {
+		// ...
+	},
+};
+```
+
+In your main file, initialize a [Collection](../additional-info/collections) to store cooldowns of commands:
+
+```js
+client.cooldowns = new Collection();
+```
+
+The key will be the command names, and the values will be Collections associating the user's id (key) to the last time (value) this user used this command. Overall the logical path to get a user's last usage of a command will be `cooldowns > command > user > timestamp`.
+
+In your `InteractionCreate` event handler, add the following code:
+
+```js title="index.js / interactionCreate.js (if you followed the event handler section)"
+// ...
+// [!code ++:14]
+const { cooldowns } = interaction.client;
+
+if (!cooldowns.has(command.data.name)) {
+	cooldowns.set(command.data.name, new Collection());
+}
+
+const now = Date.now();
+const timestamps = cooldowns.get(command.data.name);
+const defaultCooldownDuration = 3;
+const cooldownAmount = (command.cooldown ?? defaultCooldownDuration) * 1_000;
+
+if (timestamps.has(interaction.user.id)) {
+	// ...
+}
+```
+
+You check if the `cooldowns` Collection already has an entry for the command being used. If this is not the case, you can add a new entry, where the value is initialized as an empty Collection. Next, create the following variables:
+
+1. `now`: The current timestamp.
+2. `timestamps`: A reference to the Collection of user ids and timestamp key/value pairs for the triggered command.
+3. `cooldownAmount`: The specified cooldown for the command, converted to milliseconds for straightforward calculation. If none is specified, this defaults to three seconds.
+
+If the user has already used this command in this session, get the timestamp, calculate the expiration time, and inform the user of the amount of time they need to wait before using this command again. Note the use of the `return` statement here, causing the code below this snippet to execute only if the user has not used this command in this session or the wait has already expired.
+
+Continuing with your current setup, this is the complete `if` statement:
+
+```js title="index.js / interactionCreate.js (if you followed the event handler section)"
+const defaultCooldownDuration = 3;
+const cooldownAmount = (command.cooldown ?? defaultCooldownDuration) * 1_000;
+
+// [!code focus:13]
+if (timestamps.has(interaction.user.id)) {
+	// ... // [!code --]
+	// [!code ++:9]
+	const expirationTime = timestamps.get(interaction.user.id) + cooldownAmount;
+
+	if (now < expirationTime) {
+		const expiredTimestamp = Math.round(expirationTime / 1_000);
+		return interaction.reply({
+			content: `Please wait, you are on a cooldown for \`${command.data.name}\`. You can use it again <t:${expiredTimestamp}:R>.`,
+			flags: MessageFlags.Ephemeral,
+		});
+	}
+}
+```
+
+Since the `timestamps` Collection has the user's id as the key, you can use the `get()` method on it to get the value and sum it up with the `cooldownAmount` variable to get the correct expiration timestamp and further check to see if it's expired or not.
+
+The previous user check serves as a precaution in case the user leaves the guild. You can now use the `setTimeout` method, which will allow you to execute a function after a specified amount of time and remove the timeout.
+
+```js
+// [!code focus]
+if (timestamps.has(interaction.user.id)) {
+	const expiredTimestamp = Math.round(expirationTime / 1_000);
+	return interaction.reply({
+		content: `Please wait, you are on a cooldown for \`${command.data.name}\`. You can use it again <t:${expiredTimestamp}:R>.`,
+		flags: MessageFlags.Ephemeral,
+	});
+} // [!code focus]
+
+// [!code ++:2] [!code focus:2]
+timestamps.set(interaction.user.id, now);
+setTimeout(() => timestamps.delete(interaction.user.id), cooldownAmount);
+```
+
+This line causes the entry for the user under the specified command to be deleted after the command's cooldown time has expired for them.
@@ -0,0 +1,74 @@
+---
+title: Reloading Commands
+---
+
+When writing your commands, you may find it tedious to restart your bot every time for testing the smallest changes. With a command handler, you can eliminate this issue and reload your commands while your bot is running.
+
+<Callout>
+	ESM does not support require and clearing import cache. You can use [hot-esm](https://www.npmjs.com/package/hot-esm)
+	to import files without cache. Windows support is experimental per [this
+	issue](https://github.com/vinsonchuong/hot-esm/issues/33).
+</Callout>
+
+<Callout>
+	This section assumes you followed the [Command Handling](../app-creation/handling-commands) part of the guide.
+</Callout>
+
+```js title="commands/utility/reload.js"
+const { SlashCommandBuilder } = require('discord.js');
+
+module.exports = {
+	data: new SlashCommandBuilder()
+		.setName('reload')
+		.setDescription('Reloads a command.')
+		.addStringOption((option) => option.setName('command').setDescription('The command to reload.').setRequired(true)),
+	async execute(interaction) {
+		// ...
+	},
+};
+```
+
+First off, you need to check if the command you want to reload exists. You can do this check similarly to getting a command.
+
+```js
+module.exports = {
+	// ...
+	// [!code focus:10]
+	async execute(interaction) {
+		// ... // [!code --]
+		// [!code ++:6]
+		const commandName = interaction.options.getString('command', true).toLowerCase();
+		const command = interaction.client.commands.get(commandName);
+
+		if (!command) {
+			return interaction.reply(`There is no command with name \`${commandName}\`!`);
+		}
+	},
+};
+```
+
+<Callout type="warn">
+	The reload command ideally should not be used by every user. You should deploy it as a guild command in a private
+	guild.
+</Callout>
+
+To build the correct file path, you will need the file name. You can use `command.data.name` for doing that.
+
+In theory, all there is to do is delete the previous command from `client.commands` and require the file again. In practice, you cannot do this easily as `require()` caches the file. If you were to require it again, you would load the previously cached file without any changes. You first need to delete the file from `require.cache`, and only then should you require and set the command file to `client.commands`:
+
+```js
+delete require.cache[require.resolve(`./${command.data.name}.js`)];
+
+try {
+	const newCommand = require(`./${command.data.name}.js`);
+	interaction.client.commands.set(newCommand.data.name, newCommand);
+	await interaction.reply(`Command \`${newCommand.data.name}\` was reloaded!`);
+} catch (error) {
+	console.error(error);
+	await interaction.reply(
+		`There was an error while reloading a command \`${command.data.name}\`:\n\`${error.message}\``,
+	);
+}
+```
+
+The snippet above uses a `try...catch` block to load the command file and add it to `client.commands`. In case of an error, it will log the full error to the console and notify the user about it with the error's message component `error.message`. Note that you never actually delete the command from the commands Collection and instead overwrite it. This behavior prevents you from deleting a command and ending up with no command at all after a failed `require()` call, as each use of the reload command checks that Collection again.