Updating from v13 to v14

Before you start

Make sure you're using the latest LTS version of Node. To check your Node version, use node -v in your terminal or command prompt, and if it's not high enough, update it! There are many resources online to help you with this step based on your host system.

Various packages are now included in v14

If you previously had @discordjs/builders, @discordjs/formatters, @discordjs/rest, or discord-api-types manually installed, it's highly recommended that you uninstall the packages to avoid package version conflicts.

npm uninstall @discordjs/builders @discordjs/formatters @discordjs/rest discord-api-types

yarn remove @discordjs/builders @discordjs/formatters @discordjs/rest discord-api-types

pnpm remove @discordjs/builders @discordjs/formatters @discordjs/rest discord-api-types

Breaking Changes

API version

discord.js v14 makes the switch to Discord API v10!

Common Breakages

Enum Values

Any areas that used to accept a string or number type for an enum parameter will now only accept exclusively numbers.

In addition, the old enums exported by discord.js v13 and lower are replaced with new enums from discord-api-typesopen in new window.

New enum differences

Most of the difference between enums from discord.js and discord-api-types can be summarized as so:

Enums are singular, i.e., ApplicationCommandOptionTypes -> ApplicationCommandOptionType
Enums that are prefixed with Message no longer have the Message prefix, i.e., MessageButtonStyles -> ButtonStyle
Enum values are PascalCase rather than SCREAMING_SNAKE_CASE, i.e., .CHAT_INPUT -> .ChatInput

WARNING

You might be inclined to use raw numbers (most commonly referred to as magic numbersopen in new window) instead of enum values. This is highly discouraged. Enums provide more readability and are more resistant to changes in the API. Magic numbers can obscure the meaning of your code in many ways, check out this blog postopen in new window if you want more context on as to why they shouldn't be used.

Common enum breakages

Areas like Client initialization, JSON slash commands and JSON message components will likely need to be modified to accommodate these changes:

Common Client Initialization Changes

- const { Client, Intents } = require('discord.js');
+ const { Client, GatewayIntentBits, Partials } = require('discord.js');

- const client = new Client({ intents: [Intents.FLAGS.GUILDS], partials: ['CHANNEL'] });
+ const client = new Client({ intents: [GatewayIntentBits.Guilds], partials: [Partials.Channel] });

1
2
3
4
5

Common Application Command Data changes

+ const { ApplicationCommandType, ApplicationCommandOptionType } = require('discord.js');

const command = {
  name: 'ping',
- type: 'CHAT_INPUT',
+ type: ApplicationCommandType.ChatInput,
  options: [{
    name: 'option',
    description: 'A sample option',
-   type: 'STRING',
+   type: ApplicationCommandOptionType.String,
  }],
};

1
2
3
4
5
6
7
8
9
10
11
12
13

Common Button Data changes

+ const { ButtonStyle } = require('discord.js');

const button = {
  label: 'test',
- style: 'PRIMARY',
+ style: ButtonStyle.Primary,
  customId: '1234'
}

1
2
3
4
5
6
7
8

Removal of method-based type guards

Channels

Some channel type guard methods that narrowed to one channel type have been removed. Instead compare the type property against a ChannelTypeopen in new window enum member to narrow channels.

-channel.isText()
+channel.type === ChannelType.GuildText

-channel.isVoice()
+channel.type === ChannelType.GuildVoice

-channel.isDM()
+channel.type === ChannelType.DM

1
2
3
4
5
6
7
8

Builders

Builders are no longer returned by the API like they were previously. For example you send the API an EmbedBuilder but you receive an Embed of the same data from the API. This may affect how your code handles received structures such as components. Refer to message component changes section for more details.

Added disableValidators() and enableValidators() as top-level exports which disable or enable validation (enabled by default).

Consolidation of `create()` & `edit()` parameters

Various create() and edit() methods on managers and objects have had their parameters consolidated. The changes are below:

Guild#edit() now takes reason in the data parameter
GuildChannel#edit() now takes reason in the data parameter
GuildEmoji#edit() now takes reason in the data parameter
Role#edit() now takes reason in the data parameter
Sticker#edit() now takes reason in the data parameter
ThreadChannel#edit() now takes reason in the data parameter
GuildChannelManager#create() now takes name in the options parameter
GuildChannelManager#createWebhook() (and other text-based channels) now takes channel and name in the options parameter
GuildChannelManager#edit() now takes reason as a part of data
GuildEmojiManager#edit() now takes reason as a part of data
GuildManager#create() now takes name as a part of options
GuildMemberManager#edit() now takes reason as a part of data
GuildMember#edit() now takes reason as a part of data
GuildStickerManager#edit() now takes reason as a part of data
RoleManager#edit() now takes reason as a part of options
Webhook#edit() now takes reason as a part of options
GuildEmojiManager#create() now takes attachment and name as a part of options
GuildStickerManager#create() now takes file, name, and tags as a part of options

