chrxmaticc-framework

A batteries-included Discord bot framework built on discord.js v14 with Lavalink music, AI integration, XP system and Postgres support — all in ~10 lines.

Install

npm install chrxmaticc-framework discord.js

Basic setup

require("dotenv").config();
const { ChrxClient } = require("chrxmaticc-framework");

const bot = new ChrxClient({
  token: process.env.BOT_TOKEN,
});

bot.start();

With music

const { ChrxClient } = require("chrxmaticc-framework");

const bot = new ChrxClient({
  token: process.env.BOT_TOKEN,
  lavalink: {
    host: process.env.LAVA_HOST,
    port: 2333,
    password: process.env.LAVA_PASS,
    secure: false,
  },
  modules: {
    music: true,
  },
});

bot.start();

Full setup (music + AI + XP + database)

require("dotenv").config();
const { ChrxClient } = require("chrxmaticc-framework");

const bot = new ChrxClient({
  token: process.env.BOT_TOKEN,

  lavalink: {
    host: process.env.LAVA_HOST,
    port: 2333,
    password: process.env.LAVA_PASS,
    secure: false,
  },

  modules: {
    music: true,
    xp: true,
    database: process.env.DATABASE_URL,
    ai: {
      apiKey: process.env.AI_KEY,
      model: "gpt-3.5-turbo",
      provider: "openai", // or "anthropic"
    },
  },
});

bot.start();

Commands

Put your commands in a commands/ folder (subfolders supported):

// commands/ping.js
const { SlashCommandBuilder } = require("discord.js");

module.exports = {
  data: new SlashCommandBuilder()
    .setName("ping")
    .setDescription("Pong!"),
  async execute(interaction) {
    await interaction.reply("Pong!");
  },
};

Events

Put your events in an events/ folder:

// events/ready.js
module.exports = {
  name: "ready",
  once: true,
  execute(client) {
    console.log(`Logged in as ${client.user.tag}`);
  },
};

Song markers (built-in)

The music module includes a clip marker system. Use /player-set to set start/end timestamps on any song.

/player-set start 1:43        → jumps to 1:43 when the song plays
/player-set end 2:44          → cuts off at 2:44
/player-set end 2:44 loop:true → loops between start and end markers
/player-set clear both        → removes all markers from the song

AI usage in commands

async execute(interaction) {
  const answer = await interaction.client.ai.ask("What is the meaning of life?");
  await interaction.reply(answer);
}

XP usage in commands

async execute(interaction) {
  const data = await interaction.client.chrx.xp.getUser(
    interaction.user.id,
    interaction.guild.id
  );
  await interaction.reply(`You are level ${data.level} with ${data.xp} XP.`);
}

.env example

BOT_TOKEN=your_bot_token
CLIENT_ID=your_client_id
LAVA_HOST=your_lavalink_host
LAVA_PORT=2333
LAVA_PASS=your_lavalink_password
LAVA_SECURE=false
DATABASE_URL=your_postgres_url
AI_KEY=your_ai_key

(Only change LAVA_PORT to 443 if secure.)

BOT_TOKEN=your_bot_token
CLIENT_ID=your_client_id
LAVA_HOST=your_lavalink_host
LAVA_PORT=443
LAVA_PASS=your_lavalink_password
LAVA_SECURE=true
DATABASE_URL=your_postgres_url
AI_KEY=your_ai_key

Slash Command Addon

chrxmaticc-framework v2.0.0

What's new

ChrxCommandBuilder — write commands in as little as 6 lines.

No more SlashCommandBuilder boilerplate, no more manual module.exports = { data, execute }, no more writing cooldowns and permission checks yourself. Just name, description, and your logic.

How it works

const { ChrxCommandBuilder } = require("chrxmaticc-framework");

module.exports = new ChrxCommandBuilder({
  name: "balance",
  description: "Check your coin balance",
  cooldown: 5,
  options: [
    { name: "user", description: "User to check", type: "user", required: false }
  ],
  async run(interaction, { economy }) {
    const target = interaction.options.getUser("user") ?? interaction.user;
    const data = await economy.getBalance(target.id, interaction.guild.id);
    interaction.reply(`💰 **${target.username}** — ${data.balance} coins`);
  }
});

Features

• Auto option type mapping — write "user" instead of ApplicationCommandOptionType.User. Supports string, number, integer, boolean, user, channel, role, mentionable, attachment
• Built-in cooldowns — just pass cooldown: 5 (seconds), handled automatically per user
• Built-in permission checks — pass permission: "BanMembers" and it checks before running
• Built-in error handling — any error in run() is caught and sends a clean error message automatically. Custom errors via throw new Error("your message")
• Plugin injection — all plugins injected into run() automatically, no manual requires needed. Access economy, moderation, giveaways, tickets, welcome, polls, reminders, starboard, automod, xp, ai, db
• Owner only — pass ownerOnly: true to restrict a command to the bot owner
• Choices — pass choices: [{ name, value }] on string/integer/number options for dropdown menus
• Still fully flexible — run() is raw discord.js, no ceiling, do anything you could do in a normal command

Changes

• Added ChrxCommandBuilder to core
• Updated Client.js with registerPlugin() method for automatic plugin injection
• Updated index.js to export ChrxCommandBuilder
• Added GuildMessageReactions intent and Partials.Reaction automatically for Starboard plugin

Breaking changes

• None — all v1.x code works as is

Migration from raw commands

Before:

const { SlashCommandBuilder } = require("discord.js");
module.exports = {
  data: new SlashCommandBuilder()
    .setName("ping")
    .setDescription("Pong!"),
  async execute(interaction) {
    interaction.reply("Pong!");
  }
}

After:

module.exports = new ChrxCommandBuilder({
  name: "ping",
  description: "Pong!",
  cooldown: 5,
  async run(interaction) {
    interaction.reply("Pong!");
  }
});