> ## 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`                     | 아니오 | 카탈로그의 앱 이름 아래에 표시되는 짧은 한 줄 태그라인입니다(예: "Kazzle에서 Mac 앱 제어"). 게시하려면 필수입니다 — 생략하면 게시가 실패합니다.             |
| `version`      | `string`                     | 아니오 | 작성자가 설정한 버전 레이블입니다(예: "1.2.0"). 표시 전용이며, 게시 시 스냅샷되고 클론에서 포크된 버전으로 표시됩니다.                              |
| `icon`         | `string`                     | 아니오 | 리포지토리 루트를 기준으로 한 앱 아이콘 파일 경로입니다(png, jpg, svg, webp, ico). 게시 시 CDN에 업로드됩니다.                          |
| `accentColor`  | `string`                     | 아니오 | 16진수 문자열로 된 선택적 브랜드 강조 색상입니다(예: "#3b82f6"). 앱 아이콘 칩과 상세 히어로에 색상을 입힙니다. 생략하면 강조 색상이 아이콘에서 자동으로 샘플링됩니다. |
| `kazzleAuth`   | `"optional"` \| `"required"` | 아니오 | 앱 실행 화면의 ID 게이팅입니다 — "optional"(Kazzle 사용자가 있으면 ID 제공) 또는 "required"(로그인한 Kazzle 사용자만 볼 수 있음).        |
| `launchUrl`    | `string`                     | 아니오 | 앱을 클릭할 때 Kazzle 내에서 열리는 리터럴 절대 URL이며, 그대로 사용됩니다. 생략하면 실행 화면은 UI 컴포넌트의 배포된 미리보기 URL입니다.                |
| `webhookUrl`   | `string`                     | 아니오 | Kazzle이 app.installed / app.uninstalled에서 POST하는 게시자 엔드포인트입니다(설치 키를 전달함).                             |
| `components`   | object\[]                    | 아니오 | 실행 가능한 컴포넌트 — UI 프론트엔드 또는 백그라운드 프로세스                                                                  |
| `skills`       | object\[]                    | 아니오 | AI 스킬 정의 — AI가 도메인 지식을 위해 읽는 마크다운 파일                                                                  |
| `capabilities` | `object`                     | 아니오 | 핫키, 알림, 상태 표시줄 표시 등의 선택적 데스크톱 통합 기능                                                                   |

## 컴포넌트 필드

`components[]`의 각 항목:

| 필드                     | 타입                       | 필수         | 설명                                            |
| ---------------------- | ------------------------ | ---------- | --------------------------------------------- |
| `name`                 | `string`                 | 예          | 앱 내에서 고유한 컴포넌트 이름                             |
| `type`                 | `"ui"` \| `"process"`    | 예          | 컴포넌트 타입 — ui(최대 1개) 또는 process                |
| `path`                 | `string`                 | 예          | 앱 디렉토리 내의 진입점 경로                              |
| `runtime`              | object                   | 아니오        | 명령 및 선택적 env 재정의: `{ dev?, prod? }`           |
| `runtime.dev.command`  | `string`                 | 아니오        | 개발 서버를 시작하는 명령입니다(예: `"bun run dev"`)         |
| `runtime.dev.env`      | object                   | 아니오        | 개발 전용 env 재정의입니다. 컴포넌트 `env`로 대체됩니다.          |
| `runtime.prod.command` | `string`                 | 아니오        | 프로덕션에서 시작하는 명령입니다(예: `"bun run start"`)       |
| `runtime.prod.build`   | `string`                 | 아니오        | 프로덕션용으로 빌드하는 명령입니다(예: `"vite build"`)         |
| `runtime.prod.env`     | object                   | 아니오        | 프로덕션 전용 env 재정의입니다. 컴포넌트 `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({
  /** 한 줄 카탈로그 태그라인입니다. 게시하려면 필수입니다. */
  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({
  /** 한 줄 카탈로그 태그라인입니다. 게시하려면 필수입니다. */
  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({
  /** 한 줄 카탈로그 태그라인입니다. 게시하려면 필수입니다. */
  subtitle: 'My App',
  /** 리포지토리 루트를 기준으로 한 앱 아이콘 경로입니다. 게시 시 CDN에 업로드됩니다. */
  icon: 'components/ui/public/favicon.svg',
  /** 앱 컴포넌트 — 각 항목은 배포 가능한 단위를 정의합니다. 최대 1개의 UI 컴포넌트입니다. */
  components: [
    { name: 'My App', type: 'ui', path: './components/ui' },
  ],
});
```