Activity

The following properties have been removed as they are not documented by Discord:

Activity#id
Activity#platform
Activity#sessionId
Activity#syncId

Application

Application#fetchAssets() has been removed as it is no longer supported by the API.

BitField

BitField constituents now have a BitField suffix to avoid naming conflicts with the enum names:

- new Permissions()
+ new PermissionsBitField()

- new MessageFlags()
+ new MessageFlagsBitField()

- new ThreadMemberFlags()
+ new ThreadMemberFlagsBitField()

- new UserFlags()
+ new UserFlagsBitField()

- new SystemChannelFlags()
+ new SystemChannelFlagsBitField()

- new ApplicationFlags()
+ new ApplicationFlagsBitField()

- new Intents()
+ new IntentsBitField()

- new ActivityFlags()
+ new ActivityFlagsBitField()

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

#FLAGS has been renamed to #Flags

CDN

The methods that return CDN URLs have changed. Here is an example on a User:

- const url = user.displayAvatarURL({ dynamic: true, format: "png", size: 1_024 });
+ const url = user.displayAvatarURL({ extension: "png", size: 1_024 });

1
2

Dynamic URLs use ImageURLOptionsopen in new window and static URLs use BaseImageURLOptionsopen in new window. Since dynamic URLs are returned by default, this option has been renamed to forceStatic which forces the return of a static URL. Additionally, format has been renamed to extension.

CategoryChannel

CategoryChannel#children is no longer a Collection of channels the category contains. It is now a manager (CategoryChannelChildManager). This also means CategoryChannel#createChannel() has been moved to the CategoryChannelChildManager.

Channel

The following type guards have been removed:

Channel#isText()
Channel#isVoice()
Channel#isDirectory()
Channel#isDM()
Channel#isGroupDM()
Channel#isCategory()
Channel#isNews()

Refer to this section for more context.

The base channel class is now BaseChannel.

Client

The restWsBridgeTimeout client option has been removed.

CommandInteractionOptionResolver

CommandInteractionOptionResolver#getMember() no longer has a parameter for required. See this pull requestopen in new window for more information.

Constants

Many constant objects and key arrays are now top-level exports for example:

- const { Constants } = require('discord.js');
- const { Colors } = Constants;
+ const { Colors } = require('discord.js');

1
2
3

The refactored constants structures have PascalCase member names as opposed to SCREAMING_SNAKE_CASE member names.
Many of the exported constants structures have been replaced and renamed:

- Opcodes
+ GatewayOpcodes

- WSEvents
+ GatewayDispatchEvents

- WSCodes
+ GatewayCloseCodes

- InviteScopes
+ OAuth2Scopes

1
2
3
4
5
6
7
8
9
10
11

Events

The message and interaction events are now removed. Use messageCreate and interactionCreate instead.

applicationCommandCreate, applicationCommandDelete and applicationCommandUpdate have all been removed. See this pull requestopen in new window for more information.

The threadMembersUpdate event now emits the users who were added, the users who were removed, and the thread respectively.

GuildBanManager

Developers should utilise deleteMessageSeconds instead of days and deleteMessageDays:

<GuildBanManager>.create('123456789', {
-  days: 3
-  deleteMessageDays: 3
+  deleteMessageSeconds: 3 * 24 * 60 * 60
});

1
2
3
4
5

deleteMessageDays (introduced with version 14) and days are both deprecated and will be removed in the future.

Guild

Guild#setRolePositions() and Guild#setChannelPositions() have been removed. Use RoleManager#setPositions() and GuildChannelManager#setPositions() instead respectively.

Guild#maximumPresences no longer has a default value of 25,000.

Guild#me has been moved to GuildMemberManager#me. See this pull requestopen in new window for more information.

GuildAuditLogs & GuildAuditLogsEntry

GuildAuditLogs.build() has been removed as it has been deemed defunct. There is no alternative.

The following properties & methods have been moved to the GuildAuditLogsEntry class:

GuildAuditLogs.Targets
GuildAuditLogs.actionType()
GuildAuditLogs.targetType()

GuildMember

GuildMember#pending is now nullable to account for partial guild members. See this issueopen in new window for more information.

IntegrationApplication

