docs/guide/getting-started
Empezar · 5 min

Inicio rápido

Crea una app nativa de macOS que vive fuera del repo de zenit y se compila y ejecuta por sí sola.

8 min de lectura
¿Desarrollas con Claude Code u otro agente? Instala primero la zenit UI dev Skill.

Empaqueta este manual, la tabla de decisión de componentes y las trampas de proyectos reales en instrucciones que tu agente carga cuando las necesita, para que el código que escribe siga las convenciones de zenit.

Requisitos previos

Esta versión apunta a macOS, con Apple Silicon verificado de forma continua. Asegúrate de tener Zig 0.15.2 y las Xcode Command Line Tools; Bun solo hace falta para las pruebas end-to-end.

Terminal
zig version
xcode-select -p

Crear un proyecto

Parte de templates/minimal-app en el repo. Es un proyecto downstream completo:

templates/minimal-app
minimal-app/
├── README.md
├── build.zig          # zenit.attach() + run / app steps
├── build.zig.zon      # declares the zenit dependency
├── e2e/
│   └── record-demo.ts # drives and records the app through the Harness
└── src/
    └── main.zig       # counter-button app
  1. 1
    Copia la plantilla

    Copia templates/minimal-app a un directorio nuevo fuera del repo de zenit.

  2. 2
    Ajusta la ruta de la dependencia

    La plantilla usa por defecto .path = "../../", que solo se resuelve dentro del repo. Tras copiarla, apúntala a tu checkout de zenit de forma relativa a build.zig.zon, o fija una revisión publicada con zig fetch --save=zenit <url>.

  3. 3
    Genera una huella

    No conserves el .fingerprint de la plantilla: dos proyectos que lo compartan chocan en la caché de paquetes de Zig. Borra la línea, ejecuta zig build una vez y pega el valor que indica el error. De paso, cambia .name = .myapp.

Terminal
git clone https://github.com/version-next/zenit.git
cp -R zenit/templates/minimal-app ./myapp
cd myapp   # then set .zenit = .{ .path = "../zenit" } in build.zig.zon
zig build

Conectar zenit

build.zig.zon declara la dependencia; build.zig obtiene la API de build propia de zenit mediante @import("zenit").

build.zig.zon
.{
    .name = .myapp,
    .version = "0.1.0",
    .fingerprint = 0x8798022a7f8e220e, // replace: delete this line, run zig build once
    .minimum_zig_version = "0.15.2",

    .dependencies = .{
        // Relative to this file. Absolute paths are rejected by Zig 0.15.2.
        .zenit = .{ .path = "../zenit" },
    },

    .paths = .{
        "README.md",
        "build.zig",
        "build.zig.zon",
        "e2e",
        "src",
    },
}

Este es el build.zig de la plantilla tal cual. Es más que una llamada a attach: reenvía los flags de test, instala el cliente del Harness y define el paso run y el empaquetado .app:

LlamadaQué hace
zenit.attach(zenit_dep, exe)Añade los imports de módulo ui y zenit_app, compila los cinco puentes ObjC de macOS y enlaza Cocoa, Metal, CoreText y los demás frameworks
.@"test-mode" / .@"e2e-port"En Zig las opciones de dependencia están aisladas; reenvíalas explícitamente para que zig build -Dtest-mode=true llegue a zenit
zenit.installHarnessClient(b, zenit_dep)Instala el cliente tipado del Harness en zig-out/share/zenit/harness/client.ts para e2e/record-demo.ts
zenit.bundleApp(b, .{ ... })Genera un zig-out/<display_name>.app que se abre con doble clic, aquí con firma ad-hoc

Monta tu primer árbol de UI

App.runWith crea el Scope raíz, llama una vez a tu función de montaje y toma el control del bucle de eventos. La función de montaje debe tener la firma fn (cx: *ui.Cx, scope: *ui.Scope) anyerror!*ui.Node; tu app solo devuelve el nodo raíz.

cx.bindState entrega Counter al Cx, y cx.on convierte uno de sus métodos en el callback del botón; test_id permite que los scripts E2E encuentren el botón por su significado.

Compilar y ejecutar

Terminal
zig build run   # build and run the unbundled executable
zig build app   # package zig-out/My App.app (macOS)
La Hello Button.app real lanzada desde la salida del build (examples/hello_button, el mismo botón contador que la plantilla): el harness hace clic tres veces con el cursor de mano y la etiqueta muestra “Clicked 3 times”. Ventana, widget y respuesta vienen de la API pública de arriba.

La plantilla también incluye un script de grabación: compila con zig build -Dtest-mode=true, arranca la app y ejecuta e2e/record-demo.ts para obtener un clip similar; consulta E2E harness.

zenit · Doble licenciaGratis para proyectos de código abierto bajo GPL-3.0-only; los productos cerrados o comerciales necesitan una licencia comercial.Contacta con el autor: zongyi.xzy#gmail.com (cambia # por @)zenit 5f9add5+wip 2026-09-30