feat: add page about setting up with a proxy

code-samples/additional-info/proxy/14/index.js

@@ -0,0 +1,43 @@
+const { ProxyAgent } = require('undici');
+const { Client } = require('discord.js');
+const { bootstrap } = require('global-agent');
+
+bootstrap();
+
+class NodeGlobalProxy {
+	config = {
+		http: '',
+		https: '',
+	};
+
+	constructor(config) {
+		this.config = config;
+	}
+
+	start() {
+		global.GLOBAL_AGENT.HTTP_PROXY = this.config.http;
+		global.GLOBAL_AGENT.HTTPS_PROXY = this.config.https;
+	}
+
+	stop() {
+		global.GLOBAL_AGENT.HTTP_PROXY = null;
+		global.GLOBAL_AGENT.HTTPS_PROXY = null;
+	}
+}
+
+const proxy = new NodeGlobalProxy({
+	http: 'http://my-proxy-server:port',
+	https: 'http://my-proxy-server:port',
+});
+
+proxy.start();
+
+// eslint-disable-next-line no-unused-vars
+const client = new Client({
+	// other client options
+	rest: {
+		agent: new ProxyAgent('http://my-proxy-server:port'),
+	},
+});
+
+client.login('your-token-goes-here');

guide/.vuepress/sidebar.ts

@@ -150,6 +150,7 @@ export default {
 				'/additional-info/collections.md',
 				'/additional-info/async-await.md',
 				'/additional-info/rest-api.md',
+				'/additional-info/proxy.md',
 				'/additional-info/changes-in-v13.md',
 				'/additional-info/changes-in-v14.md',
 			],

guide/additional-info/proxy.md

@@ -0,0 +1,119 @@
+# Using a proxy with Discord.js
+
+It may be necessary to use a proxy when using Discord.js, for example when you are deploying your bot on a server that has a web filtering firewall that only allows outside traffic through the proxy. This guide will show you how to set up a proxy with Discord.js.
+
+A proxy for Discord.js requires 2 separate setups, one for REST and one for WebSocket.
+
+## Prerequisites
+
+In order to set up a proxy for Discord.js, you will need to install the following packages:
+
+:::: code-group
+::: code-group-item npm
+
+```sh:no-line-numbers
+npm install undici global-agent
+```
+
+:::
+::: code-group-item yarn
+
+```sh:no-line-numbers
+yarn add undici global-agent
+```
+
+:::
+::: code-group-item pnpm
+
+```sh:no-line-numbers
+pnpm add undici global-agent
+```
+
+:::
+::: code-group-item bun
+
+```sh:no-line-numbers
+bun add undici global-agent
+```
+
+:::
+::::
+
+## Setting up the proxy for REST calls
+
+To set up a proxy for REST calls, you should provide a custom `ProxyAgent` to the `Client` constructor. The `ProxyAgent` must be imported from the `undici` package, which is the package that `@discordjs/rest` uses to make HTTP requests.
+
+```js {6-8}
+const { ProxyAgent } = require('undici');
+const { Client } = require('discord.js');
+
+const myClient = new Client({
+	// other client options
+	rest: {
+		agent: new ProxyAgent('http://my-proxy-server:port'),
+	},
+});
+```
+
+:::tip
+For further information on the `undici` `ProxyAgent`, please refer to the [undici documentation](https://undici.nodejs.org/#/docs/api/ProxyAgent.md).
+:::
+
+## Setting up the proxy for WebSocket
+
+To set up a proxy for WebSocket, you can use the `global-agent` package. You will need to provide some custom configuration to activate it:
+
+```js {1-24}
+const { bootstrap } = require('global-agent');
+
+bootstrap();
+
+class NodeGlobalProxy {
+	config = {
+		http: '',
+		https: '',
+	};
+
+	constructor(config) {
+		this.config = config;
+	}
+
+	start() {
+		global.GLOBAL_AGENT.HTTP_PROXY = this.config.http;
+		global.GLOBAL_AGENT.HTTPS_PROXY = this.config.https;
+	}
+
+	stop() {
+		global.GLOBAL_AGENT.HTTP_PROXY = null;
+		global.GLOBAL_AGENT.HTTPS_PROXY = null;
+	}
+}
+
+module.exports = {
+	NodeGlobalProxy,
+};
+```
+
+Now in the file where you create your client, you can import the `NodeGlobalProxy` class and start it with the proxy URL:
+
+```js {2,4-7,9}
+const { Client } = require('discord.js');
+const { NodeGlobalProxy } = require('./NodeGlobalProxy');
+
+const proxy = new NodeGlobalProxy({
+	http: 'http://my-proxy-server:port',
+	https: 'http://my-proxy-server:port',
+});
+
+proxy.start();
+
+const client = new Client({
+	// client options, including the proxy agent as described above
+});
+
+client.login('your-token-goes-here');
+```
+
+## Resulting code
+
+<ResultingCode />