docs/guide/getting-started
Démarrer · 5 min

Démarrage rapide

Créez une app macOS native qui vit hors du dépôt zenit et se compile et s'exécute de façon autonome.

8 min de lecture
Vous développez avec Claude Code ou un autre agent ? Installez d’abord la zenit UI dev Skill.

Elle regroupe ce manuel, la table de choix des composants et les pièges de projets réels en instructions que votre agent charge à la demande, pour que le code qu’il écrit suive les conventions de zenit.

Prérequis

Cette version cible macOS, avec Apple Silicon vérifié en continu. Assurez-vous d'avoir Zig 0.15.2 et les Xcode Command Line Tools ; Bun n'est nécessaire que pour les tests de bout en bout.

Terminal
zig version
xcode-select -p

Créer un projet

Partez de templates/minimal-app dans le dépôt. C'est un projet downstream complet :

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
    Copier le template

    Copiez templates/minimal-app dans un nouveau répertoire hors du dépôt zenit.

  2. 2
    Corriger le chemin de dépendance

    Le template utilise par défaut .path = "../../", qui ne se résout qu'à l'intérieur du dépôt. Après la copie, pointez-le vers votre checkout de zenit relativement à build.zig.zon, ou épinglez une révision publiée avec zig fetch --save=zenit <url>.

  3. 3
    Générer une empreinte

    Ne gardez pas le .fingerprint du template : deux projets qui le partagent entrent en collision dans le cache de paquets de Zig. Supprimez la ligne, lancez zig build une fois et recollez la valeur indiquée par l'erreur. Renommez .name = .myapp au passage.

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

Brancher zenit

build.zig.zon déclare la dépendance ; build.zig obtient l'API de build de zenit via @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",
    },
}

Voici le build.zig du template tel quel. Il fait plus qu'un appel à attach : il transmet les options de test, installe le client Harness et définit l'étape run et le packaging .app :

AppelRôle
zenit.attach(zenit_dep, exe)Ajoute les imports de modules ui et zenit_app, compile les cinq ponts ObjC macOS et lie Cocoa, Metal, CoreText et les autres frameworks
.@"test-mode" / .@"e2e-port"Les options de dépendance sont isolées en Zig ; transmettez-les explicitement pour que zig build -Dtest-mode=true atteigne zenit
zenit.installHarnessClient(b, zenit_dep)Installe le client Harness typé dans zig-out/share/zenit/harness/client.ts pour e2e/record-demo.ts
zenit.bundleApp(b, .{ ... })Produit un zig-out/<display_name>.app lançable d'un double-clic, ici signé ad hoc

Monter votre premier arbre UI

App.runWith crée le Scope racine, appelle une fois votre fonction de montage et prend la main sur la boucle d'événements. La fonction de montage doit avoir la signature fn (cx: *ui.Cx, scope: *ui.Scope) anyerror!*ui.Node ; votre app se contente de renvoyer le nœud racine.

cx.bindState confie Counter au Cx, et cx.on transforme l'une de ses méthodes en callback du bouton ; test_id permet aux scripts E2E de trouver le bouton par son rôle.

Compiler et exécuter

Terminal
zig build run   # build and run the unbundled executable
zig build app   # package zig-out/My App.app (macOS)
La vraie Hello Button.app lancée depuis la sortie du build (examples/hello_button, le même bouton compteur que le template) : le harness clique trois fois avec le curseur main et le libellé affiche « Clicked 3 times ». Fenêtre, widget et réponse viennent tous de l'API publique ci-dessus.

Le template fournit aussi un script d'enregistrement : compilez avec zig build -Dtest-mode=true, lancez l'app, puis exécutez e2e/record-demo.ts pour obtenir le même type de clip — voir E2E harness.

zenit · Double licenceGratuit pour les projets open source sous GPL-3.0-only ; les produits propriétaires ou commerciaux nécessitent une licence commerciale.Contacter l’auteur : zongyi.xzy#gmail.com (remplacez # par @)zenit 5f9add5+wip 2026-09-30