메인 콘텐츠로 건너뛰기

구성

모든 Kazzle 앱은 프로젝트 루트에 kazzle.config.ts를 가지고 있습니다. 이 파일은 앱에 포함된 내용(컴포넌트, 스킬, 메타데이터)을 정의합니다.

빠른 시작

import { defineConfig } from './kazzle.types';

export default defineConfig({
  components: [
    { name: 'My App', type: 'ui', path: '.' }
  ]
});
defineConfig 헬퍼는 TypeScript 자동완성과 유효성 검사를 제공합니다. 타입은 kazzle.types.ts에서 가져오며, 이는 자동 생성되고 모든 템플릿에 포함됩니다.

최상위 필드

필드타입필수설명
iconstring아니오리포지토리 루트 기준 앱 아이콘 파일 경로(png, jpg, svg, webp, ico). 게시 시 CDN에 업로드됩니다.
componentsobject[]아니오실행 가능한 컴포넌트 — UI 프론트엔드 또는 백그라운드 프로세스
skillsobject[]아니오AI 스킬 정의 — AI가 도메인 지식을 위해 읽는 마크다운 파일
capabilitiesobject아니오핫키, 알림, 상태 표시줄 표시 등의 선택적 데스크톱 통합 기능

컴포넌트 필드

components[]의 각 항목:
필드타입필수설명
namestring앱 내 고유한 컴포넌트 이름
type"ui" | "process"컴포넌트 타입 — ui(최대 1개) 또는 process
pathstring앱 디렉토리 내 진입점 경로
runtimeobject아니오명령어: { dev?, build?, run? }
runtime.devstring아니오개발 서버 시작 명령어(예: "bun run dev")
runtime.buildstring아니오프로덕션용 빌드 명령어(예: "vite build")
runtime.runstring아니오프로덕션 시작 명령어(예: "bun run start")
schedulestring아니오프로세스 컴포넌트용 Cron 스케줄(예: "*/5 * * * *")
trigger"webhook" | "event"아니오프로세스 컴포넌트용 트리거 모드
envobject아니오환경 변수 주입을 위한 시크릿 컬렉션 + 환경
env.collectionstring예(env인 경우)시크릿 컬렉션 슬러그
env.environmentstring예(env인 경우)환경 슬러그
env.includestring[]아니오이 환경 변수 이름만 주입합니다. 생략하면 컬렉션+환경의 모든 항목을 주입합니다.

스킬 필드

skills[]의 각 항목:
필드타입필수설명
namestring스킬 이름
pathstring앱 루트 기준 SKILL.md 파일 경로

제약 사항

  • 앱당 최대 1개 UI 컴포넌트
  • 컴포넌트 name 값은 앱 내에서 고유해야 합니다.

템플릿 예제

ui 앱

import { defineConfig } from './kazzle.types';

export default defineConfig({
  /** 리포지토리 루트 기준 앱 아이콘 경로. 게시 시 CDN에 업로드됩니다. */
  icon: 'components/ui/public/favicon.svg',
  /** 앱 컴포넌트 — 각 항목은 배포 가능한 단위를 정의합니다. 최대 1개 UI 컴포넌트. */
  components: [
    { name: 'My App', type: 'ui', path: './components/ui' },
  ],
});

process 앱

import { defineConfig } from './kazzle.types';

export default defineConfig({
  /** 리포지토리 루트 기준 앱 아이콘 경로. 게시 시 CDN에 업로드됩니다. */
  icon: 'icon.svg',
  /** 앱 컴포넌트 — 각 항목은 배포 가능한 단위를 정의합니다. */
  components: [
    {
      name: 'My App',
      type: 'process',
      path: './components/process/index.ts',
      runtime: { dev: 'bun run dev', run: 'bun run start' },
      // 지속적 프로세스는 장시간 실행되는 서버입니다. 플랫폼은
      // 각 트리거의 `path`에서 실행 중인 서버로
      // `Authorization: Bearer ${KAZZLE_TRIGGER_SECRET}`과 함께 트리거를 게시합니다.
      // 고객 코드는 작업을 수행하기 전에 헤더를 검증합니다.
      processMode: 'persistent',
      triggers: [
        // Cron 예제 — 주석 해제 및 조정합니다. 5필드, 분 단위 해상도.
        // { name: 'hourly-sync', kind: 'schedule', schedule: '0 * * * *', path: '/cron/hourly-sync' },
        // 웹훅 예제 — /webhooks/{spaceId}/{appId}/My App/incoming으로 POST합니다.
        // { name: 'incoming', kind: 'webhook', path: '/webhook/incoming' },
      ],
    },
  ],
});

빈 앱

import { defineConfig } from './kazzle.types';

export default defineConfig({
  /** 리포지토리 루트 기준 앱 아이콘 경로. 게시 시 CDN에 업로드됩니다. */
  icon: 'icon.svg',
  /** 앱 컴포넌트 — 각 항목은 배포 가능한 단위를 정의합니다. */
  components: [],
});