Skip to main content

​
Configuration

Every Kazzle app has a kazzle.config.ts at the project root. This file defines what your app contains — components, skills, and metadata.

​
Quick start

import { defineConfig } from './kazzle.types';

export default defineConfig({
  components: [
    { name: 'My App', type: 'ui', path: '.' }
  ]
});
The defineConfig helper provides TypeScript autocompletion and validation. The types come from kazzle.types.ts, which is auto-generated and included in every template.

​
Top-level fields

FieldTypeRequiredDescription
iconstringnoPath to the app icon file relative to the repo root (png, jpg, svg, webp, ico). Uploaded to CDN on publish.
componentsobject[]noExecutable components — UI frontends or background processes
skillsobject[]noAI skill definitions — markdown files the AI reads for domain knowledge
capabilitiesobjectnoOptional desktop integration features such as hotkeys, notifications, and status bar presence

​
Component fields

Each entry in components[]:
FieldTypeRequiredDescription
namestringyesUnique component name within the app
type"ui" | "process"yesComponent type — ui (max 1) or process
pathstringyesEntry path within the app directory
runtimeobjectnoCommands: { dev?, build?, run? }
runtime.devstringnoCommand to start the dev server (e.g. "bun run dev")
runtime.buildstringnoCommand to build for production (e.g. "vite build")
runtime.runstringnoCommand to start in production (e.g. "bun run start")
schedulestringnoCron schedule for process components (e.g. "*/5 * * * *")
trigger"webhook" | "event"noTrigger mode for process components
envobjectnoSecret collection + environment for env var injection
env.collectionstringyes (if env)Secret collection slug
env.environmentstringyes (if env)Environment slug
env.includestring[]noOnly inject these env var names. If omitted, inject all from the collection+environment.

​
Skill fields

Each entry in skills[]:
FieldTypeRequiredDescription
namestringyesSkill name
pathstringyesPath to the SKILL.md file relative to the app root

​
Constraints

  • Max 1 UI component per app
  • Component name values must be unique within the app

​
Template examples

​
ui app

import { defineConfig } from './kazzle.types';

export default defineConfig({
  /** Path to the app icon relative to the repo root. Uploaded to CDN on publish. */
  icon: 'components/ui/public/favicon.svg',
  /** App components — each entry defines a deployable unit. Max 1 UI component. */
  components: [
    { name: 'My App', type: 'ui', path: './components/ui' },
  ],
});

​
process app

import { defineConfig } from './kazzle.types';

export default defineConfig({
  /** Path to the app icon relative to the repo root. Uploaded to CDN on publish. */
  icon: 'icon.svg',
  /** App components — each entry defines a deployable unit. */
  components: [
    {
      name: 'My App',
      type: 'process',
      path: './components/process/index.ts',
      runtime: { dev: 'bun run dev', run: 'bun run start' },
      // Persistent processes are long-running servers. The platform posts
      // triggers into the running server at each trigger's `path` with
      // `Authorization: Bearer ${KAZZLE_TRIGGER_SECRET}`. Customer code
      // validates the header before doing work.
      processMode: 'persistent',
      triggers: [
        // Example cron — uncomment and adjust. 5-field, minute resolution.
        // { name: 'hourly-sync', kind: 'schedule', schedule: '0 * * * *', path: '/cron/hourly-sync' },
        // Example webhook — POSTs to /webhooks/{spaceId}/{appId}/My App/incoming
        // { name: 'incoming', kind: 'webhook', path: '/webhook/incoming' },
      ],
    },
  ],
});

​
empty app

import { defineConfig } from './kazzle.types';

export default defineConfig({
  /** Path to the app icon relative to the repo root. Uploaded to CDN on publish. */
  icon: 'icon.svg',
  /** App components — each entry defines a deployable unit. */
  components: [],
});