> ## 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`                     | いいえ | カタログ内のアプリ名の下に表示される短い1行のタグライン（例："Control Mac apps from Kazzle"）。公開に必須 — 省略すると公開に失敗。                       |
| `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`                 | いいえ         | dev サーバーを起動するコマンド（例：`"bun run dev"`）             |
| `runtime.dev.env`      | object                   | いいえ         | dev のみの env オーバーライド。コンポーネント `env` にフォールバック。      |
| `runtime.prod.command` | `string`                 | いいえ         | 本番環境で起動するコマンド（例：`"bun run start"`）               |
| `runtime.prod.build`   | `string`                 | いいえ         | 本番環境用にビルドするコマンド（例：`"vite build"`）                |
| `runtime.prod.env`     | object                   | いいえ         | 本番環境のみの env オーバーライド。コンポーネント `env` にフォールバック。      |
| `schedule`             | `string`                 | いいえ         | process コンポーネント用の Cron スケジュール（例：`"*/5 * * * *"`） |
| `trigger`              | `"webhook"` \| `"event"` | いいえ         | process コンポーネント用のトリガーモード                         |
| `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' },
  ],
});
```