Configuration
Every Kazzle app has akazzle.config.ts at the project root. This file defines what your app contains — components, skills, and metadata.
Quick start
import { defineConfig } from '@kazzle/app';
export default defineConfig({
components: [
{ name: 'My App', type: 'ui', path: '.' }
]
});
defineConfig helper provides TypeScript autocompletion and validation. The types come from the @kazzle/app package included in every template.
Top-level fields
| Field | Type | Required | Description |
|---|---|---|---|
name | string | no | Marketing display name shown in the app catalog. Falls back to the slug when omitted. |
subtitle | string | no | Short one-line tagline shown under the app name in the catalog (e.g. “Control Mac apps from Kazzle”). Required to publish — omit and publish fails. |
version | string | no | Author-set version label (e.g. “1.2.0”). Display-only; snapshotted on publish and shown on clones as the forked-from version. |
icon | string | no | Path to the app icon file relative to the repo root (png, jpg, svg, webp, ico). Uploaded to CDN on publish. |
accentColor | string | no | Optional brand accent color as a hex string (e.g. “#3b82f6”). Tints the app icon chip and detail hero. When omitted, the accent is auto-sampled from the icon. |
kazzleAuth | "optional" | "required" | no | Identity gating for the app launch surface — “optional” (identity provided if a Kazzle user is present) or “required” (must be a logged-in Kazzle user to view). |
launchUrl | string | no | Literal absolute URL opened inside Kazzle when the app is clicked, used verbatim. When omitted, the launch surface is the UI component’s deployed preview URL. |
webhookUrl | string | no | Publisher endpoint Kazzle POSTs on app.installed / app.uninstalled (delivers the install key). |
components | object[] | no | Executable components — UI frontends or background processes |
skills | object[] | no | AI skill definitions — markdown files the AI reads for domain knowledge |
capabilities | object | no | Optional desktop integration features such as hotkeys, notifications, and status bar presence |
Component fields
Each entry incomponents[]:
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | Unique component name within the app |
type | "ui" | "process" | yes | Component type — ui (max 1) or process |
path | string | yes | Entry path within the app directory |
runtime | object | no | Commands and optional env overrides: { dev?, prod? } |
runtime.dev.command | string | no | Command to start the dev server (e.g. "bun run dev") |
runtime.dev.env | object | no | Dev-only env override. Falls back to component env. |
runtime.prod.command | string | no | Command to start in production (e.g. "bun run start") |
runtime.prod.build | string | no | Command to build for production (e.g. "vite build") |
runtime.prod.env | object | no | Production-only env override. Falls back to component env. |
schedule | string | no | Cron schedule for process components (e.g. "*/5 * * * *") |
trigger | "webhook" | "event" | no | Trigger mode for process components |
env | object | no | Secret collection + environment for env var injection |
env.collection | string | yes (if env) | Secret collection slug |
env.environment | string | yes (if env) | Environment slug |
env.include | string[] | no | Only inject these env var names. If omitted, inject all from the collection+environment. |
Skill fields
Each entry inskills[]:
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | Skill name |
path | string | yes | Path to the SKILL.md file relative to the app root |
Constraints
- Max 1 UI component per app
- Component
namevalues must be unique within the app
Template examples
ai app
import { defineConfig } from '@kazzle/app';
export default defineConfig({
/** One-line catalog tagline. Required to publish. */
subtitle: 'My App',
icon: 'components/ui/public/favicon.svg',
components: [
{ name: 'ui', type: 'ui', path: './components/ui' },
{ name: 'server', type: 'process', path: './components/server/index.ts', runtime: { dev: { command: 'bun run dev' }, prod: { command: 'bun run start' } } },
],
});
ui db app
import { defineConfig } from '@kazzle/app';
export default defineConfig({
/** One-line catalog tagline. Required to publish. */
subtitle: 'My App',
icon: 'components/ui/public/favicon.svg',
components: [
{ name: 'ui', type: 'ui', path: './components/ui' },
{ name: 'server', type: 'process', path: './components/server/index.ts', runtime: { dev: { command: 'bun run dev' }, prod: { command: 'bun run start' } } },
],
});
ui app
import { defineConfig } from '@kazzle/app';
export default defineConfig({
/** One-line catalog tagline. Required to publish. */
subtitle: 'My App',
/** 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' },
],
});