IntegrationApplication#summary has been removed as it is no longer supported by the API.

Interaction

Whenever an interaction is replied to and one fetches the reply, it could possibly give an APIMessage if the guild was not cached. However, interaction replies now always return a discord.js Message object with fetchReply as true.

The base interaction class is now BaseInteraction.

Invite

Invite#inviter is now a getter and resolves structures from the cache.

MessageAttachment

MessageAttachment has now been renamed to AttachmentBuilder.

- new MessageAttachment(buffer, 'image.png');

+ new AttachmentBuilder(buffer, { name: 'image.png' });

1
2
3

MessageComponent

MessageComponents have been renamed as well. They no longer have the Message prefix, and now have a Builder suffix:

- const button = new MessageButton();
+ const button = new ButtonBuilder();

- const selectMenu = new MessageSelectMenu();
+ const selectMenu = new StringSelectMenuBuilder();

- const actionRow = new MessageActionRow();
+ const actionRow = new ActionRowBuilder();

- const textInput = new TextInputComponent();
+ const textInput = new TextInputBuilder();

1
2
3
4
5
6
7
8
9
10
11

Components received from the API are no longer directly mutable. If you wish to mutate a component from the API, use ComponentBuilder#from. For example, if you want to make a button mutable:

- const editedButton = receivedButton
-   .setDisabled(true);

+ const { ButtonBuilder } = require('discord.js');
+ const editedButton = ButtonBuilder.from(receivedButton)
+   .setDisabled(true);

1
2
3
4
5
6

MessageManager

MessageManager#fetch()'s second parameter has been removed. The BaseFetchOptions the second parameter once was is now merged into the first parameter.

- messageManager.fetch('1234567890', { cache: false, force: true });
+ messageManager.fetch({ message: '1234567890', cache: false, force: true });

1
2

MessageSelectMenu

MessageSelectMenu has been renamed to StringSelectMenuBuilder
StringSelectMenuBuilder#addOption() has been removed. Use StringSelectMenuBuilder#addOptions() instead.

MessageEmbed

MessageEmbed has now been renamed to EmbedBuilder.
EmbedBuilder#setAuthor() now accepts a sole EmbedAuthorOptionsopen in new window object.
EmbedBuilder#setFooter() now accepts a sole EmbedFooterOptionsopen in new window object.
EmbedBuilder#addField() has been removed. Use EmbedBuilder#addFields() instead.

- new MessageEmbed().addField('Inline field title', 'Some value here', true);

+ new EmbedBuilder().addFields([
+  { name: 'one', value: 'one', inline: true },
+  { name: 'two', value: 'two', inline: true },
+]);

1
2
3
4
5
6

Modal has been renamed as well and now has a Builder suffix:

- const modal = new Modal();
+ const modal = new ModalBuilder();

1
2

PartialTypes

The PartialTypes string array has been removed. Use the Partials enum instead.

In addition to this, there is now a new partial: Partials.ThreadMember.

Permissions

Thread permissions USE_PUBLIC_THREADS and USE_PRIVATE_THREADS have been removed as they are deprecated in the API. Use CREATE_PUBLIC_THREADS and CREATE_PRIVATE_THREADS respectively.

ManageEmojisAndStickers has been deprecated due to API changes. Its replacement is ManageGuildExpressions. See this pull requestopen in new window for more information.

PermissionOverwritesManager

Overwrites are now keyed by the PascalCase permission key rather than the SCREAMING_SNAKE_CASE permission key.

REST Events

apiRequest

This REST event has been removed as discord.js now uses Undiciopen in new window as the underlying request handler. You must now use a Diagnostics Channelopen in new window. Here is a simple example:

import diagnosticsChannel from 'node:diagnostics_channel';

diagnosticsChannel.channel('undici:request:create').subscribe(data => {
	// If you use TypeScript, `data` may be casted as
	// `DiagnosticsChannel.RequestCreateMessage`
	// from Undici to receive type definitions.
	const { request } = data;
	console.log(request.method); // Log the method
	console.log(request.path); // Log the path
	console.log(request.headers); // Log the headers
	console.log(request); // Or just log everything!
});

1
2
3
4
5
6
7
8
9
10
11
12

You can find further examples at the Undici Diagnostics Channel documentationopen in new window.

apiResponse

This REST event has been renamed to response and moved to Client#rest:

- client.on('apiResponse', ...);
+ client.rest.on('response', ...);

1
2

invalidRequestWarning

This REST event has been moved to Client#rest:

- client.on('invalidRequestWarning', ...);
+ client.rest.on('invalidRequestWarning', ...);

