How vercel-labs/zero-native works
1. Repository shape
- This is a monorepo for a Zig-based desktop app framework plus its CLI, docs, examples, and publishable npm wrapper.
- The core product lives in src/; examples/ shows consumer apps; docs/ is a separate Next.js documentation site; packages/zero-native is the JavaScript package used for installation/distribution.
2. Core runtime model
- The central abstraction is an App described in Zig and a Runtime that owns the event loop, windows, bridge dispatch, automation hooks, tracing, and platform services.
- The root Zig exports are organized from src/root.zig, with feature areas split into modules like frontend, bridge, embed, extensions, automation, security, and runtime.
3. Platform boundary
- src/platform/ is the OS abstraction layer, with separate implementations for macOS, Linux, and Windows.
- Each platform subfolder contains native host code for embedding the web engine: AppKit/Objective-C++ on macOS, GTK/C/C++ on Linux, and WebView2/CEF C++ host code on Windows.
- This is the main boundary between portable Zig logic and OS-specific UI/runtime integration.
4. Web engine integration
- zero-native supports two execution modes: the platform’s system WebView or bundled Chromium via CEF.
- The engine choice is part of app configuration and determines whether the runtime delegates to native WebKit/WebView2/WebKitGTK or to a bundled CEF runtime.
- third_party/cef and tools/cef support vendoring/building the Chromium runtime when needed.
5. Frontend delivery
- The frontend is treated as web content loaded by the native shell, not as the application host itself.
- src/frontend/ and src/embed/ cover how packaged assets, inline HTML, URLs, or local dev servers are exposed to the runtime.
- Example apps show common frontends built with Next.js, React/Vite, Svelte/Vite, and Vue/Vite.
6. JavaScript-to-native bridge
- window.zero.invoke() is the primary JS-to-Zig call path.
- Bridge calls are routed through src/bridge/, with checks for origin, permissions, size limits, and registered handler availability.
- The bridge is a deliberate security boundary: web content is not trusted by default, and native capabilities must be explicitly enabled.
7. Security and policy
- Security policy is a first-class part of the app manifest and runtime behavior.
- src/security/, plus platform policy logic, govern navigation allowlists, external link handling, permissions, and window capabilities.
- This architecture keeps web content, native commands, and OS integrations separated unless explicitly authorized.
8. Manifest-driven configuration
- app.zon is the primary app manifest and defines metadata, icons, window layout, frontend source, web engine selection, security settings, bridge permissions, and packaging inputs.
- The src/primitives/app_manifest and src/tooling/manifest modules indicate the manifest is parsed and validated as part of the build/tooling pipeline, not ad hoc at runtime.
9. Tooling and developer workflow
- src/tooling/ provides the CLI-facing functionality: app initialization, dev mode, doctor checks, packaging, code signing, assets, templates, web engine handling, and manifest processing.
- tools/zero-native/ contains the CLI entry point, while packages/zero-native wraps distribution for npm and handles binary/framework copy and version sync scripts.
- This means the repo is both a library/runtime and a bootstrap/distribution system.
10. Automation and debugging
- src/automation/ is a distinct subsystem for app automation, snapshotting, and protocol/server support.
- src/debug/ and src/primitives/diagnostics support diagnostics and troubleshooting, which are also surfaced through tooling commands like doctor.
- These pieces sit alongside the runtime rather than inside the app UI path.
11. Shared primitives
- src/primitives/ contains reusable low-level building blocks: geometry, JSON, assets, platform info, app directories, trace, diagnostics, and manifest helpers.
- These modules are shared across runtime, tooling, and platform code, reducing duplication in the higher-level subsystems.
12. Native embedding examples
- examples/ios and examples/android show mobile hosts embedding the zero-native C ABI from a native app, rather than launching the standard desktop runtime.
- examples/webview shows a minimal native shell, while the framework examples demonstrate the desktop pattern of app.zon + Zig shell + frontend project.
- This indicates the library can be used both as a desktop app shell and as an embeddable native component.
13. Documentation and release pipeline
- docs/ is a standalone Next.js documentation site with MDX content, search indexing, and generated page metadata.
- GitHub Actions workflows cover CI and release, plus CEF runtime packaging, which matters because the bundled Chromium path is a separate artifact from the system-WebView path.
14. Build and packaging model
- build.zig and build.zig.zon drive the native build, while frontend examples use their own package managers/build tools.
- Packaging includes icons, entitlements, signing, and runtime assets, reflecting that the final deliverable is a native app bundle with embedded web content or a linked browser runtime.
Main entry points: src/root.zig src/root.zig · runtime/root.zig Runtime · platform/root.zig Platform layer · tooling/root.zig Tooling
Components 18
Core runtime
Zig app/runtime, bridge, security, embedding, and shared primitives.
- src/root.zig · Top-level Zig exports wiring the library subsystems together.
src/root.zig - Runtime · Owns windows, bridge dispatch, automation hooks, tracing, and platform services.
src/runtime/root.zig - Bridge · window.zero.invoke() call path with origin, permission, and handler checks.
src/bridge/root.zig - Frontend · Loads packaged assets, inline HTML, URLs, and local dev server content.
src/frontend/root.zig - Embed · Connects frontend delivery to the native shell and runtime embedding model.
src/embed/root.zig - Security · Navigation, permissions, external links, and window capability policy.
src/security/root.zig - Automation · App automation, snapshotting, and protocol/server support.
src/automation/root.zig - Primitives · Reusable low-level helpers for manifest, assets, diagnostics, geometry, JSON, trace, and platform info.
src/primitives
Platform hosts
OS-specific native embedding layers for desktop and mobile integrations.
- Platform layer · Portable boundary that selects native host implementations per OS.
src/platform/root.zig - macOS host · AppKit/Objective-C++ embedding and macOS-specific automation and CEF host code.
src/platform/macos/root.zig - Linux host · GTK/C/C++ embedding plus Linux CEF host code.
src/platform/linux/root.zig - Windows host · WebView2 and CEF host integration for Windows.
src/platform/windows/root.zig
Tooling & packaging
CLI, manifest processing, packaging, and distribution helpers.
Docs site
Standalone Next.js documentation app and content.
- Docs site · Standalone Next.js documentation site with MDX content and search.
docs/src/app/page.mdx
Examples
Reference consumer apps and embedding samples.
- Examples · Desktop, webview, iOS, Android, and frontend framework examples.
examples/README.md
Distribution
Publishable npm wrapper and native binary installation scripts.
- zero-native pkg · Distribution package that installs binaries/frameworks and synchronizes versions.
packages/zero-native/package.json
Other components
- zero-native · Zig desktop app framework, CLI, docs, examples, and npm distribution wrapper.
Connections 28
- zero-native → src/root.zig: core library · Top-level repository contains the Zig library runtime.
- zero-native → Tooling: CLI/tooling · Repository includes build, dev, packaging, and doctor workflows.
- zero-native → Docs site: docs · Repository includes a standalone documentation application.
- zero-native → Examples: samples · Repository includes consumer and embedding examples.
- zero-native → zero-native pkg: distribution · Repository publishes a Node package wrapper.
- src/root.zig → Runtime: exports · Root Zig exports the runtime subsystem.
- src/root.zig → Bridge: exports · Root Zig exports the bridge subsystem.
- src/root.zig → Frontend: exports · Root Zig exports frontend loading helpers.
- src/root.zig → Embed: exports · Root Zig exports embedding helpers.
- src/root.zig → Security: exports · Root Zig exports policy and security helpers.
- src/root.zig → Automation: exports · Root Zig exports automation features.
- src/root.zig → Primitives: shared core · Root Zig depends on shared primitives.
- Runtime → Platform layer: host services · Runtime delegates OS services through platform abstraction.
- Runtime → Bridge: dispatches · Runtime routes native calls through the bridge.
- Runtime → Frontend: loads · Runtime presents app frontend content.
- Runtime → Security: enforces · Runtime applies security policy during navigation and capability use.
- Runtime → Automation: supports · Runtime exposes automation and snapshot support.
- Tooling → CLI entry: drives · Tooling powers the command-line entry point.
- Tooling → zero-native pkg: packages · Tooling feeds distribution and install scripts.
- Tooling → Primitives: parses config · Tooling uses shared manifest and diagnostics helpers.
- Platform layer → macOS host: selects · Portable platform layer selects macOS host implementation.
- Platform layer → Linux host: selects · Portable platform layer selects Linux host implementation.
- Platform layer → Windows host: selects · Portable platform layer selects Windows host implementation.
- Platform layer → Security: policy hooks · Platform layer contributes navigation and capability policy enforcement.
- Docs site → src/root.zig: documents · Docs explain the library and runtime architecture.
- Examples → src/root.zig: consumes · Examples demonstrate the library runtime and embedding APIs.
- zero-native pkg → CLI entry: installs · Package wrapper installs the native CLI binary.
- zero-native pkg → Tooling: syncs versions · Distribution scripts align package and binary versions.