feat(guide): port legacy guide #10938

almostSouji · 2025-06-17T22:29:37Z

Initial release:

Considerations:

Components: Discord messages (TBD, formatting issues with https://www.npmjs.com/package/@skyra/discord-components-react spacing)
Components: consider a doc link component of sorts
Prefer relative links when possible
Styling for subguides (legacy/voice) example: https://fumadocs.dev/docs/ui

Note

serves /guide/legacy and /guide/voice

vercel · 2025-06-17T22:29:41Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
discord-js-guide	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jun 22, 2025 1:28pm

1 Skipped Deployment

Name	Status	Preview	Comments	Updated (UTC)
discord-js	⬜️ Ignored (Inspect)	Visit Preview		Jun 22, 2025 1:28pm

* top link should be installation * add docs link to sidebar

apps/guide/content/docs/legacy/app-creation/handling-events.mdx

Qjuh · 2025-06-22T09:10:23Z

apps/guide/src/app/guide/layout.tsx

+									style={
+										{
+											color,
+											backgroundColor: `color-mix(in oklab, ${color} 10%, transparent)`,


Couldn't this be a CSS class instead? To have all styling in one place instead of mixed into the code here.

Qjuh · 2025-06-22T09:39:32Z

apps/guide/content/docs/legacy/index.mdx

+- How to get a bot [up and running](/guide/legacy/preparations/app-setup) from scratch;
+- How to properly [create](/guide/legacy/app-creation/project-setup), [organize](/guide/legacy/app-creation/handling-commands), and expand on your commands;
+- In-depth explanations and examples regarding popular topics (e.g. [components](/guide/legacy/popular-topics/display-components) ,[reactions](/guide/legacy/popular-topics/reactions), [embeds](/guide/legacy/popular-topics/embeds), [canvas](/guide/legacy/popular-topics/canvas));
+- Working with databases (e.g. [sequelize](/guide/legacy/sequelize/) and [keyv](/guide/legacy/keyv/));


Suggested change

- Working with databases (e.g. [sequelize](/guide/legacy/sequelize/) and [keyv](/guide/legacy/keyv/));

- Working with databases (e.g. [sequelize](./sequelize/) and [keyv](./keyv/keyv));

Qjuh · 2025-06-22T09:43:32Z

apps/guide/content/docs/legacy/popular-topics/faq.mdx

+
+<Callout>
+	If you want to learn more about reactions, check out [this dedicated guide on
+	reactions](/guide/legacy/popular-topics/reactions.md)!


Suggested change

reactions](/guide/legacy/popular-topics/reactions.md)!

reactions](./reactions)!

Qjuh · 2025-06-22T09:46:29Z

apps/guide/content/docs/legacy/meta.json

+{
+	"pages": [
+		"[Info][Introduction](/guide/legacy)",
+		"[MessageCircleQuestion][FAQ](/guide/legacy/popular-topics/faq)",


I'd move this down, as it feels weird when using the "Next page" navigation in the guide to go from introduction to FAQ. I always felt the same on the old guide, it should jump right into the actual "Getting Started" instead of information that a new user won't need/understand.

true, but also the POI people will be trying to find - and if just to reference - when visiting the guide

Qjuh · 2025-06-22T09:59:29Z

apps/guide/content/docs/legacy/app-creation/project-setup.mdx

+
+<Callout title="Danger" type="error">
+	If you're using Git, you should not commit this file and should [ignore it via
+	`.gitignore`](/creating-your-bot/#git-and-gitignore).


Suggested change

`.gitignore`](/creating-your-bot/#git-and-gitignore).

`.gitignore`](#git-and-gitignore).

Qjuh · 2025-06-22T10:51:35Z

apps/guide/content/docs/legacy/sharding/index.mdx

+<Callout>
+	You can find the methods available for the ShardingManager class `ShardingManager`. Though, you may not be making much
+	use of this section, unlike the next feature we will explore, which you may learn about by clicking [this
+	link](/sharding/additional-information.md).


Suggested change

link](/sharding/additional-information.md).

link](./additional-information).

Qjuh · 2025-06-22T10:54:17Z

apps/guide/content/docs/voice/voice-connections.mdx

+<Callout>
+    **Voice connections can be subscribed to one audio player at most.** If you try to subscribe to another audio player while already subscribed to one, the current audio player is unsubscribed and replaced with the new one.
+
+    It is also worth noting that the **GuildVoiceStates** [gateway intent](/popular-topics/intents.md#gateway-intents) is required. Without it, the connection will permanently stay in the `signalling` state, and you'll be unable to play audio.


Suggested change

It is also worth noting that the **GuildVoiceStates** [gateway intent](/popular-topics/intents.md#gateway-intents) is required. Without it, the connection will permanently stay in the `signalling` state, and you'll be unable to play audio.

It is also worth noting that the **GuildVoiceStates** [gateway intent](/guide/legacy/popular-topics/intents#gateway-intents) is required. Without it, the connection will permanently stay in the `signalling` state, and you'll be unable to play audio.

Qjuh · 2025-06-22T10:54:37Z

apps/guide/content/docs/voice/voice-connections.mdx

+
+## Life cycle
+
+Voice connections have their own life cycle, with five distinct states. You can follow the methods discussed in the [life cycles](/voice/life-cycles.md) section to subscribe to changes to voice connections.


Suggested change

Voice connections have their own life cycle, with five distinct states. You can follow the methods discussed in the [life cycles](/voice/life-cycles.md) section to subscribe to changes to voice connections.

Voice connections have their own life cycle, with five distinct states. You can follow the methods discussed in the [life cycles](./life-cycles) section to subscribe to changes to voice connections.

Qjuh · 2025-06-22T10:56:04Z

apps/guide/content/docs/voice/audio-player.mdx

+
+### Playing audio
+
+You can create [audio resources](./audio-resources.md) and then play them on an audio player.


Suggested change

You can create [audio resources](./audio-resources.md) and then play them on an audio player.

You can create [audio resources](./audio-resources) and then play them on an audio player.

Qjuh · 2025-06-22T10:56:25Z

apps/guide/content/docs/voice/audio-player.mdx

+
+## Life cycle
+
+Voice connections have their own life cycle, with five distinct states. You can follow the methods discussed in the [life cycles](/voice/life-cycles.md) section to subscribe to changes to voice connections.


Suggested change

Voice connections have their own life cycle, with five distinct states. You can follow the methods discussed in the [life cycles](/voice/life-cycles.md) section to subscribe to changes to voice connections.

Voice connections have their own life cycle, with five distinct states. You can follow the methods discussed in the [life cycles](./life-cycles) section to subscribe to changes to voice connections.

codecov · 2025-06-22T11:13:30Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 42.70%. Comparing base (2852a52) to head (4f23fb2).
Report is 2 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main   #10938   +/-   ##
=======================================
  Coverage   42.69%   42.70%           
=======================================
  Files         262      262           
  Lines       16086    16084    -2     
  Branches     1545     1543    -2     
=======================================
  Hits         6868     6868           
+ Misses       9206     9204    -2     
  Partials       12       12

Flag	Coverage Δ
core	`0.89% <ø> (ø)`

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

vladfrangu · 2025-06-22T11:18:20Z

apps/guide/CONTRIBUTING.md

+- Whitelist -> Allowlist
+- Blacklist -> Denylist


I am not a fan of this butchering to have 1 word that represents a list of allowed/disallowed values, imo a phrase is better but 🤷

vladfrangu · 2025-06-22T11:19:15Z

apps/guide/content/docs/legacy/additional-features/cooldowns.mdx

+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](/guide/legacy/app-creation/handling-commands) part of the


Shouldn't we use relative paths wherever possible?

vladfrangu · 2025-06-22T11:20:36Z

apps/guide/content/docs/legacy/additional-features/reloading-commands.mdx

+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)


I mean there's always import(`./file.mjs?d=${Date.now()}`) but that has the disadvantage of leaking small amounts of memory per reload

vladfrangu · 2025-06-22T11:49:49Z

apps/guide/content/docs/legacy/app-creation/handling-events.mdx

+		<File name="packge-lock.json" />
+		<File name="packge.json" />


Find packge -> replace package

vladfrangu · 2025-06-22T11:52:12Z

apps/guide/content/docs/legacy/app-creation/project-setup.mdx

+
+Environment variables are special values for your environment (e.g., terminal session, Docker container, or environment variable file). You can pass these values into your code's scope so that you can use them.
+
+One way to pass in environment variables is via the command line interface. When starting your app, instead of `node index.js`, use `TOKEN=your-token-goes-here node index.js`. You can repeat this pattern to expose other values as well.


Keep in mind this will only work on unix systems. Windows will throw if you try this, maybe we can add a callout for using cross-env?

vladfrangu · 2025-06-22T12:13:57Z

apps/guide/content/docs/legacy/preparations/installation.mdx

+<Cards>
+	<Card icon={<Grid2x2 />} title="Windows">
+		Download the latest version from [the Node.js website](https://nodejs.org/), open the downloaded file, and follow
+		the steps from the installer.
+	</Card>
+	<Card icon={<Apple />} title="macOS">
+		Download the latest version from [the Node.js website](https://nodejs.org/), open the package installer, and follow
+		the instructions - Use a package manager like [Homebrew](https://brew.sh/) with the command `brew install node`
+	</Card>
+	<Card icon={<Cpu />} title="Linux">
+		Consult [this page](https://nodejs.org/en/download/package-manager/) to determine how you should install Node.
+	</Card>
+</Cards>


I know this is for legacy docs but I feel like even here we should point people towards fnm/volta/nvm

vladfrangu · 2025-06-22T12:23:55Z

apps/guide/content/docs/voice/index.mdx

+```sh tab="npm"
+npm install @discordjs/voice libsodium-wrappers
+```
+
+```sh tab="yarn"
+yarn add @discordjs/voice libsodium-wrappers
+```
+
+```sh tab="pnpm"
+pnpm add @discordjs/voice libsodium-wrappers
+```
+
+```sh tab="bun"
+bun add @discordjs/voice libsodium-wrappers
+```


Nowadays, libsodium-wrappers isn't required

vladfrangu · 2025-06-22T12:24:27Z

apps/guide/content/docs/voice/index.mdx

+- An Opus encoding library
+  - [`@discordjs/opus`](https://github.com/discordjs/opus) (best performance)
+  - [`opusscript`](https://github.com/abalabahaha/opusscript/)
+- FFmpeg – allows you to play a range of media (e.g. MP3s).
+  - [`ffmpeg`](https://ffmpeg.org/) - install and add to your system environment
+  - [`ffmpeg-static`](https://www.npmjs.com/package/ffmpeg-static) - to install FFmpeg via npm
+- Encryption packages
+  - [`sodium`](https://www.npmjs.com/package/sodium) (best performance)
+  - [`sodium-native`](https://www.npmjs.com/package/sodium-native)
+  - [`libsodium-wrappers`](https://www.npmjs.com/package/libsodium-wrappers)
+  - [`tweetnacl`](https://www.npmjs.com/package/tweetnacl)


This needs an update to add the new libs supported

vladfrangu · 2025-06-22T12:26:09Z

apps/guide/content/docs/voice/index.mdx

+If you're struggling to install these dependencies, make sure you have build tools installed first. On Windows, this is as easy as running the following command!
+
+```sh tab="npm"
+npm install --global --production --add-python-to-path windows-build-tools
+```
+
+```sh tab="yarn"
+yarn global add --production --add-python-to-path windows-build-tools
+```
+
+```sh tab="pnpm"
+pnpm add --global --production --add-python-to-path windows-build-tools
+```
+
+```sh tab="bun"
+bun add --global --production --add-python-to-path windows-build-tools
+```


We should not recommend this anymore, instead just telling users to install vs with c++ (winget install "Visual Studio Community 2022" --override "--add Microsoft.VisualStudio.Workload.NativeDesktop " -s msstore) and python

But its also not required since some modules have prebuilts, and most systems have aed encryption already and will work out of the box

vladfrangu · 2025-06-22T12:30:05Z

apps/guide/src/app/guide/layout.tsx

+										{
+											color,
+											backgroundColor: `color-mix(in oklab, ${color} 10%, transparent)`,
+										} as object


This cast feels redundant, it is an object, whats the ts error without it?

Co-authored-by: Naiyar <137700126+imnaiyar@users.noreply.github.com>

github-project-automation bot added this to discord.js Jun 17, 2025

github-project-automation bot moved this to Todo in discord.js Jun 17, 2025

github-actions bot added the apps:guide label Jun 17, 2025

vercel bot had a problem deploying to Preview – discord-js-guide June 20, 2025 19:00 Failure

almostSouji added 2 commits June 20, 2025 21:11

feat: initial attempt at porting legacy guide

2760e9a

feat: completion of legacy guide backport

32a1058

almostSouji force-pushed the legacy-guide branch from 698d2f8 to 32a1058 Compare June 20, 2025 19:33

vercel bot had a problem deploying to Preview – discord-js-guide June 20, 2025 19:33 Failure

almostSouji added 2 commits June 20, 2025 21:45

chore: lockfile shenanigans

bd18237

fix: handle svgs

e2039cf

vercel bot had a problem deploying to Preview – discord-js-guide June 20, 2025 20:28 Failure

fix: replace svg with mermaid integration

b809b4e

vercel bot deployed to Preview – discord-js-guide June 20, 2025 21:27 View deployment

almostSouji changed the title ~~Port legacy guide~~ feat(guide): port legacy guide Jun 20, 2025

chore: format

bf08ce4

vercel bot deployed to Preview – discord-js-guide June 20, 2025 23:10 View deployment

almostSouji added 2 commits June 21, 2025 01:12

chore: remove unnecssary bullet

d3ca602

chore: cleanup code highlights

71dd5b2

vercel bot deployed to Preview – discord-js-guide June 20, 2025 23:37 View deployment

chore: explicit return

f39897c

vercel bot deployed to Preview – discord-js-guide June 21, 2025 06:33 View deployment

almostSouji added 5 commits June 21, 2025 22:39

chore: move display components after interactive components in sidebar

64725cc

chore: voice

8f95419

* top link should be installation * add docs link to sidebar

feat: subguide-based accent styles

e6a5a8d

chore: don't list faq twice

cbd1c6d

chore: mention display components in interactive components

b1b1694

vercel bot deployed to Preview – discord-js-guide June 21, 2025 21:15 View deployment

fix: remove unoccs/order rule from guide

5daaaa3

vercel bot deployed to Preview – discord-js-guide June 22, 2025 08:41 View deployment

chore: redirect to legacy guide instead of /guide root

d658632

vercel bot deployed to Preview – discord-js-guide June 22, 2025 08:47 View deployment

almostSouji marked this pull request as ready for review June 22, 2025 08:47

almostSouji requested review from a team and iCrawl as code owners June 22, 2025 08:47

almostSouji requested review from Jiralite, Qjuh, monbrey, vladfrangu, kyranet and SpaceEEC June 22, 2025 08:47

imnaiyar reviewed Jun 22, 2025

View reviewed changes

apps/guide/content/docs/legacy/app-creation/handling-events.mdx Outdated Show resolved Hide resolved

refactor: use <kbd>

c37b6d0

vercel bot deployed to Preview – discord-js-guide June 22, 2025 09:21 View deployment

refactor: more kbd use

205a609

Qjuh requested changes Jun 22, 2025

View reviewed changes

github-project-automation bot moved this from Todo to Review in Progress in discord.js Jun 22, 2025

vercel bot deployed to Preview – discord-js-guide June 22, 2025 11:11 View deployment

vladfrangu requested changes Jun 22, 2025

View reviewed changes

Update apps/guide/content/docs/legacy/app-creation/handling-events.mdx

4f23fb2

Co-authored-by: Naiyar <137700126+imnaiyar@users.noreply.github.com>

vercel bot deployed to Preview – discord-js-guide June 22, 2025 13:28 View deployment

	- Working with databases (e.g. [sequelize](/guide/legacy/sequelize/) and [keyv](/guide/legacy/keyv/));
	- Working with databases (e.g. [sequelize](./sequelize/) and [keyv](./keyv/keyv));

	reactions](/guide/legacy/popular-topics/reactions.md)!
	reactions](./reactions)!

	`.gitignore`](/creating-your-bot/#git-and-gitignore).
	`.gitignore`](#git-and-gitignore).

	link](/sharding/additional-information.md).
	link](./additional-information).

	It is also worth noting that the GuildVoiceStates [gateway intent](/popular-topics/intents.md#gateway-intents) is required. Without it, the connection will permanently stay in the `signalling` state, and you'll be unable to play audio.
	It is also worth noting that the GuildVoiceStates [gateway intent](/guide/legacy/popular-topics/intents#gateway-intents) is required. Without it, the connection will permanently stay in the `signalling` state, and you'll be unable to play audio.


		## Life cycle

		Voice connections have their own life cycle, with five distinct states. You can follow the methods discussed in the [life cycles](/voice/life-cycles.md) section to subscribe to changes to voice connections.


		### Playing audio

		You can create [audio resources](./audio-resources.md) and then play them on an audio player.


		Environment variables are special values for your environment (e.g., terminal session, Docker container, or environment variable file). You can pass these values into your code's scope so that you can use them.

		One way to pass in environment variables is via the command line interface. When starting your app, instead of `node index.js`, use `TOKEN=your-token-goes-here node index.js`. You can repeat this pattern to expose other values as well.

Uh oh!

feat(guide): port legacy guide #10938

Are you sure you want to change the base?

feat(guide): port legacy guide #10938

Conversation

almostSouji commented Jun 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vercel bot commented Jun 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Qjuh Jun 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Qjuh Jun 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

codecov bot commented Jun 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vladfrangu Jun 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

almostSouji commented Jun 17, 2025 •

edited

Loading

vercel bot commented Jun 17, 2025 •

edited

Loading

Qjuh Jun 22, 2025 •

edited

Loading

Qjuh Jun 22, 2025 •

edited

Loading

codecov bot commented Jun 22, 2025 •

edited

Loading

vladfrangu Jun 22, 2025 •

edited

Loading