1
2

rateLimit

This REST event has been renamed to rateLimited and moved to Client#rest:

- client.on('rateLimit', ...);
+ client.rest.on('rateLimited', ...);

1
2

RoleManager

Role.comparePositions() has been removed. Use RoleManager#comparePositions() instead.

Sticker

Sticker#tags is now a nullable string (string | null). Previously, it was a nullable array of strings (string[] | null). See this pull requestopen in new window for more information.

ThreadChannel

The MAX helper used in ThreadAutoArchiveDuration has been removed. Discord has since allowed any guild to use any auto archive time which makes this helper redundant.

ThreadMemberManager

ThreadMemberManager#fetch()'s second parameter has been removed. The BaseFetchOptions the second parameter once was is now merged into the first parameter. In addition, the boolean helper to specify cache has been removed.

Usage is now as follows:

// The second parameter is merged into the first parameter.
- threadMemberManager.fetch('1234567890', { cache: false, force: true });
+ threadMemberManager.fetch({ member: '1234567890', cache: false, force: true });

// The lone boolean has been removed. One must be explicit here.
- threadMemberManager.fetch(false);
+ threadMemberManager.fetch({ cache: false });

1
2
3
4
5
6
7

Util

Util.removeMentions() has been removed. To control mentions, you should use allowedMentions on BaseMessageOptions instead.

Util.splitMessage() has been removed. This utility method is something the developer themselves should do.

Util.resolveAutoArchiveMaxLimit() has been removed. Discord has since allowed any guild to use any auto archive time which makes this method redundant.

Other functions in Util have been moved to top-level exports so you can directly import them from discord.js.

- import { Util } from 'discord.js';
- Util.escapeMarkdown(message);
+ import { escapeMarkdown } from 'discord.js';
+ escapeMarkdown(message);

1
2
3
4

`.deleted` Field(s) have been removed

You can no longer use the deleted property to check if a structure was deleted. See this issueopen in new window for more information.

VoiceChannel

VoiceChannel#editable has been removed. You should use GuildChannel#manageable instead.

VoiceRegion

VoiceRegion#vip has been removed as it is no longer part of the API.

Webhook

Webhook#fetchMessage()'s second parameter no longer allows a boolean to be passed. The cache option in WebhookFetchMessageOptions should be used instead.

Features

ApplicationCommand

NFSW commands are supported.

Attachment

Added support for voice message metadata fields.

AutocompleteInteraction

AutocompleteInteraction#commandGuildId has been added which is the id of the guild the invoked application command is registered to.

BaseChannel

Added support for BaseChannel#flags.

Store channels have been removed as they are no longer part of the API.

BaseChannel#url has been added which is a link to a channel, just like in the client.

Additionally, new typeguards have been added:

BaseChannel#isDMBased()
BaseChannel#isTextBased()
BaseChannel#isVoiceBased()

BaseInteraction

Added BaseInteraction#isRepliable() to check whether a given interaction can be replied to.

ClientApplication

Added support for role connection metadata.

Collection

Added Collection#merge() and Collection#combineEntries().
New type: ReadonlyCollection which indicates an immutable Collection.

Collector

A new ignore event has been added which is emitted whenever an element is not collected by the collector.

Component collector options now use the ComponentType enum values:

+ const { ComponentType } = require('discord.js');

const collector = interaction.channel.createMessageComponentCollector({
	filter: collectorFilter,
-	componentType: 'BUTTON',
+	componentType: ComponentType.Button,
	time: 20_000
});

1
2
3
4
5
6
7
8

CommandInteraction

CommandInteraction#commandGuildId has been added which is the id of the guild the invoked application command is registered to.

CommandInteractionOptionResolver

CommandInteractionOptionResolver#getChannel() now has a third parameter which narrows the channel type.

Events

Added support for guildAuditLogEntryCreate event.

ForumChannel

Added support for forum channels.

Added support for ForumChannel#defaultForumLayout.

Guild

Added Guild#setMFALevel() which sets the guild's MFA level.

Added Guild#maxVideoChannelUsers which indicates the maximum number of video channel users.

Added Guild#maxStageVideoChannelUsers which indicates the maximum number of video channel users for stage channels.

Added Guild#disableInvites() which disables the guild's invites.

Added support for the after parameter in Guild#fetchAuditLogs().

GuildChannelManager

videoQualityMode may be used whilst creating a channel to initially set the camera video quality mode.

GuildEmojiManager

Added GuildEmojiManager#delete() and GuildEmojiManager#edit() for managing existing guild emojis.

