> ## 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\[]                    | нет         | Исполняемые компоненты — фронтенды UI или фоновые процессы                                                                                                                                                                         |
| `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.collection`       | `string`                 | да (если env) | Слаг коллекции секретов                                                                                      |
| `env.environment`      | `string`                 | да (если env) | Слаг окружения                                                                                               |
| `env.include`          | `string[]`               | нет           | Инъектировать только эти имена переменных окружения. Если опущено, инъектировать все из коллекции+окружения. |

## Поля навыка

Каждая запись в `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' },
  ],
});
```