> ## 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.

# Configurazione

> Riferimento completo per kazzle.config.ts — il manifest dell'app.

# Configurazione

Ogni app Kazzle ha un file `kazzle.config.ts` nella radice del progetto. Questo file definisce cosa contiene la tua app — componenti, skill e metadati.

## Avvio rapido

```typescript theme={"theme":"material-theme-darker"}
import { defineConfig } from '@kazzle/app';

export default defineConfig({
  components: [
    { name: 'My App', type: 'ui', path: '.' }
  ]
});
```

L'helper `defineConfig` fornisce autocompletamento TypeScript e validazione. I tipi provengono dal pacchetto `@kazzle/app` incluso in ogni template.

## Campi di primo livello

| Campo          | Tipo                         | Obbligatorio | Descrizione                                                                                                                                                                                      |
| -------------- | ---------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name`         | `string`                     | no           | Nome di visualizzazione marketing mostrato nel catalogo app. Ritorna al slug se omesso.                                                                                                          |
| `subtitle`     | `string`                     | no           | Breve tagline su una riga mostrata sotto il nome dell'app nel catalogo (es. "Controlla app Mac da Kazzle"). Obbligatorio per pubblicare — se omesso la pubblicazione fallisce.                   |
| `version`      | `string`                     | no           | Etichetta di versione impostata dall'autore (es. "1.2.0"). Solo per visualizzazione; acquisita al momento della pubblicazione e mostrata sui cloni come versione da cui è stato fatto il fork.   |
| `icon`         | `string`                     | no           | Percorso del file icona dell'app relativo alla radice del repo (png, jpg, svg, webp, ico). Caricato su CDN al momento della pubblicazione.                                                       |
| `accentColor`  | `string`                     | no           | Colore di accento del brand opzionale come stringa esadecimale (es. "#3b82f6"). Tinta il chip icona app e l'hero dei dettagli. Se omesso, l'accento viene campionato automaticamente dall'icona. |
| `kazzleAuth`   | `"optional"` \| `"required"` | no           | Gating dell'identità per la superficie di lancio dell'app — "optional" (identità fornita se è presente un utente Kazzle) o "required" (deve essere un utente Kazzle connesso per visualizzare).  |
| `launchUrl`    | `string`                     | no           | URL assoluto letterale aperto dentro Kazzle quando l'app viene cliccata, usato così com'è. Se omesso, la superficie di lancio è l'URL di anteprima distribuito del componente UI.                |
| `webhookUrl`   | `string`                     | no           | Endpoint dell'editore a cui Kazzle invia POST su app.installed / app.uninstalled (consegna la chiave di installazione).                                                                          |
| `components`   | object\[]                    | no           | Componenti eseguibili — frontend UI o processi in background                                                                                                                                     |
| `skills`       | object\[]                    | no           | Definizioni di skill AI — file markdown che l'AI legge per la conoscenza del dominio                                                                                                             |
| `capabilities` | `object`                     | no           | Funzionalità opzionali di integrazione desktop come hotkey, notifiche e presenza nella barra di stato                                                                                            |

## Campi componente

Ogni voce in `components[]`:

| Campo                  | Tipo                     | Obbligatorio | Descrizione                                                                                       |
| ---------------------- | ------------------------ | ------------ | ------------------------------------------------------------------------------------------------- |
| `name`                 | `string`                 | sì           | Nome componente univoco all'interno dell'app                                                      |
| `type`                 | `"ui"` \| `"process"`    | sì           | Tipo di componente — ui (max 1) o process                                                         |
| `path`                 | `string`                 | sì           | Percorso di ingresso all'interno della directory app                                              |
| `runtime`              | object                   | no           | Comandi e override env opzionali: `{ dev?, prod? }`                                               |
| `runtime.dev.command`  | `string`                 | no           | Comando per avviare il dev server (es. `"bun run dev"`)                                           |
| `runtime.dev.env`      | object                   | no           | Override env solo per lo sviluppo. Ritorna al componente `env`.                                   |
| `runtime.prod.command` | `string`                 | no           | Comando per avviare in produzione (es. `"bun run start"`)                                         |
| `runtime.prod.build`   | `string`                 | no           | Comando per compilare per la produzione (es. `"vite build"`)                                      |
| `runtime.prod.env`     | object                   | no           | Override env solo per la produzione. Ritorna al componente `env`.                                 |
| `schedule`             | `string`                 | no           | Schedule cron per componenti process (es. `"*/5 * * * *"`)                                        |
| `trigger`              | `"webhook"` \| `"event"` | no           | Modalità trigger per componenti process                                                           |
| `env`                  | object                   | no           | Raccolta secret + ambiente per l'iniezione di variabili env                                       |
| `env.collection`       | `string`                 | sì (se env)  | Slug della raccolta secret                                                                        |
| `env.environment`      | `string`                 | sì (se env)  | Slug dell'ambiente                                                                                |
| `env.include`          | `string[]`               | no           | Inietta solo questi nomi di variabili env. Se omesso, inietta tutti dalla collection+environment. |

## Campi skill

Ogni voce in `skills[]`:

| Campo  | Tipo     | Obbligatorio | Descrizione                                              |
| ------ | -------- | ------------ | -------------------------------------------------------- |
| `name` | `string` | sì           | Nome della skill                                         |
| `path` | `string` | sì           | Percorso del file SKILL.md relativo alla radice dell'app |

## Vincoli

* **Max 1 componente UI** per app
* I valori `name` del componente devono essere univoci all'interno dell'app

## Esempi di template

### ai app

```typescript theme={"theme":"material-theme-darker"}
import { defineConfig } from '@kazzle/app';

export default defineConfig({
  /** Tagline catalogo su una riga. Obbligatorio per pubblicare. */
  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({
  /** Tagline catalogo su una riga. Obbligatorio per pubblicare. */
  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({
  /** Tagline catalogo su una riga. Obbligatorio per pubblicare. */
  subtitle: 'My App',
  /** Percorso dell'icona app relativo alla radice del repo. Caricato su CDN al momento della pubblicazione. */
  icon: 'components/ui/public/favicon.svg',
  /** Componenti app — ogni voce definisce un'unità distribuibile. Max 1 componente UI. */
  components: [
    { name: 'My App', type: 'ui', path: './components/ui' },
  ],
});
```