docs/guide/getting-started
はじめに · 5 分

クイックスタート

zenit リポジトリの外に置き、単独でビルド・実行できるネイティブ macOS アプリを作成します。

約 8 分で読めます
Claude Code や他の Agent で開発していますか? まず zenit UI dev Skill を入れましょう。

この手引き、コンポーネント選定表、実プロジェクトで踏んだ落とし穴を、Agent が必要に応じて読み込める指示としてまとめています。書かれるコードはそのまま zenit の規約に沿います。

前提条件

このリリースは macOS を対象とし、Apple Silicon で継続的に検証しています。Zig 0.15.2 と Xcode Command Line Tools があることを確認してください。Bun はエンドツーエンドテストを実行する場合にのみ必要です。

Terminal
zig version
xcode-select -p

プロジェクトを作成

リポジトリの templates/minimal-app から始めます。これは完全な下流プロジェクトです:

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
    テンプレートをコピー

    templates/minimal-app を zenit リポジトリ外の新しいディレクトリにコピーします。

  2. 2
    依存パスを修正

    テンプレートの既定値 .path = "../../" はリポジトリ内でしか解決できません。コピー後、build.zig.zon からの相対パスで zenit の checkout を指すよう変更するか、zig fetch --save=zenit <url> で公開リビジョンに固定してください。

  3. 3
    フィンガープリントを生成

    テンプレートの .fingerprint を流用しないでください。共有した 2 つのプロジェクトが Zig のパッケージキャッシュで衝突します。その行を削除して zig build を 1 回実行し、エラーに表示された値を貼り戻します。ついでに .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

zenit を接続

build.zig.zon が依存を宣言し、build.zig は @import("zenit") で zenit 自身のビルド API を取得します。

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",
    },
}

以下はテンプレートの build.zig そのままです。attach 1 行だけではなく、テスト用スイッチの転送、Harness クライアントのインストール、run ステップと .app パッケージングも含みます:

呼び出し役割
zenit.attach(zenit_dep, exe)exe に ui と zenit_app の 2 モジュールの import を追加し、macOS の ObjC ブリッジ 5 つをコンパイルして、Cocoa・Metal・CoreText などのフレームワークをリンク
.@"test-mode" / .@"e2e-port"Zig の依存オプションは分離されているため、明示的に転送しないと zig build -Dtest-mode=true が zenit に届かない
zenit.installHarnessClient(b, zenit_dep)型付きの Harness クライアントを zig-out/share/zenit/harness/client.ts にインストールし、e2e/record-demo.ts から使う
zenit.bundleApp(b, .{ ... })ダブルクリックで起動できる zig-out/<display_name>.app を生成。ここでは ad-hoc 署名

最初の UI ツリーをマウント

App.runWith はルート Scope を作成し、マウント関数を 1 回呼び出して、イベントループを引き継ぎます。マウント関数のシグネチャは fn (cx: *ui.Cx, scope: *ui.Scope) anyerror!*ui.Node でなければならず、アプリはルートノードを返すだけです。

cx.bindState は Counter を Cx に持たせ、cx.on はそのメソッドをボタンのコールバックに変えます。test_id により E2E スクリプトが意味でボタンを見つけられます。

ビルドと実行

Terminal
zig build run   # build and run the unbundled executable
zig build app   # package zig-out/My App.app (macOS)
ビルド成果物から起動した実際の Hello Button.app(examples/hello_button、テンプレートと同じカウンターボタン):harness が hand カーソルで 3 回クリックし、ラベルが「Clicked 3 times」になります。ウィンドウ、ウィジェット、応答はすべて上記の公開 API によるものです。

テンプレートには録画スクリプトも付属しています。zig build -Dtest-mode=true でビルドしてアプリを起動し、e2e/record-demo.ts を実行すると同様の動画が得られます。詳しくは E2E harness を参照してください。

zenit · デュアルライセンスオープンソースプロジェクトは GPL-3.0-only のもとで無料で使えます。クローズドソースや商用製品には商用ライセンスが必要です。作者への連絡先:zongyi.xzy#gmail.com(# を @ に置き換え)zenit 5f9add5+wip 2026-09-30