GuildForumThreadManager

Added GuildForumThreadManager as manager for threads in forum channels.

GuildMember

Added support for GuildMember#flags.

GuildMembersChunk

This object now supports the GuildMembersChunk#notFound property.

GuildMemberManager

Added GuildMemberManager#fetchMe() to fetch the client user in the guild.

Added GuildMemberManager#addRole() and GuildMemberManager#removeRole(). These methods allow a single addition or removal of a role respectively to a guild member, even if uncached.

GuildTextThreadManager

Added GuildTextThreadManager as manager for threads in text channels and announcement channels.

Message

Message#position has been added as an approximate position in a thread.

Added support for role subscription data.

MessageReaction

Added MessageReaction#react() to make the client user react with the reaction the class belongs to.

Role

Added support for role subscriptions.

Added support for Role#tags#guildConnections.

StageChannel

Stage channels now allow messages to be sent in them, much like voice channels.

Sticker

Added support for GIF stickers.

ThreadMemberManager

The new withMember options returns the associated guild member with the thread member.

When fetching multiple thread members alongside withMember, paginated results will be returned. The after and limit option are supported in this scenario.

Webhook

Added Webhook#applicationId.

Added the threadName property in Webhook#send() options which allows a webhook to create a post in a forum channel.

WebSocketManager

discord.js uses @discord.js/wsopen in new window internally.

# Updating from v13 to v14

# Before you start

# Various packages are now included in v14

# Breaking Changes

# API version

# Common Breakages

# Enum Values

# New enum differences

# Common enum breakages

# Common Client Initialization Changes

# Common Application Command Data changes

# Common Button Data changes

# Removal of method-based type guards

# Channels

# Builders

# Consolidation of create() & edit() parameters

# Activity

# Application

# BitField

# CDN

# CategoryChannel

# Channel

# Client

# CommandInteractionOptionResolver

# Constants

# Events

# GuildBanManager

# Guild

# GuildAuditLogs & GuildAuditLogsEntry

# GuildMember

# IntegrationApplication

# Interaction

# Invite

# MessageAttachment

# MessageComponent

# MessageManager

# MessageSelectMenu

# MessageEmbed

# Modal

# PartialTypes

# Permissions

# PermissionOverwritesManager

# REST Events

# apiRequest

# apiResponse

# invalidRequestWarning

# rateLimit

# RoleManager

# Sticker

# ThreadChannel

# ThreadMemberManager

# Util

# .deleted Field(s) have been removed

# VoiceChannel

# VoiceRegion

# Webhook

# Features

# ApplicationCommand

# Attachment

# AutocompleteInteraction

# BaseChannel

# BaseInteraction

# ClientApplication

# Collection

# Collector

# CommandInteraction

# CommandInteractionOptionResolver

# Events

# ForumChannel

# Guild

# GuildChannelManager

# GuildEmojiManager

# GuildForumThreadManager

# GuildMember

# GuildMembersChunk

# GuildMemberManager

# GuildTextThreadManager

# Message

# MessageReaction

# Role

Updating from v13 to v14

Before you start

Various packages are now included in v14

Breaking Changes

API version

Common Breakages

Enum Values

New enum differences

Common enum breakages

Common Client Initialization Changes

Common Application Command Data changes

Common Button Data changes

Removal of method-based type guards

Channels

Builders

Consolidation of `create()` & `edit()` parameters

Activity

Application

BitField

CDN

CategoryChannel

Channel

Client

CommandInteractionOptionResolver

Constants

Events

GuildBanManager

Guild

GuildAuditLogs & GuildAuditLogsEntry

GuildMember

IntegrationApplication

Interaction

Invite

MessageAttachment

MessageComponent

MessageManager

MessageSelectMenu

MessageEmbed

Modal

PartialTypes

Permissions

PermissionOverwritesManager

REST Events

apiRequest

apiResponse

invalidRequestWarning

rateLimit

RoleManager

Sticker

ThreadChannel

ThreadMemberManager

Util

`.deleted` Field(s) have been removed

VoiceChannel

VoiceRegion

Webhook

Features

ApplicationCommand

Attachment

AutocompleteInteraction

BaseChannel

BaseInteraction

ClientApplication

Collection

Collector

CommandInteraction

CommandInteractionOptionResolver

Events

ForumChannel

Guild

GuildChannelManager

GuildEmojiManager

GuildForumThreadManager

GuildMember

GuildMembersChunk

GuildMemberManager

GuildTextThreadManager

Message

MessageReaction

Role