How to Install Cordis: A Complete Guide to Setting Up the Discord Bot Framework

Install Cordis by adding @cordis/core to your Node.js project with npm install @cordis/core, then instantiate the Client class exported from packages/core/src/index.ts to initialize your Discord connection and plugin lifecycle.

Cordis is a modular, plugin-first framework for building scalable Discord bots with a type-safe API, maintained in the cordiverse/cordis repository. Learning how to install Cordis requires only Node.js 18+ and a Discord bot token to establish a robust, service-oriented bot architecture. The framework splits functionality into focused packages—@cordis/core houses the main Client and service container, while optional helpers like @cordis/create provide scaffolding utilities.

Prerequisites and Initial Setup

Before installing Cordis, ensure your environment meets the baseline requirements.

• Node.js 18 or higher (LTS recommended). Cordis uses modern JavaScript features and the NodeNext module resolution strategy.
• A Discord bot token. Generate this from the Discord Developer Portal by creating a new application and revealing the bot token under the "Bot" tab.

Create a fresh directory for your project and initialize npm:

mkdir my-cordis-bot && cd my-cordis-bot
npm init -y

Installing the Core Framework

The @cordis/core package contains everything required to start a bot, including the Client class, the service container, and the event system.

Install the core library:

npm install @cordis/core

This package exposes the primary entry point at packages/core/src/index.ts, which exports the Client class that manages Discord gateway connections and plugin lifecycles. The core also implements the service container pattern defined in packages/core/src/service.ts, allowing plugins to inject shared dependencies.

For basic usage, this is the only mandatory package. However, most developers also install the console logger implementation:

npm install @cordis/logger-console

Scaffolding a New Project with @cordis/create

While you can write a bot from scratch, the @cordis/create package automates boilerplate generation via a CLI.

Install the scaffolding tool as a development dependency:

npm install -D @cordis/create

Generate a starter project:

npx cordis init

This command executes the logic found in packages/create/src/bin.ts and packages/create/src/index.ts, generating:

• src/index.ts – Entry point that instantiates the Client and loads plugins.
• src/plugins/example.ts – A sample plugin demonstrating event handling.
• A pre-configured tsconfig.json with strict type checking.
• Build scripts in package.json.

The scaffolding automatically installs @cordis/core and @cordis/logger-console, so you can skip the manual installation steps above if you use this method.

Configuring Environment Variables

Cordis expects configuration through environment variables, particularly for sensitive tokens.

Create a .env file in the project root (ensure this is listed in .gitignore):

DISCORD_TOKEN=YOUR_BOT_TOKEN_HERE

The starter template generated by npx cordis init includes dotenv configuration that loads these variables before the Client initializes.

Starting the Bot

If you used the scaffold, start the bot with:

npm run build
npm run start

For a minimal setup without scaffolding, create src/index.ts:

import { Client } from '@cordis/core';
import 'dotenv/config';

const client = new Client({
  token: process.env.DISCORD_TOKEN!,
  intents: ['Guilds', 'GuildMessages'],
});

client.plugin({
  name: 'ping',
  onMessageCreate(event) {
    if (event.content === '!ping') {
      event.reply('Pong!');
    }
  },
});

client.start();

Compile and run:

npx tsc src/index.ts --outDir dist --module NodeNext --moduleResolution NodeNext --esModuleInterop
node dist/index.js

The Client class defined in packages/core/src/index.ts handles gateway identification, shard management, and emits events to loaded plugins.

Extending Functionality with Optional Packages

Cordis adopts a "pay for what you use" architecture. Add these packages as needed:

• @cordis/timer – Provides setInterval, setTimeout, and cron-like scheduling utilities. Install with npm install @cordis/timer and import scheduling functions from the package root.
• @cordis/hmr – Enables hot-module replacement during development for rapid iteration.
• @cordis/include – Handles configuration inclusion and external file loading.

For example, scheduling a recurring task with the timer package:

import { Timer } from '@cordis/timer';

client.plugin({
  name: 'reminder',
  start() {
    Timer.setInterval(() => {
      console.log('Periodic task executed');
    }, 60000);
  },
});

Understanding Key Source Files

Understanding the repository structure helps when debugging or extending the framework:

• packages/core/src/index.ts – Exports the Client constructor and primary types. This is the main entry point for the framework.
• packages/core/src/service.ts – Implements the service container used for dependency injection across plugins.
• packages/create/src/bin.ts – CLI entry point that parses arguments for cordis init and cordis dev commands.
• packages/create/src/index.ts – Contains the project generation logic, file templates, and dependency installation routines.
• packages/logger-console/src/index.ts – Default logger implementation used when no custom logger is provided.

These files demonstrate how Cordis separates concerns between connection management (core), developer tooling (create), and peripheral utilities (logger, timer).

Summary

• Install the framework with npm install @cordis/core to access the Client class and service container.
• Use npm install -D @cordis/create followed by npx cordis init to scaffold a TypeScript project with proper configuration.
• Store your Discord token in a .env file; the scaffold loads this automatically via dotenv.
• The Client instance in packages/core/src/index.ts manages the Discord gateway connection and plugin lifecycle.
• Extend functionality by installing utility packages like @cordis/timer for scheduling or @cordis/hmr for development hot-reloading.

Frequently Asked Questions

What Node.js version does Cordis require?

Cordis requires Node.js 18 or higher. The framework leverages modern Node.js APIs and the NodeNext module resolution strategy, which ensures compatibility with ES modules and top-level await patterns used throughout the codebase.

Is @cordis/create mandatory for using Cordis?

No, @cordis/create is optional. You can manually install @cordis/core, configure TypeScript, and instantiate the Client class yourself. However, the scaffolding tool automates repetitive setup tasks and generates a recommended project structure, making it the fastest way to start a new project according to the Cordis architecture.

Where does Cordis read the Discord token from?

Cordis reads the Discord token from the DISCORD_TOKEN environment variable. The scaffolded project includes dotenv/config at the top of src/index.ts, which automatically loads variables from a .env file in your project root. If not using the scaffold, manually load dotenv or set the environment variable before calling client.start().

How do I add scheduled tasks to my Cordis bot?

Install the @cordis/timer package with npm install @cordis/timer, then import the Timer utility in your plugin. Use Timer.setInterval() or Timer.setTimeout() within the plugin's start lifecycle hook to schedule recurring or delayed tasks. The timer implementation handles cleanup automatically when the bot shuts down.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}