How can I migrate my code to Discord.js v12 from v11?

Question

I upgraded to Discord.js v12, but it broke my existing v11 code. Here are some examples of things that cause errors:

// TypeError: client.users.get is not a function
const user = client.users.get('123456789012345678')

// TypeError: message.guild.roles.find is not a function
const role = message.guild.roles.find(r => r.name === 'Admin')

// TypeError: message.member.addRole is not a function
await message.member.addRole(role)

// TypeError: message.guild.createChannel is not a function
await message.guild.createChannel('welcome')

// TypeError: message.channel.fetchMessages is not a function
const messages = await message.channel.fetchMessages()

const {RichEmbed} = require('discord.js')
// TypeError: RichEmbed is not a constructor
const embed = new RichEmbed()

const connection = await message.channel.join()
// TypeError: connection.playFile is not a function
const dispatcher = connection.playFile('./music.mp3')

How can I migrate my code to Discord.js v12 and fix these errors? Where can I see the breaking changes v12 introduced?

Answer 1

Here are some of the most common breaking changes introduced in Discord.js v12 that people run into.

Managers

Properties such as Client#users and Guild#roles are now managers, instead of the cached Collection of items. To access this collection, use the cache property:

const user = client.users.cache.get('123456789012345678')
const role = message.guild.roles.cache.find(r => r.name === 'Admin')

In addition, methods such as GuildMember#addRole, Guild#createChannel, and TextBasedChannel#fetchMessages have moved to the respective managers:

await message.member.roles.add(role)
await message.guild.channels.create('welcome')
const messages = await message.channel.messages.fetch()

Collection

The Collection class (e.g. client.users.cache, guild.roles.cache, guild.channels.cache) now only accepts functions, not property keys and values, for .find and .findKey:

// v11: collection.find('property', 'value')
collection.find(item => item.property === 'value')

.exists, .deleteAll, .filterArray, .findAll have also been removed:

// v11: collection.exists('property', 'value')
collection.some(item => item.property === 'value')

// v11: collection.deleteAll()
Promise.all(collection.map(item => item.delete()))

// v11: collection.filterArray(fn)
collection.filter(fn).array()

// v11: collection.findAll('property', value')
collection.filter(item => item.property === 'value').array()

.tap now runs a function on the collection instead of every item in the collection:

// v11: collection.tap(item => console.log(item))
collection.each(item => console.log(item))

// New .tap behaviour:
collection.tap(coll => console.log(`${coll.size} items`))

RichEmbed/MessageEmbed

The RichEmbed class has been removed; use the MessageEmbed class instead which is now used for all embeds (instead of just received embeds).

const {MessageEmbed} = require('discord.js')
const embed = new MessageEmbed()

The addBlankField method has also been removed. This method simply added a field with a zero-width space (\u200B) as the name and value, so to add a blank field do this:

embed.addField('\u200B', '\u200B')

Voice

All of the VoiceConnection/VoiceBroadcast#play*** methods have been unified under a single play method:

const dispatcher = connection.play('./music.mp3')

Client#createVoiceBroadcast has been moved to the ClientVoiceManager:

const broadcast = client.voice.createVoiceBroadcast()

Additionally, StreamDispatcher extends Node.js' stream.Writable, so use dispatcher.destroy() instead of dispatcher.end(). The end event has been removed in favour of the native finish event.

Image URLs

Properties such as User#displayAvatarURL and Guild#iconURL are now methods:

const avatar = user.displayAvatarURL()
const icon = mesage.guild.iconURL()

You can also pass an ImageURLOptions to customise things like format and size.

More information

To find out more about the v12 breaking changes, take a look at the updating guide and the changelog. The documentation is also a good resource for finding a particular method/property.