구성
모든 Kazzle 앱은 프로젝트 루트에kazzle.config.ts를 가집니다. 이 파일은 앱에 포함된 내용(컴포넌트, 스킬, 메타데이터)을 정의합니다.
빠른 시작
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
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
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
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' },
],
});