CLI Configuration

All kern.config.ts options with defaults, verified from source.

Overview

KERN reads kern.config.ts from your project root automatically. Every option is optional — sensible defaults apply when omitted. The file must export a default config object typed as KernConfig.

import type { KernConfig } from 'kern-lang';

const config: KernConfig = {
  target: 'nextjs',
  // ... options
};

export default config;

target

The compilation target framework. Default: nextjs.

Valid values: nextjs, tailwind, web, native, express, cli, terminal, ink, vue, nuxt, fastapi.

If no kern.config.ts exists, KERN auto-detects the target from package.json dependencies. Detection priority: next → nuxt → vue → react-native → express/fastify/koa/hono → tailwindcss+react → react. CLI flag --target overrides this value.

structure

Output file structure for React-based targets. Default: flat.

Valid values: flat, bulletproof, atomic, kern.

  • flat — Single output file per .kern source (default)
  • bulletproof — Feature-based folder structure
  • atomic — Atomic Design hierarchy (pages/templates/organisms/molecules/atoms)
  • kern — KERN-native structure (surfaces/blocks/signals/tokens/models)

Only applies to React targets (nextjs, tailwind, web). CLI flag --structure overrides this value.

output

Controls where generated files are written.

output: {
  outDir: '.',          // Relative to project root. Default: '.'
  sourceMaps: false,    // Generate .map files. Default: false
}

i18n

Internationalization settings. When enabled, text values are wrapped in translation function calls.

i18n: {
  enabled: true,              // Default: true
  hookName: 'useTranslation', // Default: 'useTranslation'
  importPath: 'react-i18next' // Default: 'react-i18next'
}

Set enabled: false to output raw strings without t() wrapping.

components

Controls component import paths in generated output.

components: {
  uiLibrary: '@components/ui',  // Default: '@components/ui'
  componentRoot: '@/components', // Default: '@/components'
  mappings: {}                   // Custom overrides: { ComponentName: 'import/path' }
}

Use mappings to override specific component import paths. Example: { SettingsSection: '@features/settings/components/layout/SettingsSection' }.

colors

Maps hex color values to Tailwind CSS class names. KERN ships with a default palette (Zinc scale + common accents). Your custom entries merge with the defaults.

colors: {
  '#09090b': 'zinc-950',
  '#18181b': 'zinc-900',
  '#f97316': 'orange-500',
  // Your project colors:
  '#6366f1': 'indigo-500',
}

templates

Paths to directories or files containing .kern template definitions. Templates are loaded before compilation and available as custom node types.

templates: ['./templates/']

Run kern init-templates to auto-scaffold templates from your package.json dependencies.

frameworkVersions

Explicit framework version overrides. Usually auto-detected from package.json — you only need this if auto-detection fails.

frameworkVersions: {
  tailwind: '4.0',
  nextjs: '15.0',
}

express

Settings for the Express backend target.

express: {
  security: 'strict',    // 'strict' | 'relaxed'. Default: 'strict'
  helmet: false,          // Add helmet middleware. Default: false
  compression: false,     // Add compression middleware. Default: false
}

fastapi

Settings for the FastAPI Python target.

fastapi: {
  security: 'strict',    // 'strict' | 'relaxed'. Default: 'strict'
  cors: false,            // Add CORS middleware. Default: false
  gzip: false,            // Add GZip middleware. Default: false
  uvicorn: {
    host: '0.0.0.0',     // Default: '0.0.0.0'
    reload: false,        // Auto-reload on changes. Default: false
    workers: undefined,   // Number of workers (optional)
  }
}

review

Settings for kern review static analysis.

review: {
  showConfidence: false,  // Show confidence scores. Default: false
  minConfidence: 0,       // Min confidence for enforcement. Default: 0
  maxComplexity: 15,      // Max cognitive complexity. Default: 15
  disabledRules: [],      // Rule IDs to disable project-wide
}

Example: disabledRules: ['floating-promise', 'empty-catch'] silences those rules across the entire project.

Full Example

A complete kern.config.ts with all sections:

import type { KernConfig } from 'kern-lang';

const config: KernConfig = {
  target: 'nextjs',
  structure: 'flat',
  templates: ['./templates/'],

  i18n: {
    enabled: true,
    hookName: 'useTranslation',
    importPath: 'react-i18next',
  },

  components: {
    uiLibrary: '@components/ui',
    componentRoot: '@/components',
    mappings: {},
  },

  colors: {
    '#6366f1': 'indigo-500',
  },

  output: {
    outDir: 'src/generated',
    sourceMaps: true,
  },

  express: {
    security: 'strict',
    helmet: true,
    compression: true,
  },

  fastapi: {
    security: 'strict',
    cors: true,
    gzip: true,
    uvicorn: { host: '0.0.0.0', reload: true },
  },

  review: {
    showConfidence: true,
    maxComplexity: 15,
    disabledRules: [],
  },
};

export default config;

Config Loading Order

KERN resolves configuration in this order. Later steps override earlier ones.

  1. Built-in defaults (DEFAULT_CONFIG)
  2. kern.config.ts from project root (merged with defaults)
  3. Auto-detected framework versions from package.json
  4. CLI flags (--target, --structure, --outdir)

If kern.config.ts is missing and no CLI flags are passed, KERN auto-detects the target from package.json. If no framework is detected, it defaults to nextjs.