Migrating from CommandKit v0

This comprehensive guide will walk you through migrating your Discord bot from CommandKit v0 to v1. CommandKit v1 introduces significant architectural improvements, including a framework-based approach with enhanced developer experience features.

info

This guide uses TypeScript examples, but all concepts apply to JavaScript projects as well. Simply use the corresponding JavaScript file extensions (e.g., app.js, commandkit.config.js).

warning

Minimum Requirements: CommandKit v1 requires Node.js version 22 or higher. Please ensure your environment meets this requirement before proceeding.

warning

Migration Focus: This guide specifically covers converting existing v0 code to v1. For information about new v1 features and capabilities, please refer to the rest of the documentation after completing your migration.

Updating CommandKit

Begin your migration by updating to the latest version of CommandKit:

npm

npm install commandkit@dev

Yarn

yarn add commandkit@dev

pnpm

pnpm add commandkit@dev

Bun

bun add commandkit@dev

This command will install CommandKit v1 and update your package.json with the latest version.

Project Structure Migration

CommandKit v1 adopts a framework-based approach with a structured app directory that serves as the primary location for your bot's functionality. This new structure provides better organization and enables advanced features like automatic route discovery.

v1 (New Structure) ✅

.
├── src/
│   ├── app/
│   │   ├── commands/
│   │   │   └── ping.ts
│   │   └── events/
│   │       └── ready/
│   │           └── log.ts
│   └── app.ts
├── .env
├── commandkit.config.ts
├── package.json
└── tsconfig.json

v0 (Legacy Structure) ❌

.
├── src/
│   ├── commands/
│   │   └── ping.ts
│   ├── events/
│   │   └── ready/
│   │       └── log.ts
│   └── index.ts
├── .env
├── commandkit.config.mjs
├── package.json
└── tsconfig.json

Configuration File Updates

CommandKit v1 significantly simplifies configuration by automatically detecting your project structure and entry points. The framework now supports a standardized set of configuration file names for consistency.

Supported Configuration Files:

• commandkit.config.js
• commandkit.config.mjs
• commandkit.config.cjs
• commandkit.config.ts

v1 (Simplified Config) ✅

commandkit.config.ts

import { defineConfig } from 'commandkit';

export default defineConfig({
  // Configuration is now optional for most use cases
  // CommandKit automatically detects your app structure
});

v0 (Manual Config) ❌

commandkit.config.mjs

import { defineConfig } from 'commandkit';

export default defineConfig({
  src: 'src',
  main: 'index.mjs',
  // Manual configuration was required
});

info

The CommandKit CLI commands (commandkit dev, commandkit build, commandkit start) continue to work seamlessly with the new configuration system.

Entry Point Transformation

CommandKit v1 introduces a dramatically simplified entry point system. Instead of manually managing the CommandKit instance, bot login, and path configurations, you now simply export a configured Discord.js client.

v1 (Streamlined Entry) ✅

src/app.ts

import { Client } from 'discord.js';

const client = new Client({
  intents: [
    'Guilds',
    'GuildMessages',
    'MessageContent',
  ],
});

// Optional: Override the default token environment variable
client.token = process.env.CUSTOM_TOKEN_VAR;

export default client; // CommandKit handles the rest automatically

v0 (Manual Setup) ❌

src/index.ts

import { Client, GatewayIntentBits } from 'discord.js';
import { CommandKit } from 'commandkit';
import path from 'path';

const client = new Client({
  intents: [
    'Guilds',
    'GuildMessages',
    'MessageContent',
  ],
});

new CommandKit({
  client,
  commandsPath: path.join(__dirname, 'commands'),
  eventsPath: path.join(__dirname, 'events'),
  validationsPath: path.join(__dirname, 'validations'),
  skipBuiltInValidations: true,
  bulkRegister: true,
});

client.login('YOUR_TOKEN_HERE');

Command File Structure

CommandKit v1 modernizes the command API with more intuitive naming and cleaner type definitions. The new structure separates command metadata from execution logic more clearly, while introducing room for new APIs such as message (legacy) commands.

v1 (Modern API) ✅

src/app/commands/ping.ts

import type { CommandData, ChatInputCommandContext } from 'commandkit';

export const command: CommandData = {
  name: 'ping',
  description: 'Pong!',
};

export function chatInput({ interaction }: ChatInputCommandContext) {
  interaction.reply('Pong!');
}

v0 (Legacy API) ❌

src/commands/ping.ts

import type { CommandData, SlashCommandProps } from 'commandkit';

export const data: CommandData = {
  name: 'ping',
  description: 'Pong!',
};

export function run({ interaction }: SlashCommandProps) {
  interaction.reply('Pong!');
}

Middleware System (Formerly Validations)

CommandKit v1 renames and enhances the validation system to "middleware," which better reflects its purpose and capabilities. Middleware can now run in various contexts and provides more granular control over command execution.

v1 (Middleware System) ✅

src/app/commands/+global-middleware.ts

import type { MiddlewareContext } from 'commandkit';

export function beforeExecute(ctx: MiddlewareContext) {
  // Example: Block command execution based on conditions
  if (ctx.interaction.isRepliable()) {
    ctx.interaction.reply('Access denied: Command execution blocked.');
  }

  ctx.cancel(); // Prevents command execution
}

v0 (Validation System) ❌

src/validations/block-execution.ts

import type { ValidationProps } from 'commandkit';

export default function (ctx: ValidationProps) {
  if (ctx.interaction.isRepliable()) {
    ctx.interaction.reply('You are blocked from running the command!');
  }
  return true; // command will not be executed
};

For comprehensive middleware documentation, including command-specific and conditional middleware, refer to the middleware documentation.

Development Environment

CommandKit v1 introduces advanced development features that require using the CommandKit CLI. The development server provides Hot Module Replacement (HMR) for rapid iteration and supports modern features like JSX components.

Starting Development Server

npm

npx commandkit dev

Yarn

yarn dlx commandkit dev

pnpm

pnpm dlx commandkit dev

Bun

bun x commandkit dev

warning

Generated Files: The development server creates a .commandkit directory for temporary files. Add this to your .gitignore to prevent committing generated files:

.commandkit/

Production Deployment

Building Your Application

npm

npx commandkit build

Yarn

yarn dlx commandkit build

pnpm

pnpm dlx commandkit build

Bun

bun x commandkit build

Starting Production Application

Option 1 - Using CommandKit CLI (Recommended):

npm

npx commandkit start

Yarn

yarn dlx commandkit start

pnpm

pnpm dlx commandkit start

Bun

bun x commandkit start

Option 2 - Direct Node.js execution:

node dist/index.js

warning

Generated Build Files: The build process creates a dist directory. Add this to your .gitignore to prevent committing build artifacts:

dist/