cordium

🔥 Cordium

A simple but powerful Discord framework

✨ Features

• 🔌 Plugin System - Modular, extensible plugin architecture
• ⚡ Event Handling - Sophisticated event management with auto-discovery
• 🎯 Command Handling - Support for both slash commands and message commands

🚀 Quick Start

Installation

# Using npm
npm install cordium discord.js

# Using pnpm
pnpm add cordium discord.js

# Using yarn
yarn add cordium discord.js

Basic Setup

import { Client, GatewayIntentBits } from "discord.js";
import { Core } from "cordium";

const client = new Client({
    intents: [
        GatewayIntentBits.Guilds,
        GatewayIntentBits.GuildMessages,
        GatewayIntentBits.MessageContent,
        GatewayIntentBits.GuildMembers,
        GatewayIntentBits.GuildVoiceStates,
    ],
});

const core = new Core(client, {
    baseDirectory: __dirname,
    prefix: ["!", "?"],
    owners: ["YOUR_USER_ID"],
    autoRegisterCommands: true,
    // applicationCommandGuildId: "GUILD_ID", // optional
    isPluginEnabled: (pluginName: string, guildId: string) => boolean | Promise<boolean>,
    beforeCommandRun: (context: Core.Context) => boolean | Promise<boolean>,
});

await core.init();

client.login("YOUR_BOT_TOKEN");

📁 Project Structure

your-project/
├── plugins/
│   ├── moderation/
│   │   ├── moderation.plugin.ts
│   │   ├── commands/
│   │   │   ├── ban.command.ts
│   │   │   └── kick.command.ts
│   │   └── events/
│   │       └── clientReady.event.ts
│   ├── utility/
│   │   ├── plugin.ts
│   │   ├── commands/
│   │   │   ├── ping.command.ts
│   │   │   └── uptime.command.ts
│   │   └── events/
│   │       └── messageCreate.event.ts
├── index.ts
└── package.json

🔌 Creating Plugins

Plugin Structure

// plugins/example/plugin.ts
import { Plugin } from "cordium";

export class ModerationPlugin extends Plugin {
    constructor(buildOptions: Plugin.BuildOptions) {
        super(buildOptions, {
            name: "Moderation",
        });
    }
}

Commands

// plugins/example/commands/hello.command.ts
import { Command } from "cordium";
import {
    ChatInputCommandInteraction,
    Message,
    ContextMenuCommandInteraction,
    ApplicationCommandType,
} from "discord.js";

export class HelloCommand extends Command {
    constructor(buildOptions: Command.BuildOptions) {
        super(buildOptions, {
            name: "hello",
            description: "Says hello to the user",
            aliases: ["hi", "hey"],
        });
    }

    // Build application commands (slash / context menu) using the provided CommandBuilder
    buildApplicationCommands(builder: Command.Builder) {
        return builder
            .addSlashBuilder((slash) =>
                slash
                    .setName(this.name)
                    .setDescription("Says hello!")
                    .addUserOption((option) =>
                        option.setName("user").setDescription("User to greet").setRequired(false)
                    )
            )
            .addContextMenuBuilder((context) => context.setName("User Info").setType(ApplicationCommandType.User));
    }

    // Handle slash command
    async onChatInput(interaction: ChatInputCommandInteraction) {
        const user = interaction.options.getUser("user") || interaction.user;
        await interaction.reply(`Hello, ${user}! 👋`);
    }

    // Handle message command
    async onMessage(message: Message, ...args: any[]) {
        const mention = message.mentions.users.first() || message.author;
        await message.reply(`Hello, ${mention}! 👋`);
    }

    // Handle context menu command
    async onContextMenu(interaction: ContextMenuCommandInteraction) {
        const user = interaction.targetUser;
        await interaction.reply(`User: ${user.tag}`);
    }
}

Events

// plugins/example/events/ready.event.ts
import { Event, container } from "cordium";
import { Events } from "discord.js";

export class ClientReadyEvent extends Event {
    constructor(buildOptions: Event.BuildOptions) {
        super(buildOptions, {
            name: Events.ClientReady,
            once: true,
        });
    }

    async run() {
        console.log(`🚀 Bot is ready! Logged in as ${container.core.client.user?.tag}`);
    }
}

🎯 Advanced Features

Custom Stores

import { container } from "cordium";

// Access the global container
container.store.set("customData", { foo: "bar" });
const data = container.store.get("customData");

// Access plugin/event/command stores
const allPlugins = Array.from(container.pluginStore);
const allEvents = Array.from(container.eventStore);
const allCommands = Array.from(container.commandStore);

Manual Plugin Management

// Load specific plugin
await core.handler.loadPlugin("./plugins/moderation/plugin.js");

// Unload all plugins
await core.handler.unloadPlugins();

// Register commands to specific guild
await core.handler.registerCommands("GUILD_ID");

🛠️ Development

# Clone the repository
git clone https://github.com/Kevlid/Cordium.git

# Install dependencies
pnpm install

# Build the framework
pnpm build

# Watch for changes during development
pnpm dev

🤝 Contributing

• Fork the repository
• Create your feature branch (git checkout -b feature/amazing-feature)
• Commit your changes (git commit -m 'Add amazing feature')
• Push to the branch (git push origin feature/amazing-feature)
• Open a Pull Request

🔗 Links

• Documentation (At some point probably)
• NPM Package
• GitHub Repository

Built with ❤️ by Kevlid

⭐ Star this repo if you find it useful!