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

# Configuración

> Referencia completa de kazzle.config.ts — el manifiesto de la aplicación.

# Configuración

Cada aplicación Kazzle tiene un `kazzle.config.ts` en la raíz del proyecto. Este archivo define qué contiene tu aplicación — componentes, skills e información.

## Inicio rápido

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

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

El helper `defineConfig` proporciona autocompletado y validación de TypeScript. Los tipos provienen del paquete `@kazzle/app` incluido en cada plantilla.

## Campos de nivel superior

| Campo          | Tipo                         | Requerido | Descripción                                                                                                                                                                                                                 |
| -------------- | ---------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`         | `string`                     | no        | Nombre de visualización de marketing mostrado en el catálogo de aplicaciones. Vuelve al slug si se omite.                                                                                                                   |
| `subtitle`     | `string`                     | no        | Lema corto de una línea mostrado bajo el nombre de la aplicación en el catálogo (p. ej. "Controla aplicaciones Mac desde Kazzle"). Requerido para publicar — omitirlo causa fallo en la publicación.                        |
| `version`      | `string`                     | no        | Etiqueta de versión establecida por el autor (p. ej. "1.2.0"). Solo para visualización; se captura al publicar y se muestra en clones como la versión de la que se bifurcó.                                                 |
| `icon`         | `string`                     | no        | Ruta al archivo de icono de la aplicación relativa a la raíz del repositorio (png, jpg, svg, webp, ico). Se carga en CDN al publicar.                                                                                       |
| `accentColor`  | `string`                     | no        | Color de acento de marca opcional como cadena hexadecimal (p. ej. "#3b82f6"). Tinta el chip de icono de la aplicación y el héroe de detalles. Si se omite, el acento se muestrea automáticamente del icono.                 |
| `kazzleAuth`   | `"optional"` \| `"required"` | no        | Restricción de identidad para la superficie de lanzamiento de la aplicación — "optional" (identidad proporcionada si hay un usuario de Kazzle presente) o "required" (debe ser un usuario de Kazzle conectado para ver).    |
| `launchUrl`    | `string`                     | no        | URL absoluta literal abierta dentro de Kazzle cuando se hace clic en la aplicación, usada tal cual. Si se omite, la superficie de lanzamiento es la URL de vista previa implementada del componente de interfaz de usuario. |
| `webhookUrl`   | `string`                     | no        | Punto final del editor que Kazzle envía por POST en app.installed / app.uninstalled (entrega la clave de instalación).                                                                                                      |
| `components`   | object\[]                    | no        | Componentes ejecutables — frontends de interfaz de usuario o procesos en segundo plano                                                                                                                                      |
| `skills`       | object\[]                    | no        | Definiciones de skills de IA — archivos markdown que la IA lee para conocimiento del dominio                                                                                                                                |
| `capabilities` | `object`                     | no        | Características opcionales de integración de escritorio como teclas de acceso rápido, notificaciones y presencia en la barra de estado                                                                                      |

## Campos de componente

Cada entrada en `components[]`:

| Campo                  | Tipo                     | Requerido   | Descripción                                                                                         |
| ---------------------- | ------------------------ | ----------- | --------------------------------------------------------------------------------------------------- |
| `name`                 | `string`                 | sí          | Nombre único del componente dentro de la aplicación                                                 |
| `type`                 | `"ui"` \| `"process"`    | sí          | Tipo de componente — ui (máx. 1) o process                                                          |
| `path`                 | `string`                 | sí          | Ruta de entrada dentro del directorio de la aplicación                                              |
| `runtime`              | object                   | no          | Comandos y anulaciones de env opcionales: `{ dev?, prod? }`                                         |
| `runtime.dev.command`  | `string`                 | no          | Comando para iniciar el servidor de desarrollo (p. ej. `"bun run dev"`)                             |
| `runtime.dev.env`      | object                   | no          | Anulación de env solo para desarrollo. Vuelve a env del componente.                                 |
| `runtime.prod.command` | `string`                 | no          | Comando para iniciar en producción (p. ej. `"bun run start"`)                                       |
| `runtime.prod.build`   | `string`                 | no          | Comando para compilar para producción (p. ej. `"vite build"`)                                       |
| `runtime.prod.env`     | object                   | no          | Anulación de env solo para producción. Vuelve a env del componente.                                 |
| `schedule`             | `string`                 | no          | Cronograma cron para componentes de proceso (p. ej. `"*/5 * * * *"`)                                |
| `trigger`              | `"webhook"` \| `"event"` | no          | Modo de activación para componentes de proceso                                                      |
| `env`                  | object                   | no          | Colección de secretos + entorno para inyección de variables de env                                  |
| `env.collection`       | `string`                 | sí (si env) | Slug de colección de secretos                                                                       |
| `env.environment`      | `string`                 | sí (si env) | Slug de entorno                                                                                     |
| `env.include`          | `string[]`               | no          | Solo inyecta estos nombres de variables de env. Si se omite, inyecta todos de la colección+entorno. |

## Campos de skill

Cada entrada en `skills[]`:

| Campo  | Tipo     | Requerido | Descripción                                                  |
| ------ | -------- | --------- | ------------------------------------------------------------ |
| `name` | `string` | sí        | Nombre del skill                                             |
| `path` | `string` | sí        | Ruta al archivo SKILL.md relativa a la raíz de la aplicación |

## Restricciones

* **Máx. 1 componente de interfaz de usuario** por aplicación
* Los valores de `name` del componente deben ser únicos dentro de la aplicación

## Ejemplos de plantillas

### ai app

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

export default defineConfig({
  /** Lema de catálogo de una línea. Requerido para publicar. */
  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({
  /** Lema de catálogo de una línea. Requerido para publicar. */
  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({
  /** Lema de catálogo de una línea. Requerido para publicar. */
  subtitle: 'My App',
  /** Ruta al icono de la aplicación relativa a la raíz del repositorio. Se carga en CDN al publicar. */
  icon: 'components/ui/public/favicon.svg',
  /** Componentes de la aplicación — cada entrada define una unidad implementable. Máx. 1 componente de interfaz de usuario. */
  components: [
    { name: 'My App', type: 'ui', path: './components/ui' },
  ],
});
```