> ## 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.

# Конфігурація

> Повний довідник kazzle.config.ts — маніфесту додатка.

# Конфігурація

Кожен додаток Kazzle має `kazzle.config.ts` у корені проекту. Цей файл визначає, що містить ваш додаток — компоненти, навички та метадані.

## Швидкий старт

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

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

Помічник `defineConfig` забезпечує автодоповнення та валідацію TypeScript. Типи походять з пакета `@kazzle/app`, включеного в кожен шаблон.

## Поля верхнього рівня

| Поле           | Тип                          | Обов'язкове | Опис                                                                                                                                                                                                    |
| -------------- | ---------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`         | `string`                     | ні          | Маркетингова назва, показана в каталозі додатків. Повертається до слага, якщо опущено.                                                                                                                  |
| `subtitle`     | `string`                     | ні          | Коротка однорядкова назва, показана під назвою додатка в каталозі (наприклад, "Control Mac apps from Kazzle"). Обов'язково для публікації — якщо опущено, публікація не вдасться.                       |
| `version`      | `string`                     | ні          | Встановлена автором мітка версії (наприклад, "1.2.0"). Тільки для відображення; зберігається при публікації та показується на клонах як версія, з якої було розгалужено.                                |
| `icon`         | `string`                     | ні          | Шлях до файлу значка додатка відносно кореня репозиторію (png, jpg, svg, webp, ico). Завантажується на CDN при публікації.                                                                              |
| `accentColor`  | `string`                     | ні          | Необов'язковий колір акценту бренду як шістнадцяткова строка (наприклад, "#3b82f6"). Тонує мікросхему значка додатка та деталь героя. Якщо опущено, акцент автоматично вибирається з значка.            |
| `kazzleAuth`   | `"optional"` \| `"required"` | ні          | Контроль ідентичності для поверхні запуску додатка — "optional" (ідентичність надається, якщо присутній користувач Kazzle) або "required" (повинен бути авторизований користувач Kazzle для перегляду). |
| `launchUrl`    | `string`                     | ні          | Буквальна абсолютна URL-адреса, відкрита всередині Kazzle при натисканні на додаток, використовується як є. Якщо опущено, поверхня запуску — це розгорнута URL-адреса попереду перегляду компонента UI. |
| `webhookUrl`   | `string`                     | ні          | Кінцева точка видавця, на яку Kazzle надсилає POST при app.installed / app.uninstalled (доставляє ключ встановлення).                                                                                   |
| `components`   | object\[]                    | ні          | Виконувані компоненти — інтерфейси користувача або фонові процеси                                                                                                                                       |
| `skills`       | object\[]                    | ні          | Визначення навичок ШІ — файли markdown, які ШІ читає для знань предметної області                                                                                                                       |
| `capabilities` | `object`                     | ні          | Необов'язкові функції інтеграції з робочим столом, такі як гарячі клавіші, сповіщення та присутність на панелі стану                                                                                    |

## Поля компонента

Кожен запис у `components[]`:

| Поле                   | Тип                      | Обов'язкове    | Опис                                                                                        |
| ---------------------- | ------------------------ | -------------- | ------------------------------------------------------------------------------------------- |
| `name`                 | `string`                 | так            | Унікальна назва компонента в межах додатка                                                  |
| `type`                 | `"ui"` \| `"process"`    | так            | Тип компонента — ui (макс. 1) або process                                                   |
| `path`                 | `string`                 | так            | Шлях входу в межах каталогу додатка                                                         |
| `runtime`              | object                   | ні             | Команди та необов'язкові переозначення env: `{ dev?, prod? }`                               |
| `runtime.dev.command`  | `string`                 | ні             | Команда для запуску dev-сервера (наприклад, `"bun run dev"`)                                |
| `runtime.dev.env`      | object                   | ні             | Переозначення env тільки для розробки. Повертається до компонента `env`.                    |
| `runtime.prod.command` | `string`                 | ні             | Команда для запуску в production (наприклад, `"bun run start"`)                             |
| `runtime.prod.build`   | `string`                 | ні             | Команда для збірки для production (наприклад, `"vite build"`)                               |
| `runtime.prod.env`     | object                   | ні             | Переозначення env тільки для production. Повертається до компонента `env`.                  |
| `schedule`             | `string`                 | ні             | Розклад Cron для компонентів процесу (наприклад, `"*/5 * * * *"`)                           |
| `trigger`              | `"webhook"` \| `"event"` | ні             | Режим тригера для компонентів процесу                                                       |
| `env`                  | object                   | ні             | Колекція секретів + середовище для впровадження змінних env                                 |
| `env.collection`       | `string`                 | так (якщо env) | Слаг колекції секретів                                                                      |
| `env.environment`      | `string`                 | так (якщо env) | Слаг середовища                                                                             |
| `env.include`          | `string[]`               | ні             | Впровадити тільки ці назви змінних env. Якщо опущено, впровадити все з колекції+середовища. |

## Поля навички

Кожен запис у `skills[]`:

| Поле   | Тип      | Обов'язкове | Опис                                           |
| ------ | -------- | ----------- | ---------------------------------------------- |
| `name` | `string` | так         | Назва навички                                  |
| `path` | `string` | так         | Шлях до файлу SKILL.md відносно кореня додатка |

## Обмеження

* **Макс. 1 компонент UI** на додаток
* Значення `name` компонента повинні бути унікальними в межах додатка

## Приклади шаблонів

### 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' },
  ],
});
```