Quick Start

zero-native is a Zig desktop app shell with selectable web engines. Use the system WebView (WKWebView, WebKitGTK) for lightweight apps, or bundle Chromium via CEF on macOS for predictable Chromium rendering. Create a native desktop app with a web UI in under a minute.

Beta scope

The current beta target is macOS desktop apps. System WebView builds are available on macOS and Linux, Chromium/CEF builds and packages are macOS-only, and Windows plus Linux Chromium support are on the roadmap.

Prerequisites

Zig 0.16.0+
Node.js with npm for the generated frontend
macOS or Linux (Windows support is in progress)

Create a project

zero-native init my_app --frontend next
cd my_app

Frontend options: next, vite, react, svelte, vue.

This scaffolds a complete zero-native project:

File	Purpose
`build.zig`	Zig build graph with platform, trace, debug-overlay, automation, js-bridge, and web-engine options
`build.zig.zon`	Zig package manifest, declares zero-native dependency
`app.zon`	App metadata: name, icons, permissions, bridge commands, security policy, window definitions
`src/main.zig`	App struct with `app()` and optional `bridge()` methods
`src/runner.zig`	Platform wiring: trace sinks, file logging, panic capture, state store, runtime init
`assets/icon.icns`	App icon for macOS packages
`frontend/`	Frontend starter for the framework selected with `--frontend`

Run it

zig build run

The first frontend build installs dependencies automatically. Your app opens a native window with a WebView rendering your HTML.

macOS beta path

Use this path when validating an app for the macOS beta:

zero-native init my_app --frontend next
cd my_app
zig build run
zero-native cef install
zig build run
zero-native package --target macos --signing identity --identity "Developer ID Application: Your Name"
zero-native doctor --manifest app.zon --strict

Set .web_engine = "chromium" and .cef = .{ .dir = "third_party/cef/macos", .auto_install = false } in app.zon before the Chromium run. -Dweb-engine and --web-engine are still available for one-off overrides, but the normal app workflow reads the manifest.

For frontend frameworks, run the frontend dev server through Dev Server during development, then package the built assets for distribution.

Hello world

The simplest zero-native app provides a name and inline HTML:

const HelloApp = struct {
    fn app(self: *@This()) zero_native.App {
        return .{
            .context = self,
            .name = "hello",
            .source = zero_native.WebViewSource.html(
                \\<!doctype html>
                \\<html>
                \\<body style="font-family: system-ui; padding: 2rem;">
                \\  <h1>Hello from zero-native</h1>
                \\</body>
                \\</html>
            ),
        };
    }
};

Next steps

Web Engines -- Choose between system WebView and Chromium (CEF)
App Model -- How apps, sources, and lifecycle callbacks work
Frontend Projects -- Use React, Vue, or Svelte with zero-native
Bridge -- Call native Zig code from JavaScript
Security -- Permissions, policies, and navigation rules