docs/guide/getting-started
시작하기 · 5분

빠른 시작

zenit 저장소 밖에 두고 독립적으로 빌드·실행되는 네이티브 macOS 앱을 만듭니다.

8분 분량
Claude Code나 다른 에이전트로 개발하나요? 먼저 zenit UI dev Skill을 설치하세요.

이 매뉴얼, 컴포넌트 선택표, 실제 프로젝트에서 겪은 함정을 에이전트가 필요할 때 불러오는 지침으로 묶었습니다. 그래서 작성되는 코드가 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를 그대로 쓰지 마십시오. 이를 공유하는 두 프로젝트가 Zig 패키지 캐시에서 충돌합니다. 그 줄을 지우고 zig build를 한 번 실행한 뒤 오류에 나온 값을 다시 붙여 넣으십시오. 이참에 .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 호출 한 줄만이 아니라 테스트 스위치 전달, Harness 클라이언트 설치, run 단계와 .app 패키징까지 포함합니다:

호출역할
zenit.attach(zenit_dep, exe)exe에 ui와 zenit_app 모듈 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를 만들고 마운트 함수를 한 번 호출한 뒤 이벤트 루프를 넘겨받습니다. 마운트 함수의 시그니처는 반드시 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 커서로 세 번 클릭하면 레이블이 “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