Skip to main content
CommandKit uses a commandkit.config.ts file at the root of your project to configure the framework. This file controls plugins, compiler options, build settings, and more.

​
Creating the config file

Create a commandkit.config.ts file in your project root:
commandkit.config.ts
import { defineConfig } from 'commandkit/config';

export default defineConfig({
  // Your configuration here
});
Use the defineConfig helper function for full TypeScript type checking and autocomplete.

​
Configuration options

​
Plugins

Add plugins to extend CommandKit functionality: 
import { defineConfig } from 'commandkit/config';
import { i18n } from '@commandkit/i18n';
import { cache } from '@commandkit/cache';
import { devtools } from '@commandkit/devtools';

export default defineConfig({
  plugins: [
    i18n(),
    cache(),
    devtools(),
  ],
});
​
plugins
CommandKitPlugin[]
Array of plugins to use. Can include both runtime and compiler plugins.
plugins: [
  i18n(),
  cache(),
  new CustomPlugin(),
]

​
Compiler options

Configure the build and compilation process:
​
compilerOptions
CommandKitCompilerOptions
Options for the CommandKit compiler.
compilerOptions: {
  macro: {
    development: false, // Enable macros in development
  },
  disableChunking: false, // Disable code splitting
}
​
compilerOptions.macro
object
Macro compiler configuration.
  • development (boolean): Enable macro function compilation in dev mode. Default: false
​
compilerOptions.disableChunking
boolean
Disable chunking of the output in production. Default: false
​
compilerOptions.tsdown
Partial<TsDownOptions>
Advanced: Configure tsdown compiler options. Only use if you know what you’re doing.

​
TypeScript options

Configure TypeScript behavior:
​
typescript
object
TypeScript configuration options.
typescript: {
  ignoreBuildErrors: false,
}
​
typescript.ignoreBuildErrors
boolean
Whether to ignore type checking during builds. Default: false
Only use this for debugging. Type errors should be fixed, not ignored.
​
typedCommands
boolean
Enable or disable typed commands. Default: true
typedCommands: true

​
Build options

​
distDir
string
The build output directory. Default: "dist"
distDir: 'build'
​
static
boolean
Generate static command handler data in production builds. Default: true
static: true
​
entrypoints
string[]
Additional entrypoints to compile.
entrypoints: [
  'src/utils/**/*.ts',
  'src/services/index.ts',
  '!src/utils/test/**',  // Exclude pattern
]
​
sourceMap
object
Source map generation settings.
sourceMap: {
  development: true,  // Enable in dev
  production: true,   // Enable in prod
}

​
Environment variables

​
env
Record<string, string>
Statically define environment variables.
env: {
  API_URL: 'https://api.example.com',
  VERSION: '1.0.0',
}

​
Command options

​
disablePrefixCommands
boolean
Disable prefix (message) commands. Default: false
disablePrefixCommands: true
​
disablePermissionsMiddleware
boolean
Disable the built-in permissions middleware. Default: false
disablePermissionsMiddleware: false
​
showUnknownPrefixCommandsWarning
boolean
Show warnings for unknown prefix commands in development. Default: true
showUnknownPrefixCommandsWarning: true

​
JSX options

​
jsxDefaultOptionalComponents
boolean
Make interaction components optional by default when using JSX. Default: true
jsxDefaultOptionalComponents: true

​
Anti-crash script

​
antiCrashScript
object
Configure the anti-crash script for handling uncaught errors.
antiCrashScript: {
  development: true,  // Enable in dev
  production: false,  // Disable in prod
}

​
Complete example

Here’s a complete configuration file with all common options:
commandkit.config.ts
import { defineConfig } from 'commandkit/config';
import { i18n } from '@commandkit/i18n';
import { devtools } from '@commandkit/devtools';
import { cache } from '@commandkit/cache';
import { ai } from '@commandkit/ai';
import { tasks, setDriver } from '@commandkit/tasks';
import { SQLiteDriver } from '@commandkit/tasks/sqlite';
import { workflow } from '@commandkit/workflow';

// Initialize task driver for development
if (process.env.NODE_ENV === 'development') {
  setDriver(new SQLiteDriver());
}

