---
title: Web Engines
url: "https://native-sdk.dev/docs/web-engines"
docs_index: /llms.txt
lastUpdated: 2026-10-16
---

> For an index of all documentation, see [/llms.txt](/llms.txt).

Apps that [embed web content](/docs/frontend) choose a web engine backend for their WebViews; the app/runtime API is the same across engines. The default is the platform system WebView. On macOS, apps can instead bundle Chromium through CEF. Native-rendered apps carry no web engine at all — this page only applies when a WebView is in the window.

## Support Matrix

<table>
  <thead>
    <tr>
      <th>
        Platform
      </th>

      <th>
        `system`
      </th>

      <th>
        `chromium`
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        macOS
      </td>

      <td>
        WKWebView
      </td>

      <td>
        CEF, bundled with the app
      </td>
    </tr>

    <tr>
      <td>
        Linux
      </td>

      <td>
        WebKitGTK
      </td>

      <td>
        Not wired yet; builds fail early instead of silently using WebKitGTK
      </td>
    </tr>

    <tr>
      <td>
        Windows
      </td>

      <td>
        WebView2
      </td>

      <td>
        Not wired yet; builds fail early instead of silently using WebView2
      </td>
    </tr>
  </tbody>
</table>

Engines share the app API, bridge helpers, and security policy. Use runtime support queries to check host-specific capabilities.

## System WebView

```zig
.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.

On Windows the system engine is WebView2, whose Evergreen runtime is preinstalled on Windows 11 and current Windows 10; older machines need the runtime installer from the WebView2 download page (`native doctor` checks for it). The build stages the small vendored `WebView2Loader.dll` next to the app executable automatically, and `native package` includes it in the Windows artifact.

## Chromium (CEF)

Set the app engine once:

```zig
.web_engine = "chromium",
.cef = .{ .dir = "third_party/cef/<platform>", .auto_install = false },
```

```bash
native cef install
zig build run
```

macOS supports CEF as an alternative to WKWebView. It bundles a specific Chromium version. Available runtime services differ between hosts; check [Platform Support](/docs/platform-support).

Chromium is available through CEF on macOS. Linux can still use WebKitGTK with `system`, and Windows can use the native system host with `system`; Linux and Windows Chromium builds fail early until their CEF hosts are implemented.

Native-rendered surfaces stay a system-engine feature: the macOS Chromium host does not implement native child views or `gpu_surface` compositing, and those operations report unsupported instead of silently no-oping (see [Platform Support](/docs/platform-support)). Windows, child WebViews, the bridge, keyboard shortcuts, tray, dialogs, clipboard, and app timers behave the same as the system host.

### Setup

Install the runtime through the CLI:

```bash
native cef install
native doctor --manifest app.zon
```

`native cef install` downloads Native SDK's prepared CEF runtime from GitHub Releases, verifies it, and installs a complete layout. App builds currently consume the macOS layout at `third_party/cef/macos`; Linux and Windows layouts are reserved for the future CEF hosts. The prepared runtime already includes `libcef_dll_wrapper`, so app developers do not need CMake or Chromium build knowledge.

The default install uses Native SDK's pinned tested CEF version. Pin that version in your app CI or setup docs with `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:

```bash
zig build run
```

Set `.cef = .{ .dir = "third_party/cef/<platform>", .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 `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

<table>
  <thead>
    <tr>
      <th>
        Flag
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `-Dweb-engine=system`
      </td>

      <td>
        Temporarily use the platform system WebView instead of the manifest default.
      </td>
    </tr>

    <tr>
      <td>
        `-Dweb-engine=chromium`
      </td>

      <td>
        Temporarily use CEF on supported platforms. Currently supported for macOS builds.
      </td>
    </tr>

    <tr>
      <td>
        `-Dcef-dir=path`
      </td>

      <td>
        Path to the CEF distribution directory.
      </td>
    </tr>

    <tr>
      <td>
        `-Dcef-auto-install=true`
      </td>

      <td>
        Temporarily opt into running

        `native cef install`

        during Chromium builds when CEF is missing.
      </td>
    </tr>
  </tbody>
</table>

### Bundling

```bash
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

```bash
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 WebView example under CEF with automation, verifies `native.ping` over the bridge, and exercises child WebView create/setFrame/navigate/close. The package layout step verifies that a Chromium macOS package contains the framework and resources CEF expects.

`zig build test-webview-cef-link` builds the WebView example with `-Dweb-engine=chromium` without running it. Use it to check compilation and linking after platform changes. `scripts/gate.sh fast` runs it automatically whenever `src/platform/macos/` files change (macOS only; it skips with a warning when no CEF layout is installed).

## Choosing An Engine

<table>
  <thead>
    <tr>
      <th>
        Consideration
      </th>

      <th>
        System
      </th>

      <th>
        Chromium
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        Bundle size
      </td>

      <td>
        Uses the platform WebView; the loader and platform dependencies still apply.
      </td>

      <td>
        Includes the CEF distribution.
      </td>
    </tr>

    <tr>
      <td>
        Rendering consistency
      </td>

      <td>
        Varies by OS version.
      </td>

      <td>
        Consistent for apps that ship the same CEF build.
      </td>
    </tr>

    <tr>
      <td>
        Best fit
      </td>

      <td>
        Apps that can use the platform’s WebView behavior.
      </td>

      <td>
        Apps that need Chromium behavior, complex frontend stacks, or tighter rendering control.
      </td>
    </tr>
  </tbody>
</table>

## In app.zon

```zig
.web_engine = "system",
// or, on supported platforms:
.web_engine = "chromium",
.cef = .{
  .dir = "third_party/cef/<platform>",
  .auto_install = true,
},
```

---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)