Chrxmaticc Framework

1.4.0 · active · verified Sun Apr 19

Chrxmaticc Framework is a feature-rich, 'batteries-included' framework for developing Discord bots using `discord.js v14`. As of version 1.4.0, it provides out-of-the-box support for music via Lavalink, AI integration, a user experience (XP) system, and PostgreSQL database persistence, designed to streamline bot development with minimal boilerplate. The framework emphasizes a quick setup, allowing developers to create functional bots with core features in roughly ten lines of code. A significant major release, v2.0.0, is planned or recently released, which introduces a new `ChrxCommandBuilder` for simplified command creation, replacing some of the standard `discord.js` boilerplate. This framework aims for a steady release cadence, providing new features and improvements primarily focused on simplifying common Discord bot functionalities, targeting developers who prefer an opinionated, all-in-one solution rather than assembling individual packages.

Common errors

```
Error: Invalid token provided.
```
cause The `BOT_TOKEN` environment variable is either missing or contains an incorrect Discord bot token.

fix Ensure your `.env` file has `BOT_TOKEN=YOUR_DISCORD_BOT_TOKEN` and that `YOUR_DISCORD_BOT_TOKEN` is the correct token from the Discord Developer Portal.
```
Lavalink connection failed!
```
cause The bot could not establish a connection to the configured Lavalink server.

fix Verify that your Lavalink server is running and accessible. Check `LAVA_HOST`, `LAVA_PORT`, `LAVA_PASS`, and `LAVA_SECURE` in your `.env` file. Ensure firewall rules allow connection.
```
Cannot find module 'discord.js'
```
cause The `discord.js` peer dependency has not been installed.

fix Run `npm install discord.js` in your project directory.
```
ReferenceError: process is not defined
```
cause The `dotenv` package (or equivalent) has not been configured to load environment variables, or the script is running in an environment where `process` is unavailable (e.g., browser without polyfill).

fix Add `require("dotenv").config();` at the very top of your main bot file (e.g., `index.js` or `bot.js`) to load variables from your `.env` file into `process.env`.
```
TypeError: interaction.client.ai.ask is not a function
```
cause The AI module was not enabled in the ChrxClient configuration or the `AI_KEY` environment variable is missing.

fix Ensure `modules: { ai: { apiKey: process.env.AI_KEY, ... } }` is present in your ChrxClient options and `AI_KEY` is correctly set in your `.env` file.

Warnings

breaking Version 2.0.0 introduces ChrxCommandBuilder, a new API for defining commands which significantly reduces boilerplate compared to discord.js SlashCommandBuilder. Existing v1.x command files using SlashCommandBuilder will need refactoring.
Fix: Migrate your command files to use `new ChrxCommandBuilder({...})` syntax as detailed in the v2.0.0 documentation. This involves defining `name`, `description`, `options`, `cooldown`, and the `run` method directly within the builder.
gotcha Correct Lavalink configuration is crucial for the music module. Common issues include incorrect host/port, mismatched passwords, or secure flag misconfiguration (e.g., using `secure: true` with a non-SSL port).
Fix: Ensure `LAVA_HOST`, `LAVA_PORT`, `LAVA_PASS` are correctly set in your `.env` file and match your Lavalink server's configuration. Use port 443 with `secure: true` for SSL/TLS connections, otherwise use 2333 (default) with `secure: false`.
gotcha The framework relies heavily on environment variables (e.g., BOT_TOKEN, LAVA_HOST, AI_KEY, DATABASE_URL). Incorrectly set or missing environment variables will lead to runtime errors or module failures.
Fix: Always use a `.env` file and `require('dotenv').config();` at the very top of your main bot file. Double-check all required environment variables are present and correctly formatted, especially API keys and URLs.
gotcha `discord.js` is a peer dependency, meaning it must be installed separately by the user alongside `chrxmaticc-framework`. Forgetting to install it will result in a 'Cannot find module' error.
Fix: Always install both packages: `npm install chrxmaticc-framework discord.js`.

Install

npm install chrxmaticc-framework npm
yarn add chrxmaticc-framework yarn
pnpm add chrxmaticc-framework pnpm

Imports

ChrxClient
wrong:
```
const { ChrxClient } = require('chrxmaticc-framework');
```
correct:
```
import { ChrxClient } from 'chrxmaticc-framework';
```
While CommonJS `require` is shown in v1.x documentation, ESM `import` is the modern and recommended approach for new projects, especially with Node.js v16+.
ChrxCommandBuilder
wrong:
```
const { ChrxCommandBuilder } = require('chrxmaticc-framework');
```
correct:
```
import { ChrxCommandBuilder } from 'chrxmaticc-framework';
```
Introduced in v2.0.0 to simplify command creation, replacing the need for explicit `SlashCommandBuilder` from `discord.js`. Ensure you are on v2.0.0 or higher to use this.

Quickstart

This setup initializes a ChrxClient instance with full capabilities, including Lavalink music, XP system, PostgreSQL database, and AI integration, all configured via environment variables.

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

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

  lavalink: {
    host: process.env.LAVA_HOST ?? 'localhost',
    port: parseInt(process.env.LAVA_PORT ?? '2333'),
    password: process.env.LAVA_PASS ?? 'youshallnotpass',
    secure: process.env.LAVA_SECURE === 'true',
  },

  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();

view raw JSON →