export default defineConfig({
  // Plugins
  plugins: [
    i18n({
      locales: ['en', 'es', 'fr'],
      defaultLocale: 'en',
    }),
    devtools(),
    cache(),
    ai(),
    tasks({
      initializeDefaultDriver: false,
    }),
    workflow(),
  ],
  
  // Compiler options
  compilerOptions: {
    macro: {
      development: false,
    },
    disableChunking: false,
  },
  
  // TypeScript
  typescript: {
    ignoreBuildErrors: false,
  },
  
  // Build
  distDir: 'dist',
  static: true,
  entrypoints: [
    'src/utils/**/*.ts',
  ],
  
  // Source maps
  sourceMap: {
    development: true,
    production: true,
  },
  
  // Environment variables
  env: {
    API_VERSION: '1.0.0',
  },
  
  // Commands
  typedCommands: true,
  disablePrefixCommands: false,
  disablePermissionsMiddleware: false,
  showUnknownPrefixCommandsWarning: true,
  
  // JSX
  jsxDefaultOptionalComponents: true,
  
  // Anti-crash
  antiCrashScript: {
    development: true,
    production: false,
  },
});

​
Environment-specific configuration

You can use environment variables to customize configuration:
commandkit.config.ts
import { defineConfig } from 'commandkit/config';

const isDev = process.env.NODE_ENV === 'development';
const isProd = process.env.NODE_ENV === 'production';

export default defineConfig({
  plugins: [
    // Only enable devtools in development
    ...(isDev ? [devtools()] : []),
  ],
  
  sourceMap: {
    development: true,
    production: isProd && process.env.ENABLE_SOURCEMAPS === 'true',
  },
  
  antiCrashScript: {
    development: true,
    production: false,
  },
});

​
Type-safe configuration

The defineConfig helper provides full TypeScript support: 
import { defineConfig } from 'commandkit/config';
import type { CommandKitConfig } from 'commandkit/config';

// Option 1: Use defineConfig (recommended)
export default defineConfig({
  // Full autocomplete and type checking
  distDir: 'build',
  typedCommands: true,
});

// Option 2: Explicit type annotation
const config: CommandKitConfig = {
  distDir: 'build',
  typedCommands: true,
};

export default defineConfig(config);

​
Configuration validation

CommandKit validates your configuration at startup. Invalid options will show helpful error messages: 
❌ Invalid configuration:
  - distDir must be a string
  - plugins must be an array
  - typedCommands must be a boolean

​
Advanced: Rolldown plugins

Add custom Rolldown plugins for advanced bundling: 
import { defineConfig } from 'commandkit/config';
import customRolldownPlugin from './plugins/rolldown-plugin';

export default defineConfig({
  rolldownPlugins: [
    customRolldownPlugin(),
  ],
});
Only use Rolldown plugins if you understand how they affect the build process.

​
Best practices

1

Use defineConfig

Always use the defineConfig helper for type safety and autocomplete.
2

Environment-specific settings

Use environment variables for environment-specific configuration.
3

Keep it simple

Start with minimal configuration and add options as needed.
4

Document custom options

If using advanced features, document why and how they’re used.
5

Version control

Commit your commandkit.config.ts but exclude .env files.

​
Configuration helpers

CommandKit provides helper functions:

​
noBuildOnly

Run code only in development (not during builds):
commandkit.config.ts
import { defineConfig, noBuildOnly } from 'commandkit/config';
import { setDriver } from '@commandkit/tasks';
import { SQLiteDriver } from '@commandkit/tasks/sqlite';

// Only run in dev, skip during production builds
noBuildOnly(() => {
  setDriver(new SQLiteDriver());
})();

export default defineConfig({
  // ...
});

​
Troubleshooting

Ensure commandkit.config.ts is in your project root and exported with export default.
Make sure you’re using the defineConfig helper and have the latest version of CommandKit.
Check that plugins are properly imported and added to the plugins array.
Run npx commandkit dev to see detailed error messages about your configuration.

​
Next steps

Commands

Learn about creating commands

Plugins

Explore available plugins

Build docs developers (and LLMs) love

Get started for freeTalk to us