> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kazzle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Complete reference for kazzle.config.ts — the app manifest.

# 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

```typescript theme={"theme":"material-theme-darker"}
import { defineConfig } from '@kazzle/app';

export default defineConfig({
  components: [
    { name: 'My App', type: 'ui', path: '.' }
  ]
});
```

The `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 in `components[]`:

| 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 in `skills[]`:

| 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 `name` values must be unique within the app

## Template examples

### ai app

```typescript theme={"theme":"material-theme-darker"}
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

```typescript theme={"theme":"material-theme-darker"}
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

```typescript theme={"theme":"material-theme-darker"}
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' },
  ],
});
```