Roles

Create, fetch, edit, and delete guild roles. Use PermissionFlags and resolvePermissionsToBitfield for permission bitfields.

Overview

Guild roles can be created, fetched, edited, and deleted. Use guild.createRole(), guild.fetchRoles(), guild.fetchRole(roleId), role.edit(), and role.delete(). Requires Manage Roles permission. For permission bitfields, use resolvePermissionsToBitfield() or role.has() to check a role's permissions.

Create a role

Use guild.createRole() to create a new role. Pass name, permissions, color, hoist, mentionable, unicode_emoji, position, or hoist_position. Permissions accept PermissionResolvable (string, number, array) for convenience.

import { Client, Events, PermissionFlags, resolvePermissionsToBitfield } from '@erinjs/core';

const client = new Client({ intents: 0 });

client.on(Events.MessageCreate, async (message) => {
  if (message.content === '!createrole' && message.guildId) {
    const guild = client.guilds.get(message.guildId) ?? await client.guilds.resolve(message.guildId);
    if (!guild) return;

    const role = await guild.createRole({
      name: 'Moderator',
      permissions: ['BanMembers', 'KickMembers', 'ManageMessages'],
      color: 0x5865f2,
      hoist: true,
      mentionable: false,
    });
    await message.reply(`Created role ${role.name} (${role.id})`);
  }
});

await client.login(process.env.ERIN_BOT_TOKEN);

Fetch roles

Use guild.fetchRoles() to fetch all roles from the API and cache them. Use guild.fetchRole(roleId) to fetch a single role by ID. Throws ErinError with ROLE_NOT_FOUND on 404.

// Fetch all roles (updates guild.roles cache)
const roles = await guild.fetchRoles();

// Fetch a single role by ID
const role = await guild.fetchRole(roleId);
console.log(role.name, role.color);

Edit a role

Use role.edit() to update a role. Pass any of name, permissions, color, hoist, mentionable, unicode_emoji, position, hoist_position. Permissions accept PermissionResolvable.

const role = guild.roles.get(roleId) ?? await guild.fetchRole(roleId);
await role.edit({
  name: 'Senior Mod',
  permissions: ['BanMembers', 'KickMembers', 'ManageMessages', 'ManageRoles'],
  color: 0x57f287,
});

Delete a role

Use role.delete() to remove a role. The role is removed from guild.roles cache.

const role = guild.roles.get(roleId) ?? await guild.fetchRole(roleId);
await role.delete();
await message.reply('Role deleted.');

Check role permissions

Use role.has(permission) to check if a role has a specific permission. Administrator implies all permissions.

import { PermissionFlags } from '@erinjs/core';

if (role.has(PermissionFlags.BanMembers)) {
  await message.reply('This role can ban members.');
}
if (role.has('ManageChannels')) {
  await message.reply('This role can manage channels.');
}

Add/remove roles from members (member.roles)

Discord.js Compatible

See API reference for full details.

Use member.roles.add(), member.roles.remove(), and member.roles.set() for Discord.js-style role management. member.roles.cache is a Collection of Role objects. Also available: guild.addRoleToMember() and guild.removeRoleFromMember() when you only have user ID.

// Discord.js parity: member.roles.add(), remove(), set()
const member = await guild.fetchMember(userId);

await member.roles.add(roleId);        // Add a role
await member.roles.remove(roleId);     // Remove a role
await member.roles.set(['id1', 'id2']); // Replace all roles

// Check if member has a role
if (member.roles.cache.has(roleId)) {
  await message.reply('Member already has this role.');
}

// Guild-level: when you only have user ID (no member fetch needed)
await guild.addRoleToMember(userId, roleId);
await guild.removeRoleFromMember(userId, roleId);

Permission bitfields for create/edit

When creating or editing roles, pass permissions as a string (API format), number, PermissionString, or array. Use resolvePermissionsToBitfield() to combine multiple permissions. Handles high bits (PinMessages, ModerateMembers, etc.) correctly with BigInt.

import { resolvePermissionsToBitfield, PermissionFlags } from '@erinjs/core';

// Single permission by name
resolvePermissionsToBitfield('SendMessages');  // "2048"

// Array of permissions (OR'd together)
resolvePermissionsToBitfield(['SendMessages', 'ViewChannel', 'ReadMessageHistory']);
// Returns combined bitfield as string

// From PermissionFlags enum
resolvePermissionsToBitfield(PermissionFlags.BanMembers);  // "4"