Web Engines

zero-native has one app/runtime API and selectable web engine backends. The default is the platform system WebView. On macOS, apps can instead bundle Chromium through CEF.

Support Matrix

The intended parity contract is the same Zig app model, same runtime services, same builtin bridge commands, same window.zero helper shape, and the same security policy semantics for every engine that a platform supports.

System WebView

.web_engine = "system",

System mode has no bundled browser dependency. It uses the OS web engine, so rendering and web platform support follow the user's installed OS.

Chromium (CEF)

Set the app engine once:

.web_engine = "chromium",
.cef = .{ .dir = "third_party/cef/macos", .auto_install = false },

zero-native cef install
zig build run

CEF mode is first-class on macOS. It uses the same zero-native runtime APIs as WKWebView, but bundles Chromium for rendering consistency and a predictable web platform.

Chromium is currently wired for macOS only. Linux continues to use WebKitGTK, and Windows support is in progress. Treat the beta as macOS-focused when choosing Chromium.

Setup

The happy path is managed by the CLI:

zero-native cef install
zero-native doctor --manifest app.zon

zero-native cef install downloads zero-native's prepared macOS CEF runtime from GitHub Releases, verifies it, and installs a complete layout into third_party/cef/macos. The prepared runtime already includes libcef_dll_wrapper.a, so app developers do not need CMake or Chromium build knowledge.

The default install uses zero-native's pinned tested CEF version. Pin that version in your app CI or setup docs with zero-native cef install --version <version>, rerun the install when you intentionally update Chromium, then rebuild and repackage the app. A packaged Chromium app must bundle the same CEF layout the binary was linked against; mismatches usually show up as launch failures or missing framework/resource errors.

You can also opt into one-command local setup from the build:

zig build run

Set .cef = .{ .dir = "third_party/cef/macos", .auto_install = true } in app.zon to allow the build/package flow to install the prepared runtime automatically. Manual CEF layouts are still supported with -Dcef-dir=/path/to/cef or .cef.dir. Advanced users can also install directly from official CEF archives with zero-native cef install --source official --allow-build-tools. The expected layout is documented in third_party/cef/README.md.

Core maintainers can build CEF from source with tools/cef/build-from-source.sh when preparing the first runtime release for a version or testing a new CEF branch before publishing it.

Build Overrides

Bundling

zig build cef-bundle -Dcef-dir=/path/to/cef

Local Chromium builds also copy the CEF framework into zig-out/bin/Frameworks when Chromium is selected through app.zon or a one-off flag. Packaging includes the runtime when the manifest or CLI override resolves to Chromium.

For beta distribution, verify the packaged .app contains Chromium Embedded Framework.framework under Contents/Frameworks and that signing covers both the app and embedded framework before notarization.

Smoke Tests

zig build test-webview-cef-smoke -Dplatform=macos -Dweb-engine=chromium
zig build test-package-cef-layout -Dplatform=macos

The Chromium smoke step requires a local CEF layout or -Dcef-auto-install=true. It launches the example with automation, verifies native.ping, and exercises JS window create/list/focus/close. The package layout step verifies that a Chromium macOS package contains the framework and resources CEF expects.

Choosing An Engine

In app.zon

.web_engine = "system",
// or, on supported platforms:
.web_engine = "chromium",
.cef = .{
  .dir = "third_party/cef/macos",
  .auto_install = true,
},