Configuração
Todo app Kazzle tem umkazzle.config.ts na raiz do projeto. Este arquivo define o que seu app contém — componentes, skills e metadados.
Início rápido
import { defineConfig } from '@kazzle/app';
export default defineConfig({
components: [
{ name: 'My App', type: 'ui', path: '.' }
]
});
defineConfig fornece autocompletar e validação do TypeScript. Os tipos vêm do pacote @kazzle/app incluído em cada template.
Campos de nível superior
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
name | string | não | Nome de exibição para marketing mostrado no catálogo de apps. Volta para o slug quando omitido. |
subtitle | string | não | Tagline curta de uma linha mostrada sob o nome do app no catálogo (ex: “Controle apps Mac do Kazzle”). Obrigatório para publicar — omitir e a publicação falha. |
version | string | não | Rótulo de versão definido pelo autor (ex: “1.2.0”). Apenas para exibição; capturado na publicação e mostrado em clones como a versão de origem. |
icon | string | não | Caminho para o arquivo de ícone do app relativo à raiz do repositório (png, jpg, svg, webp, ico). Enviado para CDN na publicação. |
accentColor | string | não | Cor de destaque de marca opcional como string hexadecimal (ex: “#3b82f6”). Tinta o chip de ícone do app e o hero de detalhes. Quando omitido, o destaque é amostrado automaticamente do ícone. |
kazzleAuth | "optional" | "required" | não | Restrição de identidade para a superfície de lançamento do app — “optional” (identidade fornecida se um usuário Kazzle estiver presente) ou “required” (deve ser um usuário Kazzle conectado para visualizar). |
launchUrl | string | não | URL absoluta literal aberta dentro do Kazzle quando o app é clicado, usada literalmente. Quando omitido, a superfície de lançamento é a URL de visualização implantada do componente UI. |
webhookUrl | string | não | Endpoint do publicador que Kazzle faz POST em app.installed / app.uninstalled (entrega a chave de instalação). |
components | object[] | não | Componentes executáveis — frontends UI ou processos em background |
skills | object[] | não | Definições de skill de IA — arquivos markdown que a IA lê para conhecimento de domínio |
capabilities | object | não | Recursos opcionais de integração desktop como hotkeys, notificações e presença na barra de status |
Campos de componente
Cada entrada emcomponents[]:
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
name | string | sim | Nome único do componente dentro do app |
type | "ui" | "process" | sim | Tipo de componente — ui (máx 1) ou process |
path | string | sim | Caminho de entrada dentro do diretório do app |
runtime | object | não | Comandos e overrides de env opcionais: { dev?, prod? } |
runtime.dev.command | string | não | Comando para iniciar o servidor de dev (ex: "bun run dev") |
runtime.dev.env | object | não | Override de env apenas para dev. Volta para o env do componente. |
runtime.prod.command | string | não | Comando para iniciar em produção (ex: "bun run start") |
runtime.prod.build | string | não | Comando para compilar para produção (ex: "vite build") |
runtime.prod.env | object | não | Override de env apenas para produção. Volta para o env do componente. |
schedule | string | não | Agendamento cron para componentes de processo (ex: "*/5 * * * *") |
trigger | "webhook" | "event" | não | Modo de acionamento para componentes de processo |
env | object | não | Coleção de segredos + ambiente para injeção de variável de env |
env.collection | string | sim (se env) | Slug da coleção de segredos |
env.environment | string | sim (se env) | Slug do ambiente |
env.include | string[] | não | Injetar apenas estes nomes de variável de env. Se omitido, injetar todos da coleção+ambiente. |
Campos de skill
Cada entrada emskills[]:
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
name | string | sim | Nome do skill |
path | string | sim | Caminho para o arquivo SKILL.md relativo à raiz do app |
Restrições
- Máx 1 componente UI por app
- Valores de
namedo componente devem ser únicos dentro do app
Exemplos de template
ai app
import { defineConfig } from '@kazzle/app';
export default defineConfig({
/** Tagline de catálogo de uma linha. Obrigatório 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
import { defineConfig } from '@kazzle/app';
export default defineConfig({
/** Tagline de catálogo de uma linha. Obrigatório 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
import { defineConfig } from '@kazzle/app';
export default defineConfig({
/** Tagline de catálogo de uma linha. Obrigatório para publicar. */
subtitle: 'My App',
/** Caminho para o ícone do app relativo à raiz do repositório. Enviado para CDN na publicação. */
icon: 'components/ui/public/favicon.svg',
/** Componentes do app — cada entrada define uma unidade implantável. Máx 1 componente UI. */
components: [
{ name: 'My App', type: 'ui', path: './components/ui' },
],
});