Project Structure

How to organize .kern files and configure output structure.

Basic Layout

A typical KERN project has .kern source files in one directory and compiled output in another. The kern.config.ts file lives at the project root.

my-project/
  kern.config.ts          # Configuration (auto-loaded)
  package.json            # Dependencies (auto-detected)
  src/
    kern/                 # .kern source files
      landing.kern
      dashboard.kern
      settings.kern
      docs/
        overview.kern
        getting-started.kern
  app/                    # Generated output (Next.js example)
    landing/page.tsx
    dashboard/page.tsx
    settings/page.tsx
    docs/
      overview/page.tsx
      getting-started/page.tsx
  templates/              # Custom template definitions (optional)
    zustand-store.kern
    data-table.kern

Source to Output Mapping

The --outdir flag controls where generated files land. KERN preserves the relative directory structure from source to output.

# Compile kern/ → app/, preserving structure
kern dev kern/ --target=nextjs --outdir=app/

# Result:
#   kern/landing.kern      → app/landing/page.tsx
#   kern/docs/intro.kern   → app/docs/intro/page.tsx

If no --outdir is given, output is written relative to the source file using the output.outDir value from kern.config.ts (default: current directory).

Output Structure Modes

KERN supports four output structure modes for React-based targets. Set via structure in kern.config.ts or the --structure CLI flag.

flat (default)

One output file per .kern source. The simplest option and the default.

# Input:  dashboard.kern
# Output: dashboard/page.tsx (single file)

bulletproof

Feature-based folder structure. Splits a single .kern file into multiple files organized by concern.

# Input:  dashboard.kern
# Output:
#   dashboard/
#     index.tsx          # Entry point
#     hooks/             # Extracted hooks
#     components/        # Sub-components
#     types/             # TypeScript interfaces

atomic

Atomic Design hierarchy. Classifies generated code into standard atomic layers.

# Layers:
#   pages/         # Full page components
#   templates/     # Page templates / layouts
#   organisms/     # Complex composed components
#   molecules/     # Simple composed components
#   atoms/         # Primitive UI elements

kern

KERN-native structure with its own naming conventions.

# Layers:
#   surfaces/      # Top-level views (pages, screens)
#   blocks/        # Reusable UI blocks
#   signals/       # State and hooks
#   tokens/        # Design tokens and constants
#   models/        # Types and interfaces

Structure modes only apply to React targets (nextjs, tailwind, web). For Vue, Express, FastAPI, and other targets, output is always flat.

Configuration File

kern.config.ts is auto-loaded from the project root by every CLI command. It is the central place to set target, structure, templates, and other options.

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

const config: KernConfig = {
  target: 'nextjs',
  structure: 'flat',
  templates: ['./templates/'],
  output: {
    outDir: '.',
    sourceMaps: false,
  },
};

export default config;

Run kern scan to auto-generate a kern.config.ts based on your package.json dependencies.

Templates Directory

Custom template definitions live in a templates/ directory (or any path listed in config.templates). Templates extend the KERN language with project-specific node types.

templates/
  zustand-store.kern     # Zustand store template
  data-table.kern        # Data table template
  arrow-fn.kern          # Common templates (auto-generated)
  window-event.kern      # Common templates (auto-generated)

Run kern init-templates to auto-scaffold templates from your package.json. Supported libraries: Zustand, SWR, TanStack Query, XState, Jotai, Zod, tRPC.

Evolved Nodes

When using kern evolve, graduated node definitions are stored in .kern/evolved/ at the project root. These are loaded automatically by kern dev and kern transpile.

.kern/
  evolved/
    manifest.json        # Registry of evolved nodes
    async-data-view.ts   # Node definition
    modal-state.ts       # Node definition

Generated Files

All generated files include a header comment identifying the source:

// Generated by KERN — do not edit. Source: src/kern/dashboard.kern

Do not edit generated files directly — edit the .kern source and recompile.

Coverage Gap Reports

During compilation, KERN analyzes coverage gaps and writes reports to .kern-gaps/ in the project root. These show which parts of your .kern files could be improved. Disable with --no-gaps.

.kern-gaps/                # Auto-generated during kern dev

Monorepo Packages

KERN itself is organized as a monorepo with these packages:

  • @kernlang/core — Parser, codegen, types (the compiler engine)
  • @kernlang/cli — CLI tool (compile, dev, review, evolve)
  • @kernlang/react — Next.js, Tailwind, Web transpilers
  • @kernlang/vue — Vue 3 SFC, Nuxt 3 transpilers
  • @kernlang/native — React Native transpiler
  • @kernlang/express — Express backend + WebSocket transpiler
  • @kernlang/fastapi — FastAPI Python + WebSocket transpiler
  • @kernlang/terminal — ANSI terminal + Ink transpilers
  • @kernlang/review — 159 AST rules, taint tracking, concept rules
  • @kernlang/review-mcp — MCP server security scanner (12 rules)
  • @kernlang/evolve — Self-extending template system
  • @kernlang/metrics — Language coverage analysis
  • @kernlang/protocol — AI draft communication protocol
  • @kernlang/playground — Interactive compiler UI