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

> Install Cordis easily into your Node.js project with npm install @cordis/core. Follow our guide to set up the Discord bot framework and connect your application.

- Repository: [Cordiverse/cordis](https://github.com/cordiverse/cordis)
- Tags: how-to-guide
- Published: 2026-09-13

---

**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`](https://github.com/cordiverse/cordis/blob/main/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](https://discord.com/developers/applications) by creating a new application and revealing the bot token under the "Bot" tab.

Create a fresh directory for your project and initialize npm:

```bash
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:

```bash
npm install @cordis/core

```

This package exposes the primary entry point at [`packages/core/src/index.ts`](https://github.com/cordiverse/cordis/blob/main/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`](https://github.com/cordiverse/cordis/blob/main/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:

```bash
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:

```bash
npm install -D @cordis/create

```

Generate a starter project:

```bash
npx cordis init

```

This command executes the logic found in [`packages/create/src/bin.ts`](https://github.com/cordiverse/cordis/blob/main/packages/create/src/bin.ts) and [`packages/create/src/index.ts`](https://github.com/cordiverse/cordis/blob/main/packages/create/src/index.ts), generating:

- [`src/index.ts`](https://github.com/cordiverse/cordis/blob/main/src/index.ts) – Entry point that instantiates the `Client` and loads plugins.
- [`src/plugins/example.ts`](https://github.com/cordiverse/cordis/blob/main/src/plugins/example.ts) – A sample plugin demonstrating event handling.
- A pre-configured [`tsconfig.json`](https://github.com/cordiverse/cordis/blob/main/tsconfig.json) with strict type checking.
- Build scripts in [`package.json`](https://github.com/cordiverse/cordis/blob/main/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`):

```dotenv
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:

```bash
npm run build
npm run start

```

For a minimal setup without scaffolding, create [`src/index.ts`](https://github.com/cordiverse/cordis/blob/main/src/index.ts):

```typescript
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:

```bash
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`](https://github.com/cordiverse/cordis/blob/main/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:

```typescript
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`](https://github.com/cordiverse/cordis/blob/main/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`](https://github.com/cordiverse/cordis/blob/main/packages/core/src/service.ts)** – Implements the service container used for dependency injection across plugins.
- **[`packages/create/src/bin.ts`](https://github.com/cordiverse/cordis/blob/main/packages/create/src/bin.ts)** – CLI entry point that parses arguments for `cordis init` and `cordis dev` commands.
- **[`packages/create/src/index.ts`](https://github.com/cordiverse/cordis/blob/main/packages/create/src/index.ts)** – Contains the project generation logic, file templates, and dependency installation routines.
- **[`packages/logger-console/src/index.ts`](https://github.com/cordiverse/cordis/blob/main/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`](https://github.com/cordiverse/cordis/blob/main/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`](https://github.com/cordiverse/cordis/blob/main/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.